Draft: draft-ietf-masque-h3-datagram

Commentary: thank you for the suggestions over on  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 . 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 did n'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 do n'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 !
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.
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.
multiplexing presents core concepts for multiplexing across HTTP
versions.
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.
datagram-capsule defines Datagram Capsule types, along with
guidance for specifying new capsule types.
This document describes HTTP Datagrams, a convention for conveying
multiplexed, potentially unreliable datagrams inside an HTTP
connection.
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.
Both are intended for use by HTTP extensions, not applications.
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.
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, the
QUIC DATAGRAM frame payload starts with an encoded stream identifier
that associates the datagram with a request stream.
When running over HTTP/2, demultiplexing is provided by the HTTP/2
framing layer.  When running over HTTP/1, requests are strictly
serialized in the connection, therefore demultiplexing is not needed.
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.
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.
When running over HTTP/2, demultiplexing is provided by the HTTP/2
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.
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.
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.
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.
Implementations of HTTP/3 that support HTTP Datagrams can indicate
that to their peer by sending the H3_DATAGRAM SETTINGS parameter with
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.
Endpoints MUST NOT send QUIC DATAGRAM frames until they have both
sent and received the H3_DATAGRAM SETTINGS parameter with a value of
1.
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.
Implementations of HTTP/3 that support HTTP Datagrams can indicate
that to their peer by sending the H3_DATAGRAM SETTINGS parameter with
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.
QUIC DATAGRAM frames MUST NOT be sent until the H3_DATAGRAM SETTINGS
parameter has been both sent and received with a value of 1.
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 to
make incompatible changes.  Multiple draft versions MAY be supported
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.
This specification introduces the Capsule Protocol.  The Capsule
Protocol is a sequence of type-length-value tuples that new HTTP
Upgrade Tokens (see HTTP) can choose to use.  It allows endpoints to
reliably communicate request-related information end-to-end on HTTP
request streams, even in the presence of HTTP intermediaries.  The
Capsule Protocol 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.
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.
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.
Endpoints which receive a Capsule with an unknown Capsule Type MUST
silently drop that Capsule.
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 to
make incompatible changes.  Multiple draft versions MAY be supported
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.
When HTTP/3 Datagrams are unavailable or undesirable, HTTP Datagrams
can be sent using the Capsule Protocol, see datagram-capsule.
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).
This specification introduces the Capsule Protocol.  The Capsule
Protocol is a sequence of type-length-value tuples that definitions
of new HTTP Upgrade Tokens can choose to use.  It allows endpoints to
reliably communicate request-related information end-to-end on HTTP
request streams, even in the presence of HTTP intermediaries.  The
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.
This specification defines the "data stream" of an HTTP request as
the bidirectional stream of bytes that follows the header section of
the request message and the final, successful (i.e., 2xx) response
message.
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.
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.
Endpoints which receive a Capsule with an unknown Capsule Type MUST
silently drop that Capsule and skip over it to parse the next
Capsule.
The Capsule Protocol MUST NOT be used with messages that contain
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
that use the Capsule Protocol.
When an error occurs processing the capsule protocol, the receiver
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
messages is described in H2.  For HTTP/1.1, the handling of
incomplete messages is described in H1.
The Capsule Protocol MUST NOT be used with messages that contain
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
that use the Capsule Protocol.  A receiver that observes a violation
of these requirements MUST treat the HTTP message as malformed.
When an error occurs in processing the Capsule Protocol, the receiver
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
messages is described in H2.  For HTTP/1.1, the handling of
incomplete messages is described in H1.
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.
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.
This document defines the DATAGRAM capsule type (see iana-types for
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.
Datagrams sent using the DATAGRAM capsule have the same semantics as
datagrams sent in QUIC DATAGRAM frames.  In particular, the
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.
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.
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.
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.
This document defines the DATAGRAM capsule type (see iana-types for
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.
HTTP Datagrams sent using the DATAGRAM capsule have the same
semantics as those sent in QUIC DATAGRAM frames.  In particular, the
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.
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.
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.