Draft: draft-ietf-masque-h3-datagram

Commentary: This somewhat of an experiment . While trying to address I got distracted by the document 's use of the " flow identifier " term . The document likes to compare " flow identifiers " with QUIC streams , which is fine . But QUIC makes the distinction between streams and stream IDs ; the ID is a property of the stream but it is n't the only one , and sometimes it helps to talk about the stream in other contexts . This change tries to channel a similar editorial style . It replaces : " flow identifiers " with " flows " when talking about a logical entitiy " flow identifiers " with " flow IDs " when talking about the wire format , encoding , examples etc . This could be a change too far but I figured it would be a good discussion starter . 
 The draft does n't do this . It relies on the QUIC varint encoding for non - negativity in DATAGRAM frames but could contain a negative value . Let 's be clear in the spec . 
 Definitely agree , could you write a PR please ? 
 I will . 
 fixed in 
 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 defines how to use QUIC DATAGRAM
frames when the application protocol running over QUIC is HTTP/3 by
adding an identifier at the start of the frame payload.  This allows
HTTP messages to convey related information using unreliable DATAGRAM
frames, ensuring those frames are properly associated with an HTTP
message.
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 defines logical flows identified by a non-negative
integer that are present at the start of the DATAGRAM frame payload.
Flows are associated with HTTP messages using the Datagram-Flow-Id
header field, allowing endpoints to match unreliable DATAGRAMS frames
to the HTTP messages that they are related to.
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 defines how to use QUIC DATAGRAM
frames when the application protocol running over QUIC is HTTP/3 H3
by adding an identifier at the start of the frame payload.  This
allows HTTP messages to convey related information using unreliable
DATAGRAM frames, ensuring those frames are properly associated with
an HTTP message.
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 defines logical flows identified by a non-negative
integer that are present at the start of the DATAGRAM frame payload.
Flows are associated with HTTP messages using the Datagram-Flow-Id
header field, allowing endpoints to match unreliable DATAGRAMS frames
to the HTTP messages that they are related to.
Flow identifiers represent bidirectional flows of datagrams within a
single QUIC connection.  These are conceptually similar to streams in
the sense that they allow multiplexing of application data.  Flows
lack any of the ordering or reliability guarantees of streams.
Beyond this, a sender SHOULD ensure that DATAGRAM frames within a
single flow are transmitted in order relative to one another.  If
multiple DATAGRAM frames can be packed into a single QUIC packet, the
sender SHOULD group them by flow identifier to promote fate-sharing
within a specific flow and improve the ability to process batches of
datagram messages efficiently on the receiver.
Implementations of HTTP/3 that support the DATAGRAM extension MUST
provide a flow identifier allocation service.  That service will
allow applications co-located with HTTP/3 to request a unique flow
identifier that they can subsequently use for their own purposes.
The HTTP/3 implementation will then parse the flow identifier of
incoming DATAGRAM frames and use it to deliver the frame to the
appropriate application.
Even-numbered flow identifiers are client-initiated, while odd-
numbered flow identifiers are server-initiated.  This means that an
HTTP/3 client implementation of the flow identifier allocation
service MUST only provide even-numbered identifiers, while a server
implementation MUST only provide odd-numbered identifiers.  Note
that, once allocated, any flow identifier can be used by both client
and server - only allocation carries separate namespaces to avoid
requiring synchronization.
The flow allocation service SHOULD also provide a mechanism for
applications to indicate they have completed their usage of a flow
identifier and will no longer be using that flow identifier, this
process is called "retiring" a flow identifier.  Applications MUST
NOT retire a flow identifier until after they have received
confirmation that the peer has also stopped using that flow
identifier.  The flow identifier allocation service MAY reuse
previously retired flow identifiers once they have ascertained that
there are no packets with DATAGRAM frames using that flow identifier
still in flight.  Reusing flow identifiers can improve performance by
transmitting the flow identifier using a shorter variable-length
integer encoding.
Flows are bidirectional exchanges of datagrams within a single QUIC
connection.  These are conceptually similar to streams in the sense
that they allow multiplexing of application data.  Flows are
identified within a connection by a numeric value, referred to as the
flow ID.  A flow ID is a 62-bit integer (0 to 2^62-1).
Flows lack any of the ordering or reliability guarantees of streams.
Beyond this, a sender SHOULD ensure that DATAGRAM frames within a
single flow are transmitted in order relative to one another.  If
multiple DATAGRAM frames can be packed into a single QUIC packet, the
sender SHOULD group them by flow to promote fate-sharing within a
specific flow and improve the ability to process batches of datagram
messages efficiently on the receiver.
Implementations of HTTP/3 that support the DATAGRAM extension MUST
provide a flow ID allocation service.  That service will allow
applications co-located with HTTP/3 to request a unique flow ID that
they can subsequently use for their own purposes.  The HTTP/3
implementation will then parse the flow ID of incoming DATAGRAM
frames and use it to deliver the frame to the appropriate application
context.
Even-numbered flow IDs are client-initiated, while odd-numbered flow
IDs are server-initiated.  This means that an HTTP/3 client
implementation of the flow ID allocation service MUST only provide
even-numbered IDs, while a server implementation MUST only provide
odd-numbered IDs.  Note that, once allocated, any flow ID can be used
by both client and server - only allocation carries separate
namespaces to avoid requiring synchronization.
The flow ID allocation service SHOULD also provide a mechanism for
applications to indicate they have completed their usage of a flow ID
and will no longer be using that flow ID, this process is called
"retiring" a flow ID.  Applications MUST NOT retire a flow ID until
after they have received confirmation that the peer has also stopped
using that flow ID.  The flow ID allocation service MAY reuse
previously retired flow ID once they have ascertained that there are
no packets with DATAGRAM frames using that flow ID still in flight.
Reusing flow IDs can improve performance by transmitting the flow ID
using a shorter variable-length integer encoding.
A variable-length integer indicating the Flow Identifier of the
datagram (see flow-id).
Endpoints MUST treat receipt of a DATAGRAM frame whose payload is too
short to parse the flow identifier as an HTTP/3 connection error of
type H3_GENERAL_PROTOCOL_ERROR.
A variable-length integer indicating the Flow ID of the datagram
(see datagram-flows).
Endpoints MUST treat receipt of a DATAGRAM frame whose payload is too
short to parse the flow ID as an HTTP/3 connection error of type
H3_GENERAL_PROTOCOL_ERROR.
Even if a sender attempts to communicate the meaning of a flow
identifier before it uses it in an HTTP/3 datagram, it is possible
that its peer will receive an HTTP/3 datagram with a flow identifier
that it does not know as it has not yet received the corresponding
"Datagram-Flow-Id" header field.  (For example, this could happen if
the QUIC STREAM frame that contains the "Datagram-Flow-Id" header
field is reordered and arrives afer the DATAGRAM frame.)  Endpoints
MUST NOT treat that scenario as an error; they MUST either silently
discard the datagram or buffer it until they receive the "Datagram-
Flow-Id" header field.
Distinct HTTP requests MAY refer to the same flow identifier in their
respective "Datagram-Flow-Id" header fields.
Note that integer structured fields can only encode values up to
10^15-1, therefore the maximum possible value of an element of the
"Datagram-Flow-Id" header field is lower then the theoretical maximum
value of a flow identifier which is 2^62-1 due to the QUIC variable
length integer encoding.  If the flow identifier allocation service
of an endpoint runs out of values lower than 10^15-1, the endpoint
MUST fail the flow identifier allocation.  An HTTP message that
carries a "Datagram-Flow-Id" header field with a flow identifier
value above 10^15-1 is malformed (see Section 8.1.2.6 of H2).
HTTP/3 DATAGRAM flow identifiers are specific to a given HTTP/3
connection.  However, in some cases, an HTTP request may travel
across multiple HTTP connections if there are HTTP intermediaries
involved; see Section 2.3 of RFC7230.
Even if a sender attempts to communicate the meaning of a flow before
it uses it in an HTTP/3 datagram, it is possible that its peer will
receive an HTTP/3 datagram with a flow ID that it does not know as it
has not yet received the corresponding "Datagram-Flow-Id" header
field.  (For example, this could happen if the QUIC STREAM frame that
contains the "Datagram-Flow-Id" header field is reordered and arrives
afer the DATAGRAM frame.)  Endpoints MUST NOT treat that scenario as
an error; they MUST either silently discard the datagram or buffer it
until they receive the "Datagram-Flow-Id" header field.
Distinct HTTP requests MAY refer to the same flow in their respective
"Datagram-Flow-Id" header fields.
Note that integer structured fields can only encode values up to
10^15-1, therefore the maximum possible value of an element of the
"Datagram-Flow-Id" header field is lower then the theoretical maximum
value of a flow ID which is 2^62-1 due to the QUIC variable length
integer encoding.  If the flow allocation service of an endpoint runs
out of flow ID values lower than 10^15-1, the endpoint MUST fail the
flow ID allocation.  An HTTP message that carries a "Datagram-Flow-
Id" header field with a flow ID value above 10^15-1 is malformed (see
Section 8.1.2.6 of H2).
HTTP/3 DATAGRAM flows are specific to a given HTTP/3 connection.
However, in some cases, an HTTP request may travel across multiple
HTTP connections if there are HTTP intermediaries involved; see
Section 2.3 of RFC7230.
If an intermediary processes distinct HTTP requests that refer to the
same flow identifier in their respective "Datagram-Flow-Id" header
fields, it MUST ensure that those requests are routed to the same
backend.
If an intermediary processes distinct HTTP requests that refer to the
same flow ID in their respective "Datagram-Flow-Id" header fields, it
MUST ensure that those requests are routed to the same backend.
The key of a parameter that is associated with a datagram flow
identifier list member (see header).  Keys MUST be valid
structured field parameter keys (see Section 3.1.2 of STRUCT-
FIELD).
The key of a parameter that is associated with a datagram flow
list member (see header).  Keys MUST be valid structured field
parameter keys (see Section 3.1.2 of STRUCT-FIELD).