Draft: draft-ietf-masque-h3-datagram

Commentary: thanks for this , LGTM modulo the one nit
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.
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.
Additionally, this document defines how to 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 when the application protocol running over QUIC is
HTTP/3 H3.  It associates datagrams with client-initiated
bidirectional streams and defines an optional additional
demultiplexing layer.
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
HTTP/3 H3.  It associates datagrams with client-initiated
bidirectional streams and defines an optional additional
demultiplexing layer.  Additionally, this document defines how to
convey datagrams over prior versions of HTTP.
In order to allow multiple exchanges of datagrams to coexist on a
given QUIC connection, 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 stream.  Second, datagrams optionally carry a context identifier
(see datagram-contexts) 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/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 stream.  Second, datagrams
optionally carry a context identifier (see datagram-contexts) 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.
Implementations of HTTP/3 that support the DATAGRAM extension MUST
provide a context ID allocation service.  That service will allow
applications co-located with HTTP/3 to request a unique context ID
that they can subsequently use for their own purposes.  The HTTP/3
implementation will then parse the context ID of incoming DATAGRAM
frames 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 an HTTP/3 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 and server - only allocation carries separate
namespaces to avoid requiring synchronization.  Additionally, note
that the context ID namespace is tied to a given HTTP request: it is
possible for the same numeral context ID to be used simultaneously in
distinct requests.
Implementations of HTTP Datagrams 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
the context ID 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 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 and server - only allocation carries separate
namespaces to avoid requiring synchronization.  Additionally, note
that the context ID namespace is tied to a given HTTP request: it is
possible for the same numeral context ID to be used simultaneously in
distinct requests.
Datagrams sent using the DATAGRAM Capsule have the exact same
semantics as datagrams sent in QUIC DATAGRAM frames.  In particular,
the restrictions on when it is allowed to send an HTTP/3 datagram and
how to process them from format also apply to HTTP/3 datagrams sent
and received using the DATAGRAM capsule.
The DATAGRAM Capsule is transparent to intermediaries, meaning that
intermediaries MAY parse it and send DATAGRAM Capsules that they did
not receive.  This allows an intermediary to reencode HTTP/3
Datagrams as it forwards them: in other words, an intermediary MAY
send a DATAGRAM Capsule to forward an HTTP/3 Datagram which was
received in a QUIC DATAGRAM frame, and vice versa.
Note that while DATAGRAM capsules are sent on a stream,
intermediaries can reencode HTTP/3 datagrams into QUIC DATAGRAM
frames over the next hop, and those could be dropped.  Because of
this, applications have to always consider HTTP/3 datagrams to be
unreliable, even if they were initially sent in a capsule.
Datagrams sent using the DATAGRAM Capsule have the exact 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 DATAGRAM Capsule is transparent to intermediaries, meaning that
intermediaries MAY parse it and send DATAGRAM Capsules that they did
not receive.  This allows an intermediary to reencode HTTP Datagrams
as it forwards them: 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 can reencode 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.
TODO: Refactor this document into "HTTP Datagrams" with definitions
for HTTP/1.x, HTTP/2, and HTTP/3.
TODO: Refactor this document and add definitions for HTTP/1.x and
HTTP/2.