MASQUE                                                       D. Schinazi
Internet-Draft                                                Google LLC
Intended status: Standards Track                               L. Pardue
Expires: 28 April 5 September 2022                                     Cloudflare
                                                         25 October 2021
                                                            4 March 2022

                       Using Datagrams with HTTP
                    draft-ietf-masque-h3-datagram-05
                    draft-ietf-masque-h3-datagram-06

Abstract

   The QUIC DATAGRAM extension provides application protocols running
   over QUIC with a mechanism to send unreliable data while leveraging
   the security and congestion-control properties of QUIC.  However,
   QUIC DATAGRAM frames do not provide a means to demultiplex
   application contexts.  This document describes how to use QUIC
   DATAGRAM frames when the application protocol running over QUIC is
   HTTP/3.  It associates datagrams with client-initiated bidirectional
   streams and defines an optional additional demultiplexing layer. HTTP/3 by association with HTTP requests.
   Additionally, this document defines how to the Capsule Protocol that can
   convey datagrams over prior versions of HTTP.

Discussion Venues

   This note is to be removed before publishing as an RFC.

   Discussion of this document takes place on the MASQUE WG mailing list
   (masque@ietf.org), which is archived at
   https://mailarchive.ietf.org/arch/browse/masque/.

   Source for this draft and an issue tracker can be found at
   https://github.com/ietf-wg-masque/draft-ietf-masque-h3-datagram.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 28 April 5 September 2022.

Copyright Notice

   Copyright (c) 2021 2022 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Simplified Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Simplified Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Conventions and Definitions . . . . . . . . . . . . . . .   4   3
   2.  Multiplexing  . . . . . . . . . . . . . . . . . . . . . . . .   4
     2.1.   3
   3.  HTTP/3 Datagram Contexts . Format  . . . . . . . . . . . . . . . . . . .   4
     2.2.  Datagram Formats  . . . . . . . . . . . . . . . . . . . .   5
     2.3.  Context ID Allocation . . . . . . . . . .
     3.1.  The H3_DATAGRAM HTTP/3 SETTINGS Parameter . . . . . . . .   5
   3.  HTTP/3 DATAGRAM Format  . . . . .
       3.1.1.  Note About Draft Versions . . . . . . . . . . . . . .   6
   4.  Capsules  . . . . . . . . . . . . . . . . . . . . . . . . . .   7   6
     4.1.  Capsule Protocol  . . . . . . . . . . . . . . . . . . . .   8   7
     4.2.  Requirements  .  Error Handling  . . . . . . . . . . . . . . . . . . . . .   9   8
     4.3.  Intermediary Processing . . . . .  The Capsule-Protocol Header Field . . . . . . . . . . . .   9   8
     4.4.  Capsule Types . . . . . . . . . . . . . . . . . . . . . .  10
       4.4.1.  The Datagram Registration Capsules  . DATAGRAM Capsule  . . . . . . . .  10
       4.4.2.  The Datagram Close Capsule . . . . . . . . . .   9
   5.  Prioritization  . . .  11
       4.4.3.  The Datagram Capsules . . . . . . . . . . . . . . . .  13
   5.  The H3_DATAGRAM HTTP/3 SETTINGS Parameter . . . .  10
   6.  Security Considerations . . . . . .  14
     5.1.  Note About Draft Versions . . . . . . . . . . . . .  11
   7.  IANA Considerations . . .  15
   6.  The Sec-Use-Datagram-Contexts HTTP Header . . . . . . . . . .  15
   7.  Prioritization . . . . . . . .  11
     7.1.  HTTP/3 SETTINGS Parameter . . . . . . . . . . . . . . .  16
   8.  Security Considerations .  11
     7.2.  HTTP/3 Error Code . . . . . . . . . . . . . . . . . .  17
   9.  IANA Considerations . .  11
     7.3.  HTTP Header Field Name  . . . . . . . . . . . . . . . . .  12
     7.4.  Capsule Types . .  17
     9.1.  HTTP/3 SETTINGS Parameter . . . . . . . . . . . . . . . .  17
     9.2.  HTTP Header Field Name . . . .  12
   8.  References  . . . . . . . . . . . . .  17
     9.3.  Capsule Types . . . . . . . . . . . .  13
     8.1.  Normative References  . . . . . . . . . .  18
     9.4.  Datagram Format Types . . . . . . . .  13
     8.2.  Informative References  . . . . . . . . . .  18
     9.5.  Context Close Codes . . . . . . .  14
   Appendix A.  Examples . . . . . . . . . . . .  19
   10. References . . . . . . . . . .  14
     A.1.  CONNECT-UDP . . . . . . . . . . . . . . .  20
     10.1.  Normative References . . . . . . . .  14
     A.2.  WebTransport  . . . . . . . . . .  20
     10.2.  Informative References . . . . . . . . . . . .  15
   Acknowledgments . . . . .  21
   Appendix A.  Examples . . . . . . . . . . . . . . . . . . . .  16
   Authors' Addresses  . .  21
     A.1.  CONNECT-UDP . . . . . . . . . . . . . . . . . . . . . . .  21
     A.2.  CONNECT-UDP with Delayed Timestamp Extension  . . . . . .  22
       A.2.1.  With Delay  . . . . . . . . . . . . . . . . . . . . .  22
     A.3.  Successful Optimistic . . . . . . . . . . . . . . . . . .  23
     A.4.  Optimistic but Unsupported  . . . . . . . . . . . . . . .  24
     A.5.  CONNECT-IP with IP compression  . . . . . . . . . . . . .  25
     A.6.  WebTransport  . . . . . . . . . . . . . . . . . . . . . .  26
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  27
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  27  16

1.  Introduction

   The QUIC DATAGRAM extension [DGRAM] provides application protocols
   running over QUIC [QUIC] with a mechanism to send unreliable data
   while leveraging the security and congestion-control properties of
   QUIC.  However, QUIC DATAGRAM frames do not provide a means to
   demultiplex application contexts.  This document describes how to use
   QUIC DATAGRAM frames when the application protocol running over QUIC
   is with HTTP/3 [H3].  It associates datagrams [H3] by association with client-initiated
   bidirectional streams and defines an optional additional
   demultiplexing layer. HTTP
   requests.  Additionally, this document defines how to the Capsule Protocol
   that can convey datagrams over prior versions of HTTP.

   This document is structured as follows:

   *  Section 2 presents core concepts for multiplexing across HTTP
      versions.

      -  Section 2.1 defines datagram contexts, an optional end-to-end
         multiplexing concept scoped to each HTTP request.  Whether
         contexts are in use is defined in Section 6.

      -  Section 2.2 defines datagram formats, which are scoped to
         contexts.  Formats communicate the format and encoding of
         datagrams sent using the associated context.

      -  Contexts are identified using a variable-length integer.
         Requirements for allocating identifier values are detailed in
         Section 2.3.

   *  Section 3 defines how QUIC DATAGRAM frames are used with HTTP/3.

      -  Section 5 3.1 defines an HTTP/3 setting that endpoints can use to
         advertise support of the frame.

   *  Section 4 introduces the Capsule Protocol and the "data stream"
      concept.  Data streams are initiated using special-purpose HTTP
      requests, after which Capsules, an end-to-end message, can be
      sent.

      -  The following  Section 4.4 defines Datagram Capsule types are defined, together types, along with guidance
         for defining specifying new types:

         o  Datagram registration capsules Section 4.4.1

         o  Datagram close capsule Section 4.4.2

         o  Datagram capsules Section 4.4.3 types.

1.1.  Conventions and Definitions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

2.  Multiplexing

   All HTTP Datagrams are associated with an HTTP request.

   When running over HTTP/3, multiple exchanges of datagrams need the
   ability to coexist on a given QUIC connection.  To allow this, HTTP
   datagrams contain two layers of multiplexing.  First, the
   QUIC DATAGRAM frame payload starts with an encoded stream identifier
   that associates the datagram with a given QUIC request stream.  Second, datagrams
   optionally carry a context identifier (see Section 2.1) that allows
   multiplexing multiple datagram contexts related to a given HTTP
   request.  Conceptually, the first layer of multiplexing is per-hop,
   while the second is end-to-end.

   When running over HTTP/2, the first level of demultiplexing is provided by the HTTP/2
   framing layer.  When running over HTTP/1, requests are strictly
   serialized in the connection, therefore the
   first layer of demultiplexing is not needed.

2.1.

3.  HTTP/3 Datagram Contexts

   Within Format

   When used with HTTP/3, the scope Datagram Data field of a given HTTP request, contexts provide an
   additional demultiplexing layer.  Contexts determine QUIC DATAGRAM
   frames uses the encoding of
   datagrams, and can be used to implicitly convey metadata.  For
   example, contexts can be used for compression to elide some parts of following format (using the datagram: notation from the context identifier then maps to a compression
   context
   "Notational Conventions" section of [QUIC]):

   HTTP/3 Datagram {
     Quarter Stream ID (i),
     HTTP Datagram Payload (..),
   }

                      Figure 1: HTTP/3 DATAGRAM Format

   Quarter Stream ID:  A variable-length integer that contains the receiver can use to reconstruct value
      of the elided data.

   While client-initiated bidirectional stream IDs are a per-hop concept, context IDs are an end-to-end
   concept.  In other words, if a that this datagram travels through one or more
   intermediaries on its way is
      associated with, divided by four (the division by four stems from client to server,
      the fact that HTTP requests are sent on client-initiated
      bidirectional streams, and those have stream ID will
   most likely change from hop to hop, but the context ID will remain
   the same.  Context IDs that are opaque to intermediaries.

   Contexts are OPTIONAL to implement for both endpoints.
   Intermediaries do not require any context-specific software to enable
   contexts.  When contexts are supported
      divisible by four).  The largest legal QUIC stream ID value is
      2^62-1, so the implementation, their
   use largest legal value of Quarter Stream ID is optional and can be selected on each stream.  Endpoints inform
   their peer of whether they wish to use contexts via the Sec-Use-
   Datagram-Contexts HTTP header, see Section 6.

   When contexts are used, they are identified within the scope 2^60-1.
      Receipt of a
   given request by frame that includes a numeric value, referred to larger value MUST be treated as the context ID.  A
   context ID is a 62-bit integer (0 to 2^62-1).

2.2.  Datagram Formats

   When
      an endpoint registers a datagram context (or the lack HTTP/3 connection error of type H3_DATAGRAM_ERROR.

   HTTP Datagram Payload:  The payload of
   contexts), it communicates the format (i.e., the datagram, whose semantics and
   encoding) of datagrams sent using this context.  This is
   acccomplished
      are defined by sending a Datagram Format Type as part individual applications.  Note that this field can
      be empty.

   Receipt of the
   datagram registration capsule, see Section 4.4.1.  This type
   identifier a QUIC DATAGRAM frame whose payload is registered with IANA (see Section 9.4) and allows
   applications that use HTTP Datagrams too short to indicate what allow
   parsing the content Quarter Stream ID field MUST be treated as an HTTP/3
   connection error of type H3_DATAGRAM_ERROR.

   Endpoints MUST NOT send HTTP/3 datagrams are.  Registration capsules carry unless the corresponding
   stream's send side is open.  On a Datagram Format
   Additional Data field which allows sending some additional
   information that would impact given endpoint, once the format receive
   side of datagrams.

   For example, a protocol which proxies IP packets stream is closed, incoming datagrams for this stream are no
   longer expected so the endpoint can define release related state.  Endpoints
   MAY keep state for a
   Datagram Format Type which represents short time to account for reordering.  Once the
   state is released, the endpoint MUST silently drop received
   associated datagrams.

   If an IP packet.  The
   corresponding Datagram Format Additional Data field would be empty.
   An extension HTTP/3 datagram is received and its Quarter Stream ID maps to such a protocol
   stream that wishes to compress IP addresses
   could define a distinct Datagram Format Type and exchange two IP
   addresses via has not yet been created, the Datagram Format Additional Data field.  Then any
   datagrams with receiver SHALL either drop
   that type would contain datagram silently or buffer it temporarily (on the IP packet with addresses
   elided.

2.3.  Context ID Allocation

   Implementations order of HTTP Datagrams that support datagram contexts MUST
   provide a context ID allocation service.  That service will allow
   applications co-located with HTTP to request a unique context ID that
   they can subsequently use for their own purposes.  The HTTP
   implementation will then parse
   round trip) while awaiting the context ID creation of incoming HTTP
   Datagrams and use it to deliver the frame to the appropriate
   application context.

   Even-numbered context IDs are client-initiated, while odd-numbered
   context IDs are server-initiated.  This means that corresponding stream.

   If an HTTP client
   implementation of the context ID allocation service MUST only provide
   even-numbered IDs, while a server implementation MUST only provide
   odd-numbered IDs.  Note that, once allocated, any context ID can be
   used by both client HTTP/3 datagram is received and server - only allocation carries separate
   namespaces to avoid requiring synchronization.  Additionally, note
   that the context its Quarter Stream ID namespace is tied maps to a given HTTP request: it is
   possible for the same numeral context ID
   stream that cannot be created due to client-initiated bidirectional
   stream limits, it SHOULD be used simultaneously in
   distinct requests.

3. treated as an HTTP/3 DATAGRAM Format

   When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM
   frames uses the following format (using the notation from the
   "Notational Conventions" section connection error of [QUIC]):

   HTTP/3 Datagram {
     Quarter Stream ID (i),
     [Context ID (i)],
     HTTP Datagram Payload (..),
   }

                      Figure 1:
   type H3_ID_ERROR.  Generating an error is not mandatory in this case
   because HTTP/3 DATAGRAM Format

   Quarter Stream ID:  A variable-length integer that contains the value
      of implementations might have practical barriers to
   determining the client-initiated bidirectional active stream concurrency limit that this datagram is
      associated with, divided by four (the division applied by four stems from
   the fact that HTTP requests are QUIC layer.

   HTTP/3 datagrams MUST only be sent on client-initiated
      bidirectional streams, and those have with an association to a stream IDs
   that are
      divisible by four).  The largest legal QUIC stream ID value is
      2^62-1, so supports semantics for HTTP Datagrams.  For example, existing
   HTTP methods GET and POST do not define semantics for associated HTTP
   Datagrams; therefore, HTTP/3 datagrams cannot be sent associated with
   GET or POST request streams.  If an endpoint receives an HTTP/3
   datagram associated with a method that has no known semantics for
   HTTP Datagrams, it MUST abort the largest legal value of Quarter Stream ID is 2^62-1
      / 4.  Receipt corresponding stream with
   H3_DATAGRAM_ERROR.  Future extensions MAY remove these requirements
   if they define semantics for such HTTP Datagrams and negotiate mutual
   support.

3.1.  The H3_DATAGRAM HTTP/3 SETTINGS Parameter

   Implementations of a frame HTTP/3 that includes support HTTP Datagrams can indicate
   that to their peer by sending the H3_DATAGRAM SETTINGS parameter with
   a larger value MUST be
      treated as a connection error of type FRAME_ENCODING_ERROR.

   Context ID:  A variable-length integer indicating the context ID 1.  The value of the datagram (see Section 2.1).  Whether H3_DATAGRAM SETTINGS parameter MUST
   be either 0 or 1.  A value of 0 indicates that HTTP Datagrams are not this field
   supported.  An endpoint that receives the H3_DATAGRAM SETTINGS
   parameter with a value that is
      present depends on whether datagram contexts are in use on this
      stream, see Section 6.  If this neither 0 or 1 MUST terminate the
   connection with error H3_SETTINGS_ERROR.

   Endpoints MUST NOT send QUIC DATAGRAM frame is reordered frames until they have both
   sent and arrives before received the receiver knows whether datagram contexts
      are in H3_DATAGRAM SETTINGS parameter with a value of
   1.

   When clients use on this stream, then the receiver cannot parse this
      datagram and 0-RTT, they MAY store the receiver MUST either drop that datagram silently
      or buffer it temporarily.

   HTTP Datagram Payload:  The payload value of the datagram, whose semantics
      are defined by individual applications.  Note that this field can
      be empty.

   Intermediaries parse server's
   H3_DATAGRAM SETTINGS parameter.  Doing so allows the Quarter Stream ID field in order client to
   associate the QUIC DATAGRAM frame with a stream.  If an intermediary
   receives a send
   QUIC DATAGRAM frame whose payload is too short frames in 0-RTT packets.  When servers decide to allow
   parsing the Quarter Stream ID field, the intermediary accept
   0-RTT data, they MUST treat it
   as an HTTP/3 connection error of type H3_GENERAL_PROTOCOL_ERROR.  The
   Context ID field is optional and whether it is present send a H3_DATAGRAM SETTINGS parameter greater
   than or not is
   decided end-to-end by the endpoints, see Section 6.  Therefore
   intermediaries cannot know whether equal to the Context ID field is present or
   absent and value they MUST ignore any HTTP/3 Datagram fields after the
   Quarter Stream ID.

   Endpoints parse both the Quarter Stream ID field and sent to the Context ID
   field client in order to associate the QUIC DATAGRAM frame with a stream and
   context within that stream. connection
   where they sent them the NewSessionTicket message.  If an endpoint receives a QUIC DATAGRAM
   frame whose payload is too short to allow parsing client
   stores the Quarter Stream
   ID field, value of the endpoint H3_DATAGRAM SETTINGS parameter with their
   0-RTT state, they MUST treat it as an HTTP/3 connection error validate that the new value of
   type H3_GENERAL_PROTOCOL_ERROR.  If an endpoint receives a QUIC
   DATAGRAM frame whose payload is long enough to allow parsing the
   Quarter Stream ID field but too short H3_DATAGRAM
   SETTINGS parameter sent by the server in the handshake is greater
   than or equal to allow parsing the Context ID
   field, stored value; if not, the endpoint client MUST abruptly terminate
   the corresponding stream connection with a stream error H3_SETTINGS_ERROR.  In all cases, the
   maximum permitted value of type H3_GENERAL_PROTOCOL_ERROR.

   Endpoints MUST NOT send HTTP/3 datagrams unless the corresponding
   stream's send side H3_DATAGRAM SETTINGS parameter is open.  On 1.

   It is RECOMMENDED that implementations that support receiving HTTP
   Datagrams using QUIC always send the H3_DATAGRAM SETTINGS parameter
   with a given endpoint, once value of 1, even if the receive
   side application does not intend to use
   HTTP Datagrams.  This helps to avoid "sticking out"; see Section 6.

3.1.1.  Note About Draft Versions

   [[RFC editor: please remove this section before publication.]]

   Some revisions of this draft specification use a stream is closed, incoming datagrams different value (the
   Identifier field of a Setting in the HTTP/3 SETTINGS frame) for this stream are no
   longer expected so the endpoint can release related state.  Endpoints
   H3_DATAGRAM Settings Parameter.  This allows new draft revisions to
   make incompatible changes.  Multiple draft versions MAY keep state for be supported
   by either endpoint in a short time to account connection.  Such endpoints MUST send
   multiple values for reordering. H3_DATAGRAM.  Once an endpoint has sent and
   received SETTINGS, it MUST compute the
   state is released, intersection of the endpoint values it
   has sent and received, and then it MUST silently drop received
   associated datagrams.

   If an HTTP/3 datagram is received select and its Quarter Stream ID maps to a
   stream that has not yet been created, use the receiver SHALL either drop
   that datagram silently or buffer it temporarily while awaiting most
   recent draft version from the
   creation of intersection set.  This ensures that
   both endpoints negotiate the corresponding stream. same draft version.

4.  Capsules

   This specification introduces the Capsule Protocol.  The Capsule
   Protocol is a sequence of type-length-value tuples that new HTTP
   Upgrade Tokens (see Section 16.7 of [HTTP]) can choose to use.  It
   allows endpoints to reliably communicate request-related information end-to-
   end,
   end-to-end on HTTP request streams, even in the presence of HTTP
   intermediaries.

4.1.  The Capsule Protocol

   This specification defines the "data stream" of an can be used to exchange HTTP
   Datagrams when HTTP is running over a transport that does not support
   the QUIC DATAGRAM frame.

   This specification defines the "data stream" of an HTTP request as
   the bidirectional stream of bytes that follow the headers in both
   directions.  In HTTP/1.x, the data stream consists of all bytes on
   the connection that follow the blank line that concludes either the
   request header section, or the 2xx (Successful) response header
   section.  (Note that only a single HTTP request starting the capsule
   protocol can be sent on HTTP/1.x connections.)  In HTTP/2 and HTTP/3,
   the data stream of a given HTTP request consists of all bytes sent in
   DATA frames with the corresponding stream ID.  The concept of a data
   stream is particularly relevant for methods such as CONNECT where
   there is no HTTP message content after the headers.

   Definitions

   Note that use of the Capsule Protocol is not required to use HTTP
   Datagrams.  If a new HTTP Methods or Upgrade Token is only defined over
   transports that support QUIC DATAGRAM frames, they might not need a
   stream encoding.  Additionally, definitions of new HTTP Upgrade
   Tokens can use HTTP Datagrams with their own data stream protocol.

   However, new HTTP Upgrade Tokens that wish to use HTTP Datagrams
   SHOULD use the Capsule Protocol unless they have a good reason not
   to.

4.1.  Capsule Protocol

   Definitions of new HTTP Upgrade Tokens can state that their data
   stream uses the Capsule Protocol.  If they do so, that means that the
   contents of their data stream uses the following format (using the
   notation from the "Notational Conventions" section of [QUIC]):

   Capsule Protocol {
     Capsule (..) ...,
   }

                  Figure 2: Capsule Protocol Stream Format

   Capsule {
     Capsule Type (i),
     Capsule Length (i),
     Capsule Value (..),
   }

                          Figure 3: Capsule Format

   Capsule Type:  A variable-length integer indicating the Type of the
      capsule.  Endpoints that receive a capsule with an unknown Capsule
      Type MUST silently skip over that capsule.

   Capsule Length:  The length of the Capsule Value field following this
      field, encoded as a variable-length integer.  Note that this field
      can have a value of zero.

   Capsule Value:  The payload of this capsule.  Its semantics are
      determined by the value of the Capsule Type field.

4.2.  Requirements

   If

   Because new protocols or extensions may involve defining new capsule
   types, intermediaries that wish to allow for future extensibility
   SHOULD forward capsules unmodified.  One exception to this rule is
   the definition DATAGRAM capsule; see Section 4.4.  An intermediary can identify
   the use of an HTTP Method the capsule protocol either through the presence of the
   Capsule-Protocol header field (Section 4.3) or by understanding the
   chosen HTTP Upgrade Token states token.  An intermediary that
   it uses identifies the use
   of the capsule protocol, its implementations protocol MAY convert between DATAGRAM capsules and
   QUIC DATAGRAM frames when forwarding.  Definitions of new Capsule
   Types MAY specify optional custom intermediary processing.

   Endpoints which receive a Capsule with an unknown Capsule Type MUST follow
   silently drop that Capsule.

   By virtue of the
   following requirements:

   *  A server MUST NOT send any Transfer-Encoding or Content-Length
      header fields definition of the data stream, the Capsule Protocol
   is not in use on responses unless the response includes a 2xx
   (Successful) response.  If a client
      receives a Content-Length status code.

   The Capsule Protocol MUST NOT be used with messages that contain
   Content-Length, Content-Type, or Transfer-Encoding header fields in a
      successful response, it fields.
   Additionally, HTTP status codes 204 (No Content), 205 (Reset
   Content), and 206 (Partial Content) MUST treat NOT be sent on responses
   that response as malformed.

   *  A request message does not have content.

   *  A successful response message does not have content.

   *  Responses are not cacheable.

4.3.  Intermediary Processing

   Intermediaries MUST operate in one of the two following modes:

   Pass-through mode:  In this mode, the intermediary forwards use the data
      stream between two associated streams without any modification of Capsule Protocol.

4.2.  Error Handling

   When an error occurs processing the data stream.

   Participant mode:  In this mode, capsule protocol, the intermediary terminates receiver
   MUST treat the data
      stream and parses all Capsule Type and Capsule Length fields it
      receives.

   Each Capsule Type determines whether it is opaque message as malformed or transparent incomplete, according to
   intermediaries in participant mode: opaque capsules are forwarded
   unmodified while transparent ones can be parsed, added, or removed by
   intermediaries.  Intermediaries MAY modify the contents of
   underlying transport protocol.  For HTTP/3, the
   Capsule Data field handling of transparent capsule types.

   Unless otherwise specified, all Capsule Types are defined as opaque
   to intermediaries.  Intermediaries MUST forward all received opaque
   CAPSULE frames in their unmodified entirety.  Intermediaries MUST NOT
   send any opaque CAPSULE frames other than the ones it malformed
   messages is forwarding.
   All Capsule Types defined described in this document are opaque, with the
   exception of the datagram capsules, see Section 4.4.3.  Definitions 4.1.3 of new Capsule Types MAY specify that [H3].  For HTTP/2, the newly introduced type
   handling of malformed messages is
   transparent.  Intermediaries MUST treat unknown Capsule Types as
   opaque.

   Intermediaries respect described in Section 8.1.1 of [H2].
   For HTTP/1.1, the order handling of opaque CAPSULE frames: if an
   intermediary receives two opaque CAPSULE frames incomplete messages is described in a given order, it
   Section 8 of [H1].

   Each capsule's payload MUST forward them contain exactly the fields identified in
   its description.  A capsule payload that contains additional bytes
   after the same order.

   Endpoints which receive identified fields or a Capsule with an unknown Capsule Type MUST
   silently drop capsule payload that Capsule.

4.4.  Capsule Types

4.4.1.  The Datagram Registration Capsules

   This document defines the REGISTER_DATAGRAM and
   REGISTER_DATAGRAM_CONTEXT capsules types, known collectively as the
   datagram registration capsules (see Section 9.3 for terminates
   before the value end of the
   capsule types).  The REGISTER_DATAGRAM capsule is used by endpoints identified fields MUST be treated as a
   malformed or incomplete message.  In particular, redundant length
   encodings MUST be verified to inform their peer of be self-consistent.

   When a stream carrying capsules terminates cleanly, if the encoding and semantics of all datagrams
   associated with last
   capsule on the stream was truncated, this MUST be treated as a stream.
   malformed or incomplete message.

4.3.  The REGISTER_DATAGRAM_CONTEXT capsule is
   used by endpoints to inform their peer of Capsule-Protocol Header Field

   This document defines the encoding and semantics "Capsule-Protocol" header field.  It is an
   Item Structured Field, see Section 3.3 of all datagrams associated with [STRUCT-FIELD]; its value
   MUST be a given context ID on this stream.

   Datagram Registration Capsule {
     Type (i) Boolean.  Its ABNF is:

   Capsule-Protocol = REGISTER_DATAGRAM or REGISTER_DATAGRAM_CONTEXT,
     Length (i),
     [Context ID (i)],
     Datagram Format Type (i),
     Datagram Format Additional Data (..),
   }

             Figure 4: REGISTER_DATAGRAM_CONTEXT Capsule Format

   Context ID:  A variable-length integer indicating sf-item
   Endpoints indicate that the context ID to
      register (see Section 2.1).  This field Capsule Protocol is present in
      REGISTER_DATAGRAM_CONTEXT capsules but not in REGISTER_DATAGRAM
      capsules.  If a REGISTER_DATAGRAM capsule is used use on a stream
      where datagram contexts are in use, it is associated with context
      ID 0.  REGISTER_DATAGRAM_CONTEXT capsules MUST NOT carry context
      ID 0 as that context ID is conveyed using the REGISTER_DATAGRAM
      capsule.

   Datagram Format Type:  A variable-length integer that defines the
      semantics and encoding of data
   stream by sending the HTTP Datagram Payload Capsule-Protocol header field of
      datagrams with this context ID, see Section 2.2.

   Datagram Format Additional Data:  This field carries additional
      information that impact the format a value of datagrams
   ?1.  A Capsule-Protocol header field with this context
      ID, see Section 2.2.

   Note that these registrations are unilateral and bidirectional: the
   sender a value of ?0 has the capsule unilaterally defines the same
   semantics it will
   apply to as when the datagrams it sends and receives using this context ID.
   Once a context ID header is registered, it can be used in both directions.

   Endpoints MUST NOT send HTTP Datagrams until they have either sent or
   received a datagram registration capsule with the same Context ID.
   However, reordering can cause HTTP Datagrams not present.  Intermediaries MAY use
   this header field to be received with an
   unknown Context ID.  Receipt allow processing of such HTTP datagrams MUST NOT be
   treated as an error.  Endpoints SHALL drop the Datagrams for unknown
   HTTP Datagram
   silently, or buffer it temporarily while awaiting the corresponding
   datagram registration capsule.  Intermediaries SHALL drop the Upgrade Tokens; note that this is only possible for HTTP
   Datagram silently, MAY buffer it, Upgrade
   or forward it on immediately.

   Endpoints Extended CONNECT.

   The Capsule-Protocol header field MUST NOT register the same Context ID twice be sent multiple times on the same
   stream.  This also applies to Context IDs that have been closed using
   a CLOSE_DATAGRAM_CONTEXT capsule.  Clients MUST NOT register server-
   initiated Context IDs and servers message.  The Capsule-Protocol header field MUST NOT register client-initiated
   Context IDs.  If an endpoint receives a REGISTER_DATAGRAM_CONTEXT
   capsule that violates one or more of these requirements, the endpoint
   MUST abruptly terminate the corresponding stream be used on
   HTTP responses with a stream error
   of type H3_GENERAL_PROTOCOL_ERROR.

   If datagrams contexts are status code different from 2xx (Successful).
   This specification does not in use, the client is responsible define any parameters for
   choosing the datagram format and informing the server via a
   REGISTER_DATAGRAM capsule.  Servers Capsule-
   Protocol header field value, but future documents MAY define
   parameters.  Receivers MUST NOT send the
   REGISTER_DATAGRAM capsule.  If a client receives a REGISTER_DATAGRAM
   capsule, ignore unknown parameters.

   Definitions of new HTTP Upgrade Tokens that use the client MUST abruptly terminate Capsule Protocol
   MAY use the corresponding stream
   with a stream error of type H3_GENERAL_PROTOCOL_ERROR.

4.4.2. Capsule-Protocol header field to simplify intermediary
   processing.

4.4.  The Datagram Close DATAGRAM Capsule

   The CLOSE_DATAGRAM_CONTEXT

   This document defines the DATAGRAM capsule type (see Section 9.3 7.4 for
   the value of the capsule type) type).  This capsule allows an endpoint to inform its peer that it will
   no longer
   send or parse received datagrams associated with an HTTP Datagram on a given
   context ID.

   CLOSE_DATAGRAM_CONTEXT Capsule {
     Type (i) = CLOSE_DATAGRAM_CONTEXT,
     Length (i),
     Context ID (i),
     Close Code (i),
     Close Details (..),
   }

              Figure 5: CLOSE_DATAGRAM_CONTEXT stream using the Capsule Format

   Context ID:  The context ID to close.

   Close Code:  The close code allows an endpoint to provide additional
      information as to why a datagram context was closed.
      Section 4.4.2.1 defines a set of codes, the circumstances under
      which an implementation sends them, and how receivers react.

   Close Details: Protocol.  This
   is meant for debugging purposes.  It consists of particularly useful when HTTP is running over a human-readable string encoded in UTF-8.

   Note transport that this close is unilateral and bidirectional: the sender of
   does not support the frame unilaterally informs its peer QUIC DATAGRAM frame.

   Datagram Capsule {
     Type (i) = DATAGRAM,
     Length (i),
     HTTP Datagram Payload (..),
   }

                     Figure 4: DATAGRAM Capsule Format

   HTTP Datagram Payload:  The payload of the closure.  Endpoints
   can use CLOSE_DATAGRAM_CONTEXT capsules to close a context that was
   initially registered by either themselves, or datagram, whose semantics
      are defined by their peer.
   Endpoints MAY use the CLOSE_DATAGRAM_CONTEXT capsule to immediately
   reject a context individual applications.  Note that was just registered this field can
      be empty.

   Datagrams sent using a
   REGISTER_DATAGRAM_CONTEXT the DATAGRAM capsule if they find its Datagram Format
   Type field have the same semantics as
   datagrams sent in QUIC DATAGRAM frames.  In particular, the
   restrictions on when it is allowed to be unacceptable.

   After send an endpoint has either HTTP Datagram and how
   to process them from Section 3 also apply to HTTP Datagrams sent or and
   received a
   CLOSE_DATAGRAM_CONTEXT frame, it MUST NOT send any using the DATAGRAM capsule.

   An intermediary can reencode HTTP Datagrams
   with that Context ID.  However, due to reordering, an endpoint that
   receives as it forwards them.  In
   other words, an HTTP Datagram with intermediary MAY send a closed Context ID MUST NOT treat it
   as DATAGRAM capsule to forward
   an error, it SHALL instead drop the HTTP Datagram silently.

   Endpoints MUST NOT close a Context ID that which was not previously
   registered.  Endpoints MUST NOT close received in a Context ID QUIC DATAGRAM frame, and
   vice versa.

   Note that has already
   been closed.  If an endpoint receives a CLOSE_DATAGRAM_CONTEXT
   capsule while DATAGRAM capsules that violates one or more of these requirements, the endpoint
   MUST abruptly terminate the corresponding stream with are sent on a stream error
   of type H3_GENERAL_PROTOCOL_ERROR.

4.4.2.1.  Close Codes

   Close codes are intended to allow implementations to react
   differently
   reliably delivered in order, intermediaries can reencode DATAGRAM
   capsules into QUIC DATAGRAM frames when they receive them - for example, some close codes
   require the receiver to not open another context under certain
   conditions.

   This specification defines the close codes below.  Their numeric
   values are forwarding messages, which
   could result in Section 9.5.  Extensions to this mechanism MAY define
   new close codes loss or reordering.

   If an intermediary receives an HTTP Datagram in a QUIC DATAGRAM frame
   and they SHOULD state how receivers react to them.

   NO_ERROR:  This indicates that is forwarding it on a context was closed without any
      action specified for the receiver.

   UNKNOWN_FORMAT:  This indicates connection that supports QUIC DATAGRAM
   frames, the sender does not know how to
      interpret the datagram format type associated with this context.
      The endpoint that had originally registered this context MUST intermediary SHOULD NOT
      try to register another context with the same datagram format type
      on this stream.

   DENIED:  This indicates convert that HTTP Datagram to a
   DATAGRAM capsule.  If the sender has rejected HTTP Datagram is too large to fit in a
   DATAGRAM frame (for example because the context
      registration based on its local policy.  The endpoint path MTU of that had
      originally registered this context MUST NOT try to register
      another context with QUIC
   connection is too low or if the same datagram format type and datagram
      format data maximum UDP payload size advertised
   on this stream.

   RESOURCE_LIMIT:  This indicates that connection is too low), the context was closed to save
      resources.  The recipient intermediary SHOULD limit its future registration of
      resource-intensive contexts.

   Receipt of an unknown close code MUST be treated as if drop the NO_ERROR
   code was present.  Close codes are registered with IANA, see
   Section 9.5.

4.4.3.  The HTTP
   Datagram Capsules

   This document defines the DATAGRAM and DATAGRAM_WITH_CONTEXT capsules
   types, known collectively as the datagram capsules (see Section 9.3
   for the value instead of the capsule types).  These capsules allow an
   endpoint converting it to send a datagram frame over an HTTP stream. DATAGRAM capsule.  This is
   particularly useful when using a version of HTTP
   preserves the end-to-end unreliability characteristic that does not
   support methods
   such as Datagram Packetization Layer Path MTU Discovery (DPLPMTUD)
   depend on [DPLPMTUD].  An intermediary that converts QUIC DATAGRAM frames.

   Datagram Capsule {
     Type (i) =
   frames to DATAGRAM or DATAGRAM_WITH_CONTEXT,
     Length (i),
     [Context ID (i)], capsules allows HTTP Datagram Payload (..),
   }

                     Figure 6: DATAGRAM Capsule Format

   Context ID:  A variable-length integer indicating the context ID of Datagrams to be arbitrarily
   large without suffering any loss; this can misrepresent the datagram (see Section 2.1).  This field is present in
      DATAGRAM_WITH_CONTEXT capsules but not in true path
   properties, defeating methods such as DPLPMTUD.

   While DATAGRAM capsules.  If capsules can theoretically carry a payload of length
   2^62-1, most applications will have their own limits on what datagran
   payload sizes are practical.  Implementations SHOULD take those
   limits into account when parsing DATAGRAM capsules: if an incoming
   DATAGRAM capsule is used on has a stream where datagram contexts are
      in use, it is associated with context ID 0.  DATAGRAM_WITH_CONTEXT
      capsules MUST NOT carry context ID 0 as length that context ID is
      conveyed using known to be so large as to not
   be usable, the DATAGRAM capsule.

   HTTP Datagram Payload:  The payload of implementation SHOULD discard the datagram, whose semantics
      are defined by individual applications.  Note that this field capsule without
   buffering its contents into memory.

5.  Prioritization

   Data streams (see Section 4.1) can be empty.

   Datagrams sent prioritized using the datagram capsule have the exact same
   semantics as any means
   suited to stream or request prioritization.  For example, see
   Section 11 of [PRIORITY].

   Prioritization of HTTP/3 datagrams sent in QUIC DATAGRAM frames.  In particular,
   the restrictions on when it is allowed not defined in this document.
   Future extensions MAY define how to send an HTTP Datagram prioritize datagrams, and
   how MAY
   define signaling to process them from Section 3 also apply allow endpoints to communicate their
   prioritization preferences.

6.  Security Considerations

   Since transmitting HTTP Datagrams sent
   and received using the datagram capsules.

   The datagram capsules are transparent to intermediaries, meaning that
   intermediaries MAY parse them and send datagram capsules that they
   did not receive.  This allows QUIC DATAGRAM frames requires
   sending an intermediary to reencode HTTP
   Datagrams as HTTP/3 Settings parameter, it forwards them: in "sticks out".  In other
   words, an intermediary MAY
   send a datagram capsule to forward an HTTP Datagram which was
   received in a QUIC DATAGRAM frame, and vice versa.

   Note that while datagram capsules are sent on a stream,
   intermediaries probing clients can reencode learn whether a server supports HTTP
   Datagrams into QUIC DATAGRAM frames over the next hop, and those could be dropped.  Because of this,
   applications have to always consider HTTP Datagrams to be unreliable,
   even if they were initially sent in a capsule.

   If an intermediary receives an HTTP Datagram in a QUIC DATAGRAM frame
   and is forwarding it on a connection that supports QUIC DATAGRAM
   frames, frames.  As some servers might wish to
   obfuscate the intermediary SHOULD NOT convert fact that they offer application services that use HTTP Datagram
   datagrams, it's best for all implementations that support this
   feature to a
   DATAGRAM capsule.  If always send this Settings parameter, see Section 3.1.

   Since use of the Capsule Protocol is restricted to new HTTP Datagram Upgrade
   Tokens, it is too large not accessible from Web Platform APIs (such as those
   commonly accessed via JavaScript in web browsers).

7.  IANA Considerations

7.1.  HTTP/3 SETTINGS Parameter

   This document will request IANA to fit register the following entry in a
   DATAGRAM frame (for example because
   the path MTU of "HTTP/3 Settings" registry:

   Value:  0xffd277 (note that QUIC
   connection is too low or if the maximum UDP payload size advertised
   on that connection is too low), the intermediary SHOULD drop the HTTP
   Datagram instead of converting it this will switch to a DATAGRAM capsule. lower value before
      publication)

   Setting Name:  H3_DATAGRAM

   Default:  0

   Status:  provisional (permanent if this document is approved)

   Specification:  This
   preserves the end-to-end unreliability characteristic that methods
   such as Datagram Packetization Layer Path MTU Discovery (DPLPMTUD)
   depend on [RFC8899].  An intermediary that converts QUIC DATAGRAM
   frames to datagram capsules allows Document

   Change Controller:  IETF

   Contact:  HTTP_WG; HTTP Datagrams working group; ietf-http-wg@w3.org

7.2.  HTTP/3 Error Code

   This document will request IANA to be arbitrarily
   large without suffering any loss; this can misrepresent register the true path
   properties, defeating methods such a DPLPMTUD.

5.  The H3_DATAGRAM HTTP/3 SETTINGS Parameter

   Implementations of HTTP/3 following entry in
   the "HTTP/3 Error Codes" registry:

   Value:  0x4A1268 (note that support this will switch to a lower value before
      publication)

   Name:  H3_DATAGRAM_ERROR

   Description:  Datagram or capsule protocol parse error
   Status:  provisional (permanent if this document is approved)

   Specification:  This Document

   Change Controller:  IETF

   Contact:  HTTP_WG; HTTP Datagrams can indicate
   that working group; ietf-http-wg@w3.org

7.3.  HTTP Header Field Name

   This document will request IANA to their peer by sending register the H3_DATAGRAM SETTINGS parameter with following entry in
   the "HTTP Field Name" registry:

   Field Name:  Capsule-Protocol

   Template:  None

   Status:  provisional (permanent if this document is approved)

   Reference:  This document

   Comments:  None

7.4.  Capsule Types

   This document establishes a value of 1. registry for HTTP capsule type codes.
   The value of the H3_DATAGRAM SETTINGS parameter "HTTP Capsule Types" registry governs a 62-bit space.
   Registrations in this registry MUST
   be either 0 or 1. include the following fields:

   Type:  A name or label for the capsule type.

   Value:  The value of 0 indicates that HTTP Datagrams are not
   supported.  An endpoint that receives the H3_DATAGRAM SETTINGS
   parameter with a value that is neither 0 or 1 MUST terminate Capsule Type field (see Section 4.1) is a
      62-bit integer.

   Reference:  An optional reference to a specification for the
   connection with error H3_SETTINGS_ERROR.

   Endpoints type.
      This field MAY be empty.

   Registrations follow the "First Come First Served" policy (see
   Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT send QUIC DATAGRAM frames until they have both
   sent and received
   the H3_DATAGRAM SETTINGS parameter same Type.

   This registry initially contains the following entry:

                +==============+==========+===============+
                | Capsule Type | Value    | Specification |
                +==============+==========+===============+
                | DATAGRAM     | 0xff37a5 | This Document |
                +--------------+----------+---------------+

                  Table 1: Initial Capsule Types Registry

   Capsule types with a value of
   1.

   When clients use 0-RTT, they MAY store the value form 41 * N + 23 for integer values
   of the server's
   H3_DATAGRAM SETTINGS parameter.  Doing so allows the client to send
   QUIC DATAGRAM frames in 0-RTT packets.  When servers decide to accept
   0-RTT data, they MUST send a H3_DATAGRAM SETTINGS parameter greater
   than or equal to the value they sent N are reserved to exercise the client in the connection
   where they sent them the NewSessionTicket message.  If a client
   stores the value of the H3_DATAGRAM SETTINGS parameter with their
   0-RTT state, they MUST validate requirement that the new value of the H3_DATAGRAM
   SETTINGS parameter sent unknown capsule
   types be ignored.  These capsules have no semantics and can carry
   arbitrary values.  These values MUST NOT be assigned by the server in the handshake is greater
   than or equal to the stored value; if not, the client IANA and MUST terminate
   the connection with error H3_SETTINGS_ERROR.  In all cases,
   NOT appear in the
   maximum permitted value listing of the H3_DATAGRAM SETTINGS parameter is 1.

5.1.  Note About Draft Versions

   [[RFC editor: please remove this section before publication.]]

   Some revisions of this draft specification use a different value (the
   Identifier field of a Setting in the HTTP/3 SETTINGS frame) for the
   H3_DATAGRAM Settings Parameter.  This allows new draft revisions assigned values.

8.  References

8.1.  Normative References

   [DGRAM]    Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable
              Datagram Extension to
   make incompatible changes.  Multiple draft versions MAY be supported
   by either endpoint QUIC", Work in a connection.  Such endpoints MUST send
   multiple values for H3_DATAGRAM.  Once an endpoint has sent Progress, Internet-
              Draft, draft-ietf-quic-datagram-10, 4 February 2022,
              <https://datatracker.ietf.org/doc/html/draft-ietf-quic-
              datagram-10>.

   [H1]       Fielding, R. T., Nottingham, M., and
   received SETTINGS, it MUST compute the intersection of the values it
   has sent J. Reschke,
              "HTTP/1.1", Work in Progress, Internet-Draft, draft-ietf-
              httpbis-messaging-19, 12 September 2021,
              <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
              messaging-19>.

   [H2]       Thomson, M. and received, C. Benfield, "HTTP/2", Work in Progress,
              Internet-Draft, draft-ietf-httpbis-http2bis-07, 24 January
              2022, <https://datatracker.ietf.org/doc/html/draft-ietf-
              httpbis-http2bis-07>.

   [H3]       Bishop, M., "Hypertext Transfer Protocol Version 3
              (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf-
              quic-http-34, 2 February 2021,
              <https://datatracker.ietf.org/doc/html/draft-ietf-quic-
              http-34>.

   [HTTP]     Fielding, R. T., Nottingham, M., and then it MUST select J. Reschke, "HTTP
              Semantics", Work in Progress, Internet-Draft, draft-ietf-
              httpbis-semantics-19, 12 September 2021,
              <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
              semantics-19>.

   [IANA-POLICY]
              Cotton, M., Leiba, B., and use the most
   recent draft version from the intersection set.  This ensures that
   both endpoints negotiate the same draft version.

6.  The Sec-Use-Datagram-Contexts HTTP Header

   Endpoints indicate their support T. Narten, "Guidelines for datagram contexts by sending the
   Sec-Use-Datagram-Contexts header with a value of ?1.  If the header
   is missing or has a value different from ?1, that indicates that its
   sender does not wish to use datagram contexts.  Endpoints that wish
   to use datagram contexts SHALL send the Sec-Use-Datagram-Contexts
   header with a value of ?1 on requests and responses that use the
   capsule protocol.

   "Sec-Use-Datagram-Contexts" is
              Writing an Item Structured Header [RFC8941].
   Its value MUST be a Boolean, its ABNF is:

   Sec-Use-Datagram-Contexts = sf-boolean

   The REGISTER_DATAGRAM_CONTEXT, DATAGRAM_WITH_CONTEXT, and
   CLOSE_DATAGRAM_CONTEXT capsules as refered to as context-related
   capsules.  Endpoints which do not wish to use contexts MUST NOT send
   context-related capsules, IANA Considerations Section in RFCs", BCP 26,
              RFC 8126, DOI 10.17487/RFC8126, June 2017,
              <https://www.rfc-editor.org/rfc/rfc8126>.

   [QUIC]     Iyengar, J., Ed. and MUST silently ignore any received
   context-related capsules.

   Both endpoints unilaterally decide whether they wish to use datagram
   contexts on a given stream.  Contexts are used on a given stream if M. Thomson, Ed., "QUIC: A UDP-Based
              Multiplexed and only if both endpoints indicate they wish to use them on this
   stream.  Once an endpoint has received the HTTP request or response,
   it knows whether datagram contexts are in use on this stream or not.

   Conceptually, when datagram contexts are not in use on a stream, all
   datagrams use context ID 0, which is client-initiated.  This means
   that the client chooses the datagram format Secure Transport", RFC 9000,
              DOI 10.17487/RFC9000, May 2021,
              <https://www.rfc-editor.org/rfc/rfc9000>.

   [RFC2119]  Bradner, S., "Key words for all datagrams when
   datagram contexts are not in use.

   If datagram contexts are not in use on a stream, endpoints MUST NOT
   send context-related capsules to the peer on that stream.  Clients
   MAY optimistically send context-related capsules before learning
   whether the server wishes to support datagram contexts or not.

   This allows a client in RFCs to optimistically use extensions that rely on
   datagram contexts without knowing a priori whether the server
   supports them, Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

   [STRUCT-FIELD]
              Nottingham, M. and without incurring a latency cost to negotiate
   extension support.  In this scenario, the client would send its
   request with the Sec-Use-Datagram-Contexts header set to ?1, and
   register two datagram contexts: the main context would use context ID
   0 and the extension context would use context ID 2.  The client then
   sends a REGISTER_DATAGRAM capsule to register the main context, and a
   REGISTER_DATAGRAM_CONTEXT to register the extension context.  The
   client can then immediately send DATAGRAM capsules to send main
   datagrams and DATAGRAM_WITH_CONTEXT capsules to send extension
   datagrams.

   *  If the server wishes to use datagram contexts, it will set Sec-
      Use-Datagram-Contexts to ?1 on its response and correctly parse
      all the received capsules.

   *  If the server does not wish to use datagram contexts (for example
      if the server implementation does not support them), it will not
      set Sec-Use-Datagram-Contexts to ?1 on its response.  It will then
      parse the REGISTER_DATAGRAM and DATAGRAM capsules without datagram
      contexts being in use on this stream, and parse the main datagrams
      correctly while silently dropping the extension datagrams.  Once
      the client receives the server's response, it will know datagram
      contexts are not in use, P-H. Kamp, "Structured Field Values for
              HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,
              <https://www.rfc-editor.org/rfc/rfc8941>.

8.2.  Informative References

   [DPLPMTUD] Fairhurst, G., Jones, T., Tüxen, M., Rüngeler, I., and then will be able to send HTTP
      Datagrams via the QUIC DATAGRAM frame.

   Extensions MAY define a different mechanism to communicate whether
   contexts are in use, T.
              Völker, "Packetization Layer Path MTU Discovery for
              Datagram Transports", RFC 8899, DOI 10.17487/RFC8899,
              September 2020, <https://www.rfc-editor.org/rfc/rfc8899>.

   [PRIORITY] Oku, K. and they MAY do so in a way which is opaque to
   intermediaries.

7.  Prioritization

   Data streams (see Section 4.1) can be prioritized using any means
   suited to stream or request prioritization.  For example, see
   Section 11 of [PRIORITY]. L. Pardue, "Extensible Prioritization of HTTP/3 datagrams is not defined in this document.
   Future extensions MAY define how to prioritize datagrams, and MAY
   define signaling to allow endpoints to communicate their
   prioritization preferences.

8.  Security Considerations

   Since this feature requires sending an HTTP/3 Settings parameter, it
   "sticks out".  In other words, probing clients can learn whether a
   server supports this feature.  Implementations that support this
   feature SHOULD always send this Settings parameter to avoid leaking
   the fact that there are applications using HTTP/3 datagrams enabled
   on this endpoint.

9.  IANA Considerations

9.1.  HTTP/3 SETTINGS Parameter

   This document will request IANA to register the following entry in
   the "HTTP/3 Settings" registry:

           +==============+==========+===============+=========+
           | Setting Name | Value    | Specification | Default |
           +==============+==========+===============+=========+
           | H3_DATAGRAM  | 0xffd277 | This Document | 0       |
           +--------------+----------+---------------+---------+

                        Table 1: New HTTP/3 Settings

9.2.  HTTP Header Field Name

   This document will request IANA to register the following entry in
   the "HTTP Field Name" registry:

   Field Name:  Sec-Use-Datagram-Contexts

   Template:  None

   Status:  provisional (permanent if this document is approved)

   Reference:  This document

   Comments:  None

9.3.  Capsule Types

   This document establishes a registry for HTTP capsule type codes.
   The "HTTP Capsule Types" registry governs a 62-bit space.
   Registrations in this registry MUST include the following fields:

   Type:  A name or label for the capsule type.

   Value:  The value of the Capsule Type field (see Section 4.1) is a
      62-bit integer.

   Reference:  An optional reference to a specification for the type.
      This field MAY be empty.

   Registrations follow the "First Come First Served" policy (see
   Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have
   the same Type.

   This registry initially contains the following entries:

         +===========================+==========+===============+
         | Capsule Type              | Value    | Specification |
         +===========================+==========+===============+
         | REGISTER_DATAGRAM_CONTEXT | 0xff37a1 | This Document |
         +---------------------------+----------+---------------+
         | REGISTER_DATAGRAM         | 0xff37a2 | This Document |
         +---------------------------+----------+---------------+
         | CLOSE_DATAGRAM_CONTEXT    | 0xff37a3 | This Document |
         +---------------------------+----------+---------------+
         | DATAGRAM_WITH_CONTEXT     | 0xff37a4 | This Document |
         +---------------------------+----------+---------------+
         | DATAGRAM                  | 0xff37a5 | This Document |
         +---------------------------+----------+---------------+

             Table 2: Initial Capsule Types Registry Entries

   Capsule types with a value of the form 41 * N + 23 for integer values
   of N are reserved to exercise the requirement that unknown capsule
   types be ignored.  These capsules have no semantics and can carry
   arbitrary values.  These values MUST NOT be assigned by IANA and MUST
   NOT appear in the listing of assigned values.

9.4.  Datagram Format Types

   This document establishes a registry for HTTP datagram format type
   codes.  The "HTTP Datagram Format Types" registry governs a 62-bit
   space.  Registrations in this registry MUST include the following
   fields:

   Type:  A name or label for the datagram format type.

   Value:  The value of the Datagram Format Type field (see Section 2.2)
      is a 62-bit integer.

   Reference:  An optional reference to a specification for the
      parameter.  This field MAY be empty.

   Registrations follow the "First Come First Served" policy (see
   Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have
   the same Type nor Value.

   This registry is initially empty.

   Datagram format types with a value of the form 41 * N + 17 for
   integer values of N are reserved to exercise the requirement that
   unknown datagram format types be ignored.  These format types have no
   semantics and can carry arbitrary values.  These values MUST NOT be
   assigned by IANA and MUST NOT appear in the listing of assigned
   values.

9.5.  Context Close Codes

   This document establishes a registry for HTTP context close codes.
   The "HTTP Context Close Codes" registry governs a 62-bit space.
   Registrations in this registry MUST include the following fields:

   Type:  A name or label for the close code.

   Value:  The value of the Close Code field (see Section 4.4.2) is a
      62-bit integer.

   Reference:  An optional reference to a specification for the
      parameter.  This field MAY be empty.

   Registrations follow the "First Come First Served" policy (see
   Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have
   the same Type nor Value.

   This registry initially contains the following entries:

             +====================+==========+===============+
             | Context Close Code | Value    | Specification |
             +====================+==========+===============+
             | NO_ERROR           | 0xff78a0 | This Document |
             +--------------------+----------+---------------+
             | UNKNOWN_FORMAT     | 0xff78a1 | This Document |
             +--------------------+----------+---------------+
             | DENIED             | 0xff78a2 | This Document |
             +--------------------+----------+---------------+
             | RESOURCE_LIMIT     | 0xff78a3 | This Document |
             +--------------------+----------+---------------+

                Table 3: Initial Context Close Code Registry
                                  Entries

   Context close codes with a value of the form 41 * N + 19 for integer
   values of N are reserved to exercise the requirement that unknown
   context close codes be treated as NO_ERROR.  These values MUST NOT be
   assigned by IANA and MUST NOT appear in the listing of assigned
   values.

10.  References

10.1.  Normative References

   [DGRAM]    Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable
              Datagram Extension to QUIC", Work in Progress, Internet-
              Draft, draft-ietf-quic-datagram-06, 5 October 2021,
              <https://datatracker.ietf.org/doc/html/draft-ietf-quic-
              datagram-06>.

   [H3]       Bishop, M., "Hypertext Transfer Protocol Version 3
              (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf-
              quic-http-34, 2 February 2021,
              <https://datatracker.ietf.org/doc/html/draft-ietf-quic-
              http-34>.

   [IANA-POLICY]
              Cotton, M., Leiba, B., and T. Narten, "Guidelines for
              Writing an IANA Considerations Section in RFCs", BCP 26,
              RFC 8126, DOI 10.17487/RFC8126, June 2017,
              <https://www.rfc-editor.org/rfc/rfc8126>.

   [QUIC]     Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based
              Multiplexed and Secure Transport", RFC 9000,
              DOI 10.17487/RFC9000, May 2021,
              <https://www.rfc-editor.org/rfc/rfc9000>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

   [RFC8941]  Nottingham, M. and P-H. Kamp, "Structured Field Values for
              HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,
              <https://www.rfc-editor.org/rfc/rfc8941>.

10.2.  Informative References

   [PRIORITY] Oku, K. and L. Pardue, "Extensible Prioritization Scheme
              for HTTP", Work in Progress, Internet-Draft, draft-ietf-
              httpbis-priority-07, 25 October 2021,
              <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
              priority-07>.

   [RFC8899]  Fairhurst, G., Jones, T., Tüxen, M., Rüngeler, I., and T.
              Völker, "Packetization Layer Path MTU Discovery for
              Datagram Transports", RFC 8899, DOI 10.17487/RFC8899,
              September 2020, <https://www.rfc-editor.org/rfc/rfc8899>.

Appendix A.  Examples

A.1.  CONNECT-UDP

   In this example, the client does not support any CONNECT-UDP nor HTTP
   Datagram extensions, and therefore has no use for datagram contexts
   on this stream.

   Client                                             Server

   STREAM(44): HEADERS             -------->
     :method = CONNECT
     :protocol = connect-udp
     :scheme = https
     :path = /target.example.org/443/
     :authority = proxy.example.org:443

   STREAM(44): DATA                -------->
     Capsule Type = REGISTER_DATAGRAM
     Datagram Format Type = UDP_PAYLOAD
     Datagram Format Additional Data = ""

   DATAGRAM                        -------->
     Quarter Stream ID = 11
     Payload = Encapsulated UDP Payload

              <--------  STREAM(44): HEADERS
                           :status = 200

   /* Wait for target server to respond to UDP packet. */

              <--------  DATAGRAM
                           Quarter Stream ID = 11
                           Payload = Encapsulated UDP Payload

A.2.  CONNECT-UDP with Delayed Timestamp Extension

   In these examples, the client supports a CONNECT-UDP Timestamp
   Extension, which uses a different Datagram Format Type that carries a
   timestamp followed by the encapsulated UDP payload.

A.2.1.  With Delay

   In this instance, the client prefers to wait a round trip to learn
   whether the server supports datagram contexts.

   Client                                             Server

   STREAM(44): HEADERS            -------->
     :method = CONNECT
     :protocol = connect-udp
     :scheme = https
     :path = /target.example.org/443/
     :authority = proxy.example.org:443
     Sec-Use-Datagram-Contexts = ?1

              <--------  STREAM(44): HEADERS
                           :status = 200
                           Sec-Use-Datagram-Contexts = ?1

   STREAM(44): DATA               -------->
     Capsule Type = REGISTER_DATAGRAM_CONTEXT
     Context ID = 0
     Datagram Format Type = UDP_PAYLOAD
     Datagram Format Additional Data = ""

   DATAGRAM                        -------->
     Quarter Stream ID = 11
     Context ID = 0
     Payload = Encapsulated UDP Payload

              <--------  DATAGRAM
                           Quarter Stream ID = 11
                           Context ID = 0
                           Payload = Encapsulated UDP Payload

   STREAM(44): DATA               -------->
     Capsule Type = REGISTER_DATAGRAM_CONTEXT
     Context ID = 2
     Datagram Format Type = UDP_PAYLOAD_WITH_TIMESTAMP
     Datagram Format Additional Data = ""

   DATAGRAM                       -------->
     Quarter Stream ID = 11
     Context ID = 2
     Payload = Encapsulated UDP Payload With Timestamp

A.3.  Successful Optimistic

   In this instance, the client does not wish to spend a round trip
   waiting to learn whether the server supports datagram contexts.  It
   registers its context optimistically in such a way that the server
   will react well whether it supports contexts or not.  In this case,
   the server does support datagram contexts.

   Client                                             Server

   STREAM(44): HEADERS            -------->
     :method = CONNECT
     :protocol = connect-udp
     :scheme = https
     :path = /target.example.org/443/
     :authority = proxy.example.org:443
     Sec-Use-Datagram-Contexts = ?1

   STREAM(44): DATA               -------->
     Capsule Type = REGISTER_DATAGRAM
     Datagram Format Type = UDP_PAYLOAD
     Datagram Format Additional Data = ""

   STREAM(44): DATA               -------->
     Capsule Type = DATAGRAM
     Payload = Encapsulated UDP Payload

              <--------  STREAM(44): HEADERS
                           :status = 200
                           Sec-Use-Datagram-Contexts = ?1

   /* Datagram contexts are in use on this stream */

              <--------  DATAGRAM
                           Quarter Stream ID = 11
                           Context ID = 0
                           Payload = Encapsulated UDP Payload

   STREAM(44): DATA               -------->
     Capsule Type = REGISTER_DATAGRAM_CONTEXT
     Context ID = 2
     Datagram Format Type = UDP_PAYLOAD_WITH_TIMESTAMP
     Datagram Format Additional Data = ""

   DATAGRAM                       -------->
     Quarter Stream ID = 11
     Context ID = 2
     Payload = Encapsulated UDP Payload With Timestamp

A.4.  Optimistic but Unsupported

   In this instance, the client does not wish to spend a round trip
   waiting to learn whether the server supports datagram contexts.  It
   registers its context optimistically Scheme
              for HTTP", Work in such a way that the server
   will react well whether it supports contexts or not.  In Progress, Internet-Draft, draft-ietf-
              httpbis-priority-12, 17 January 2022,
              <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
              priority-12>.

Appendix A.  Examples

   [[RFC editor: please remove this case,
   the server does not support datagram contexts. appendix before publication.]]

A.1.  CONNECT-UDP
   Client                                             Server

   STREAM(44): HEADERS             -------->
     :method = CONNECT
     :protocol = connect-udp
     :scheme = https
     :path = /target.example.org/443/
     :authority = proxy.example.org:443
     Sec-Use-Datagram-Contexts
     capsule-protocol = ?1

   STREAM(44): DATA               -------->
     Capsule Type = REGISTER_DATAGRAM
     Datagram Format Type = UDP_PAYLOAD
     Datagram Format Additional Data = ""

   STREAM(44): DATA               -------->
     Capsule Type = DATAGRAM
     Payload = Encapsulated UDP Payload

              <--------  STREAM(44): HEADERS
                           :status = 200

   /* Datagram contexts are not in use on this stream */

              <--------  DATAGRAM
                           Quarter Stream ID = 11
                           Payload = Encapsulated UDP Payload

   DATAGRAM                        -------->
     Quarter Stream ID = 11
     Payload = Encapsulated UDP Payload

A.5.  CONNECT-IP with IP compression

   Client                                             Server

   STREAM(44): HEADERS            -------->
     :method = CONNECT
     :protocol = connect-ip
     :scheme = https
     :path = /
     :authority = proxy.example.org:443
     Sec-Use-Datagram-Contexts = ?1

              <--------  STREAM(44): HEADERS
                           :status = 200
                           Sec-Use-Datagram-Contexts
                           capsule-protocol = ?1

   /* Exchange CONNECT-IP configuration information. */

   STREAM(44): DATA                -------->
     Capsule Type = REGISTER_DATAGRAM_CONTEXT
     Context ID = 0
     Datagram Format Type = IP_PACKET
     Datagram Format Additional Data = ""

   DATAGRAM                       -------->
     Quarter Stream ID = 11
     Context ID = 0
     Payload = Encapsulated IP Packet

   /* Endpoint happily exchange encapsulated IP packets */
   /* using Quarter Stream ID 11 and Context ID 0. Wait for target server to respond to UDP packet. */

              <--------  DATAGRAM                       -------->
                           Quarter Stream ID = 11
     Context ID = 0
                           Payload = Encapsulated IP Packet

   /* After performing some analysis on traffic patterns, */
   /* the client decides it wants to compress a 2-tuple.  */

   STREAM(44): DATA                -------->
     Capsule Type = REGISTER_DATAGRAM_CONTEXT
     Context ID = 2
     Datagram Format Type = COMPRESSED_IP_PACKET
     Datagram Format Additional Data = "192.0.2.6,192.0.2.7"

   DATAGRAM                       -------->
     Quarter Stream ID = 11
     Context ID = 2 UDP Payload = Compressed IP Packet

A.6.

A.2.  WebTransport

   Client                                             Server

   STREAM(44): HEADERS            -------->
     :method = CONNECT
     :scheme = https
     :method
     :protocol = webtransport
     :path = /hello
     :authority = webtransport.example.org:443
     Origin
     origin = https://www.example.org:443

   STREAM(44): DATA                -------->
     Capsule Type = REGISTER_DATAGRAM
     Datagram Format Type = WEBTRANSPORT_DATAGRAM
     Datagram Format Additional Data = ""

              <--------  STREAM(44): HEADERS
                           :status = 200

   /* Both endpoints can now send WebTransport datagrams. */

Acknowledgments

   The DATAGRAM context identifier was

   Portions of this document were previously part of the QUIC DATAGRAM
   frame definition itself, the authors would like to acknowledge the
   authors of that document and the members of the IETF MASQUE working
   group for their suggestions.  Additionally, the authors would like to
   thank Martin Thomson for suggesting the use of an HTTP/3 SETTINGS
   parameter.  Furthermore, the authors would like to thank Ben Schwartz
   for writing the first proposal that used two layers of indirection.
   The final design in this document came out of the HTTP Datagrams
   Design Team, whose members were Alan Frindell, Alex Chernyakhovsky,
   Ben Schwartz, Eric Rescorla, Marcus Ihlar, Martin Thomson, Mike
   Bishop, Tommy Pauly, Victor Vasiliev, and the authors of this
   document.

Authors' Addresses

   David Schinazi
   Google LLC
   1600 Amphitheatre Parkway
   Mountain View, California 94043,
   United States of America
   Email: dschinazi.ietf@gmail.com

   Lucas Pardue
   Cloudflare
   Email: lucaspardue.24.7@gmail.com