Original text:
<del> Using Datagrams with HTTP </del>  draft-ietf-masque-h3-datagram-latest Abstract <del> 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 with HTTP/3 by association with HTTP requests. Additionally, this document defines the Capsule Protocol that can convey datagrams over prior versions of HTTP. </del>  <del> 1. 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 with HTTP/3 H3 by association with HTTP requests. Additionally, this document defines the Capsule Protocol that can convey datagrams over prior versions of HTTP. This document is structured as follows: </del>  <del> multiplexing presents core concepts for multiplexing across HTTP versions. </del>  <del> format defines how QUIC DATAGRAM frames are used with HTTP/3. setting defines an HTTP/3 setting that endpoints can use to advertise support of the frame. capsule 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. </del>  <del> datagram-capsule defines Datagram Capsule types, along with guidance for specifying new capsule types. </del>  1.1. 2. <del> All HTTP Datagrams are associated with an HTTP request. </del>  <del> When running over HTTP/3, multiple exchanges of datagrams need the ability to coexist on a given QUIC connection.  To allow this, the QUIC DATAGRAM frame payload starts with an encoded stream identifier that associates the datagram with a request stream. </del>  When running over HTTP/2, demultiplexing is provided by the HTTP/2 <del> framing layer.  When running over HTTP/1, requests are strictly serialized in the connection, therefore demultiplexing is not needed. 3. </del>  When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM frames uses the following format (using the notation from the parsing the Quarter Stream ID field MUST be treated as an HTTP/3 connection error of type H3_DATAGRAM_ERROR. <del> Endpoints MUST NOT send HTTP/3 datagrams unless the corresponding stream's send side is open.  On a given endpoint, once the receive side of a stream is closed, incoming datagrams for this stream are no longer expected so the endpoint can release related state.  Endpoints MAY keep state for a short time to account for reordering.  Once the state is released, the endpoint MUST silently drop received associated datagrams. </del>  If an HTTP/3 datagram is received and its Quarter Stream ID maps to a stream that has not yet been created, the receiver SHALL either drop determining the active stream concurrency limit that is applied by the QUIC layer. <del> HTTP/3 datagrams MUST only be sent with an association to a stream that 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 corresponding stream with H3_DATAGRAM_ERROR.  Future extensions MAY remove these requirements if they define semantics for such HTTP Datagrams and negotiate mutual support. </del>  <del> 3.1. </del>  Implementations of HTTP/3 that support HTTP Datagrams can indicate that to their peer by sending the H3_DATAGRAM SETTINGS parameter with <del> a value of 1.  The value of the H3_DATAGRAM SETTINGS parameter MUST be either 0 or 1.  A 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 the connection with error H3_SETTINGS_ERROR. </del>  <del> Endpoints MUST NOT send QUIC DATAGRAM frames until they have both sent and received the H3_DATAGRAM SETTINGS parameter with a value of 1. </del>  When clients use 0-RTT, they MAY store the value of the server's H3_DATAGRAM SETTINGS parameter.  Doing so allows the client to send with a value of 1, even if the application does not intend to use HTTP Datagrams.  This helps to avoid "sticking out"; see security. <del> 3.1.1. </del>  [[RFC editor: please remove this section before publication.]] Identifier field of a Setting in the HTTP/3 SETTINGS frame) for the H3_DATAGRAM Settings Parameter.  This allows new draft revisions to make incompatible changes.  Multiple draft versions MAY be supported <del> by either endpoint in a connection.  Such endpoints MUST send multiple values for H3_DATAGRAM.  Once an endpoint has sent and received SETTINGS, it MUST compute the intersection of the values it has sent and received, and then it MUST select and use the most recent draft version from the intersection set.  This ensures that both endpoints negotiate the same draft version. </del>  <del> 4. </del>  This specification introduces the Capsule Protocol.  The Capsule <del> Protocol is a sequence of type-length-value tuples that new HTTP Upgrade Tokens (see HTTP) can choose to use.  It allows endpoints to </del>  reliably communicate request-related information end-to-end on HTTP request streams, even in the presence of HTTP intermediaries.  The <del> Capsule Protocol can be used to exchange HTTP Datagrams when HTTP is running over a transport that does not support the QUIC DATAGRAM frame. </del>  This specification defines the "data stream" of an HTTP request as <del> 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. </del>  <del> Note that use of the Capsule Protocol is not required to use HTTP Datagrams.  If a new HTTP 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. 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): 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 DATAGRAM capsule; see datagram-capsule.  An intermediary can identify the use of the capsule protocol either through the presence of the Capsule-Protocol header field (hdr) or by understanding the chosen HTTP Upgrade token.  An intermediary that identifies the use of the capsule protocol MAY convert between DATAGRAM capsules and QUIC DATAGRAM frames when forwarding.  Definitions of new Capsule Types MAY specify optional custom intermediary processing. </del>  Endpoints which receive a Capsule with an unknown Capsule Type MUST <del> silently drop that Capsule. </del>  By virtue of the definition of the data stream, the Capsule Protocol is not in use on responses unless the response includes a 2xx Content-Length, Content-Type, or Transfer-Encoding header fields. Additionally, HTTP status codes 204 (No Content), 205 (Reset Content), and 206 (Partial Content) MUST NOT be sent on responses <del> that use the Capsule Protocol. </del>  <del> 4.2. </del>  <del> When an error occurs processing the capsule protocol, the receiver </del>  MUST treat the message as malformed or incomplete, according to the underlying transport protocol.  For HTTP/3, the handling of malformed messages is described in H3.  For HTTP/2, the handling of malformed capsule on the stream was truncated, this MUST be treated as a malformed or incomplete message. <del> 4.3. </del>  <del> This document defines the "Capsule-Protocol" header field.  It is an Item Structured Field, see STRUCT-FIELD; its value MUST be a Boolean. Its ABNF is: </del>  <del> Endpoints indicate that the Capsule Protocol is in use on the data stream by sending the Capsule-Protocol header field with a value of ?1.  A Capsule-Protocol header field with a value of ?0 has the same semantics as when the header is not present.  Intermediaries MAY use this header field to allow processing of HTTP Datagrams for unknown HTTP Upgrade Tokens; note that this is only possible for HTTP Upgrade or Extended CONNECT. </del>  <del> The Capsule-Protocol header field MUST NOT be sent multiple times on a message.  The Capsule-Protocol header field MUST NOT be used on HTTP responses with a status code different from 2xx (Successful). This specification does not define any parameters for the Capsule- Protocol header field value, but future documents MAY define parameters.  Receivers MUST ignore unknown parameters. </del>  Definitions of new HTTP Upgrade Tokens that use the Capsule Protocol MAY use the Capsule-Protocol header field to simplify intermediary processing. <del> 4.4. </del>  This document defines the DATAGRAM capsule type (see iana-types for <del> the value of the capsule type).  This capsule allows an endpoint to send an HTTP Datagram on a stream using the Capsule Protocol.  This is particularly useful when HTTP is running over a transport that does not support the QUIC DATAGRAM frame. </del>  <del> Datagrams sent using the DATAGRAM capsule have the same semantics as datagrams sent in QUIC DATAGRAM frames.  In particular, the </del>  restrictions on when it is allowed to send an HTTP Datagram and how to process them from format also apply to HTTP Datagrams sent and received using the DATAGRAM capsule. be usable, the implementation SHOULD discard the capsule without buffering its contents into memory. <del> 5. Data streams (see capsule-protocol) can be prioritized using any means suited to stream or request prioritization.  For example, see PRIORITY. 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. </del>  <del> 6. </del>  Since transmitting HTTP Datagrams using QUIC DATAGRAM frames requires sending an HTTP/3 Settings parameter, it "sticks out".  In other Tokens, it is not accessible from Web Platform APIs (such as those commonly accessed via JavaScript in web browsers). <del> 7. </del>  <del> 7.1. </del>  This document will request IANA to register the following entry in the "HTTP/3 Settings" registry: <del> 7.2. </del>  This document will request IANA to register the following entry in the "HTTP/3 Error Codes" registry: <del> 7.3. </del>  This document will request IANA to register the following entry in the "HTTP Field Name" registry: <del> 7.4. </del>  This document establishes a registry for HTTP capsule type codes. The "HTTP Capsule Types" registry governs a 62-bit space.

Reviewer comments:
NAME thank you for the suggestions over on URL David and I worked through your proposal from top to bottom and turned it into this PR, which accepts many suggestions but not all. Please review and let us know if you're happy with it. NAME we believe some of your comments are addressed here too (unless tracked on a separate ticket). Please take a look.
While the argument in Section 2 "requests are strictly serialised in the connection, therefore demultiplexing is not needed" is technically correct, Section 4. further restricts the use of HTTP/1.1 connections to a single stream of capsules/HTTP datagrams. I would prefer to see this restriction as an argument here.
The sentence "Additionally, this document defines the Capsule Protocol that can convey datagrams over prior versions of HTTP." seems a little misleading … During the IETF 113 discussions, I understood capsules as general mechanism reliable datagrams/wire encoding over HTTP In the draft however, Section 1 state "Additionally, this document defines the Capsule Protocol that can convey datagrams over prior versions of HTTP." contradicts this impression. Can we clarify this?
Why is the ebnf instead of ? Should this allow request/upgrade methods to append a list of additional parameters?
Yes, allows parameters but does not. We didn't see a good reason to ban future parameters
Maybe you should mention it and require intermediaries to pass and ignore them in case they don't understand them.
as per recent changes in HTTPland specs, the ABNF adds confusion. My suggestion is to remove the ABNF. That might still leave a question over the structured types, but that is answered by the Structured Field value specs and we are unlikely to need to state anything ourselves. I can take a pass at this.
LGTM, thanks!

Revised text:
 <ins> HTTP Datagrams and the Capsule Protocol </ins> draft-ietf-masque-h3-datagram-latest Abstract  <ins> This document describes HTTP Datagrams, a convention for conveying multiplexed, potentially unreliable datagrams inside an HTTP connection. </ins>  <ins> In HTTP/3, HTTP Datagrams can be conveyed natively using the QUIC DATAGRAM extension.  When the QUIC DATAGRAM frame is unavailable or undesirable, they can be sent using the Capsule Protocol, a more general convention for conveying data in HTTP connections. </ins>  <ins> Both are intended for use by HTTP extensions, not applications. </ins>  <ins> 1. </ins>  <ins> HTTP extensions sometimes need to access underlying transport protocol features such as unreliable delivery (as offered by DGRAM) to enable desirable features like an unreliable version of the CONNECT method, and unreliable delivery in WebSockets RFC6455 (or its successors). In datagrams, this document describes HTTP Datagrams, a convention that supports the bidirectional and possibly multiplexed exchange of data inside an HTTP connection.  While HTTP datagrams are associated with HTTP requests, they are not part of message content; instead, they are intended for use by HTTP extensions (such as the CONNECT method), and are compatible with all versions of HTTP.  When the underlying transport protocol supports unreliable delivery (such as when the QUIC DATAGRAM extension is available in HTTP/3), they can use that capability. It also describes the HTTP Capsule Protocol in capsule, to allow conveyance of HTTP Datagrams when the QUIC DATAGRAM frame is unavailable or undesirable, such as when earlier versions of HTTP are in use. </ins> 1.1. 2.  <ins> HTTP Datagrams are a convention for conveying bidirectional and potentially unreliable datagrams inside an HTTP connection, with multiplexing when possible.  All HTTP Datagrams are associated with an HTTP request. </ins>  <ins> When HTTP Datagrams are conveyed on an HTTP/3 connection, the QUIC DATAGRAM frame can be used to achieve these goals, including unreliable delivery; see format.  Negotiation is achieved using a setting; see setting. </ins> When running over HTTP/2, demultiplexing is provided by the HTTP/2  <ins> framing layer, but unreliable delivery is unavailable.  HTTP Datagrams are negotiated and conveyed using the Capsule Protocol; see datagram-capsule. When running over HTTP/1, requests are strictly serialized in the connection, and therefore demultiplexing is not available. Unreliable delivery is likewise not available.  HTTP Datagrams are negotiated and conveyed using the Capsule Protocol; see datagram- capsule. HTTP Datagrams MUST only be sent with an association to a stream whose HTTP semantics explicitly supports HTTP Datagrams.  For example, existing HTTP methods GET and POST do not define semantics for associated HTTP Datagrams; therefore, HTTP Datagrams cannot be sent associated with GET or POST request streams. If an HTTP Datagram associated with a method that has no known semantics for HTTP Datagrams is received, the receiver MUST abort the corresponding stream; if HTTP/3 is in use, the stream MUST be aborted with H3_DATAGRAM_ERROR.  HTTP extensions can override these requirements by defining a negotiation mechanism and semantics for HTTP Datagrams. 2.1. </ins> When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM frames uses the following format (using the notation from the parsing the Quarter Stream ID field MUST be treated as an HTTP/3 connection error of type H3_DATAGRAM_ERROR.  <ins> HTTP/3 Datagrams MUST NOT be sent unless the corresponding stream's send side is open.  Once the receive side of a stream is closed, incoming datagrams for this stream are no longer expected so related state can be released.  State MAY be kept for a short time to account for reordering.  Once the state is released, the received associated datagrams MUST be silently dropped. </ins> If an HTTP/3 datagram is received and its Quarter Stream ID maps to a stream that has not yet been created, the receiver SHALL either drop determining the active stream concurrency limit that is applied by the QUIC layer.  <ins> 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 communicating prioritization preferences. </ins>  <ins> 2.1.1. </ins> Implementations of HTTP/3 that support HTTP Datagrams can indicate that to their peer by sending the H3_DATAGRAM SETTINGS parameter with  <ins> a value of 1. The value of the H3_DATAGRAM SETTINGS parameter MUST be either 0 or 1.  A value of 0 indicates that HTTP Datagrams are not supported.  If the H3_DATAGRAM SETTINGS parameter is received with a value that is neither 0 or 1, the receiver MUST terminate the connection with error H3_SETTINGS_ERROR. </ins>  <ins> QUIC DATAGRAM frames MUST NOT be sent until the H3_DATAGRAM SETTINGS parameter has been both sent and received with a value of 1. </ins> When clients use 0-RTT, they MAY store the value of the server's H3_DATAGRAM SETTINGS parameter.  Doing so allows the client to send with a value of 1, even if the application does not intend to use HTTP Datagrams.  This helps to avoid "sticking out"; see security.  <ins> 2.1.1.1. </ins> [[RFC editor: please remove this section before publication.]] Identifier field of a Setting in the HTTP/3 SETTINGS frame) for the H3_DATAGRAM Settings Parameter.  This allows new draft revisions to make incompatible changes.  Multiple draft versions MAY be supported  <ins> by sending multiple values for H3_DATAGRAM.  Once SETTINGS have been sent and received, an implementation that supports multiple drafts MUST compute the intersection of the values it has sent and received, and then it MUST select and use the most recent draft version from the intersection set.  This ensures that both peers negotiate the same draft version. </ins>  <ins> 2.2. When HTTP/3 Datagrams are unavailable or undesirable, HTTP Datagrams can be sent using the Capsule Protocol, see datagram-capsule. 3. One mechanism to extend HTTP is to introduce new HTTP Upgrade Tokens (see HTTP).  In HTTP/1.x, these tokens are used via the Upgrade mechanism (see HTTP).  In HTTP/2 and HTTP/3, these tokens are used via the Extended CONNECT mechanism (see EXT-CONNECT2 and EXT- CONNECT3). </ins> This specification introduces the Capsule Protocol.  The Capsule  <ins> Protocol is a sequence of type-length-value tuples that definitions of new HTTP Upgrade Tokens can choose to use.  It allows endpoints to </ins> reliably communicate request-related information end-to-end on HTTP request streams, even in the presence of HTTP intermediaries.  The  <ins> Capsule Protocol can be used to exchange HTTP Datagrams, which is necessary when HTTP is running over a transport that does not support the QUIC DATAGRAM frame. 3.1. </ins> This specification defines the "data stream" of an HTTP request as  <ins> the bidirectional stream of bytes that follows the header section of the request message and the final, successful (i.e., 2xx) response message. </ins>  <ins> 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 response header section.  As a result, 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. Data streams can be prioritized using any means suited to stream or request prioritization.  For example, see PRIORITY. 3.2. Definitions of new HTTP Upgrade Tokens can state that their associated request's data stream uses the Capsule Protocol.  If they do so, that means that the contents of the associated request's data stream uses the following format (using the notation from the "Notational Conventions" section of QUIC): An intermediary can identify the use of the capsule protocol either through the presence of the Capsule-Protocol header field (hdr) or by understanding the chosen HTTP Upgrade token. Because new protocols or extensions might define new capsule types, intermediaries that wish to allow for future extensibility SHOULD forward capsules without modification, unless the definition of the Capsule Type in use specifies additional intermediary processing. One such Capsule Type is the DATAGRAM capsule; see datagram-capsule. In particular, intermediaries SHOULD forward Capsules with an unknown Capsule Type without modification. </ins> Endpoints which receive a Capsule with an unknown Capsule Type MUST  <ins> silently drop that Capsule and skip over it to parse the next Capsule. </ins> By virtue of the definition of the data stream, the Capsule Protocol is not in use on responses unless the response includes a 2xx Content-Length, Content-Type, or Transfer-Encoding header fields. Additionally, HTTP status codes 204 (No Content), 205 (Reset Content), and 206 (Partial Content) MUST NOT be sent on responses  <ins> that use the Capsule Protocol.  A receiver that observes a violation of these requirements MUST treat the HTTP message as malformed. </ins>  <ins> 3.3. </ins>  <ins> When an error occurs in processing the Capsule Protocol, the receiver </ins> MUST treat the message as malformed or incomplete, according to the underlying transport protocol.  For HTTP/3, the handling of malformed messages is described in H3.  For HTTP/2, the handling of malformed capsule on the stream was truncated, this MUST be treated as a malformed or incomplete message.  <ins> 3.4. </ins>  <ins> The "Capsule-Protocol" header field is an Item Structured Field, see STRUCT-FIELD; its value MUST be a Boolean; any other value type MUST be handled as if the field were not present by recipients (for example, if this field is included multiple times, its type will become a List and the field will therefore be ignored).  This document does not define any parameters for the Capsule-Protocol header field value, but future documents might define parameters. Receivers MUST ignore unknown parameters. </ins>  <ins> Endpoints indicate that the Capsule Protocol is in use on a data stream by sending a Capsule-Protocol header field with a true value. A Capsule-Protocol header field with a false value has the same semantics as when the header is not present. </ins>  <ins> Intermediaries MAY use this header field to allow processing of HTTP Datagrams for unknown HTTP Upgrade Tokens; note that this is only possible for HTTP Upgrade or Extended CONNECT. The Capsule-Protocol header field MUST NOT be used on HTTP responses with a status code outside the 2xx range. </ins> Definitions of new HTTP Upgrade Tokens that use the Capsule Protocol MAY use the Capsule-Protocol header field to simplify intermediary processing.  <ins> 3.5. </ins> This document defines the DATAGRAM capsule type (see iana-types for  <ins> the value of the capsule type).  This capsule allows HTTP Datagrams to be sent on a stream using the Capsule Protocol.  This is particularly useful when HTTP is running over a transport that does not support the QUIC DATAGRAM frame. </ins>  <ins> HTTP Datagrams sent using the DATAGRAM capsule have the same semantics as those sent in QUIC DATAGRAM frames.  In particular, the </ins> restrictions on when it is allowed to send an HTTP Datagram and how to process them from format also apply to HTTP Datagrams sent and received using the DATAGRAM capsule. be usable, the implementation SHOULD discard the capsule without buffering its contents into memory.  <ins> Note that use of the Capsule Protocol is not required to use HTTP Datagrams.  If a new HTTP 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, definitions of new HTTP Upgrade Tokens that wish to use HTTP Datagrams SHOULD use the Capsule Protocol unless they have a good reason not to. </ins>  <ins> 4. </ins> Since transmitting HTTP Datagrams using QUIC DATAGRAM frames requires sending an HTTP/3 Settings parameter, it "sticks out".  In other Tokens, it is not accessible from Web Platform APIs (such as those commonly accessed via JavaScript in web browsers).  <ins> 5. </ins>  <ins> 5.1. </ins> This document will request IANA to register the following entry in the "HTTP/3 Settings" registry:  <ins> 5.2. </ins> This document will request IANA to register the following entry in the "HTTP/3 Error Codes" registry:  <ins> 5.3. </ins> This document will request IANA to register the following entry in the "HTTP Field Name" registry:  <ins> 5.4. </ins> This document establishes a registry for HTTP capsule type codes. The "HTTP Capsule Types" registry governs a 62-bit space.