Draft: draft-ietf-masque-h3-datagram

Commentary: Had offline conversation with Lucas , conclusion was that this is good enough to merge to allow interop - we 'll have plenty of time to figure out details in subsequent issues and PRs .
CAPSULE allows reliably sending request-related information end-to-
end, even in the presence of HTTP intermediaries.
CAPSULE is an HTTP/3 Frame (as opposed to a QUIC frame) which SHALL
only be sent in client-initiated bidirectional streams.
Intermediaries forward received CAPSULE frames on the same stream
where it would forward DATA frames.  Each Capsule Type determines
whether it is opaque or transparent to intermediaries: opaque
capsules are forwarded unmodified while transparent ones can be
parsed, added, or removed by intermediaries.
This specification of CAPSULE currently uses HTTP/3 frame type
0xffcab5.  If this document is approved, a lower number will be
requested from IANA.
The type of this capsule.
Data whose semantics depends on the Capsule Type.
This specification introduces the Capsule Protocol.  The Capsule
Protocol is a sequence of type-length-value tuples that allows
endpoints to reliably communicate request-related information end-to-
end, even in the presence of HTTP intermediaries.
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.  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.
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.
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.
The payload of this capsule.  Its semantics are determined by the
value of the Capsule Type field.
A server MUST NOT send any Transfer-Encoding or Content-Length
header fields in a 2xx (Successful) response.  If a client
receives a Content-Length or Transfer-Encoding header fields in a
successful response, it MUST treat that response as malformed.
A request message does not have content.
A successful response message does not have content.
Responses are not cacheable.
In this mode, the intermediary forwards the data stream between
two associated streams without any modification of the data
stream.
In this mode, the intermediary terminates the data stream and
parses all Capsule Type and Capsule Length fields it receives.
Each Capsule Type determines whether it is opaque or transparent 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 the
Capsule Data field of transparent capsule types.
Receipt of a CAPSULE HTTP/3 Frame on a stream that is not a client-
initiated bidirectional stream MUST be treated as a connection error
of type H3_FRAME_UNEXPECTED.
CAPSULE frames MUST NOT be sent on a stream before at least one
HEADERS frame has been sent on that stream.  This removes the need to
buffer capsules when the endpoint needs information from headers to
determine how to react to the capsule.  If a CAPSULE frame is
received on a stream before a HEADERS frame, the receiver MUST treat
this as a connection error of type H3_FRAME_UNEXPECTED.
We can provide DATAGRAM support in HTTP/2 by defining the CAPSULE
frame in HTTP/2.
We can provide DATAGRAM support in HTTP/1.x by defining its data
stream format to a sequence of length-value capsules.
TODO: Refactor this document and add definitions for HTTP/1.x and
HTTP/2.
The value of the Capsule Type field (see capsule-frame) is a 62bit
integer.
The value of the Capsule Type field (see capsule-protocol) is a
62bit integer.