HTTP Datagrams and the Capsule Protocol
Extracted elements (28)
New HTTP extensions that use HTTP Datagrams SHOULD use the Capsule Protocol because failing to do so makes it harder to support HTTP versions other than HTTP/3 and prevents interoperability with intermediaries that only support the Capsule Protocol.
Preserving the unreliable delivery characteristic of QUIC DATAGRAM frames end-to-end is important because methods such as DPLPMTUD depend on it. An intermediary that converts QUIC DATAGRAM frames to DATAGRAM Capsules allows arbitrarily large HTTP Datagrams without loss, misrepresenting the true path properties and defeating PMTU discovery.
The Quarter Stream ID field encodes the QUIC stream ID divided by four because HTTP requests are sent on client-initiated bidirectional streams whose IDs are divisible by four. This division reduces the encoded value and exploits a structural property of QUIC stream ID assignment.
In HTTP/1.x, only the last HTTP request on a connection can start the Capsule Protocol because the data stream consists of all bytes following the blank line concluding the header section, making it impossible to multiplex Capsule Protocol sessions on a single HTTP/1.x connection.
The Capsule Protocol only applies to definitions of new HTTP upgrade tokens; in HTTP/2 and HTTP/3, it can only be used with the CONNECT method, which changes the frame usage requirements per Section 8.5 of HTTP/2 and Section 4.4 of HTTP/3.
Each Capsule's payload MUST contain exactly the fields identified in its description. A Capsule payload with extra bytes or one that terminates before the end of the identified fields MUST be treated as malformed. Redundant length encodings MUST be verified to be self-consistent.
Endpoints that receive a Capsule with an unknown Capsule Type MUST silently drop that Capsule and skip over it to parse the next Capsule. Intermediaries SHOULD forward unknown Capsule Types without modification.
HTTP/3 Datagrams MUST NOT be sent unless the corresponding stream's send side is open. If a datagram is received after the corresponding stream's receive side is closed, the received datagrams MUST be silently dropped.
HTTP Datagrams MUST only be sent with an association to an HTTP request that explicitly supports them. Existing HTTP methods GET and POST do not define semantics for associated HTTP Datagrams.
If an HTTP Datagram is received and it is associated with a request that has no known semantics for HTTP Datagrams, the receiver MUST terminate the request. If HTTP/3 is in use, the request stream MUST be aborted with H3_DATAGRAM_ERROR (0x33).
If an intermediary receives an HTTP Datagram in a QUIC DATAGRAM frame and is forwarding on a connection that supports QUIC DATAGRAM frames, the intermediary SHOULD NOT convert it to a DATAGRAM Capsule. If too large to fit in a DATAGRAM frame, the intermediary SHOULD drop the datagram rather than convert it.
If the receive side of a stream carrying Capsules is terminated cleanly and the last Capsule was truncated, this MUST be treated as a malformed or incomplete message.
Intermediaries MUST NOT re-encode HTTP Datagrams between QUIC DATAGRAM frames and DATAGRAM Capsules unless they have identified the use of the Capsule Protocol on the corresponding request stream.
QUIC DATAGRAM frames MUST NOT be sent until the SETTINGS_H3_DATAGRAM setting has been both sent and received with a value of 1.
Receipt of an HTTP/3 Datagram with a Quarter Stream ID larger than 2^60-1 MUST be treated as an HTTP/3 connection error of type H3_DATAGRAM_ERROR (0x33). Receipt of a QUIC DATAGRAM frame whose payload is too short to parse the Quarter Stream ID MUST also be treated as H3_DATAGRAM_ERROR.
Receivers SHOULD avoid accumulating the full Capsule Value field before processing, because doing so can consume flow control in underlying layers and lead to deadlocks if Capsule data exhausts the flow control window.
The Capsule-Protocol header field MUST NOT be used on HTTP responses with a status code different from 101 and outside the 2xx range.
The Capsule Protocol MUST NOT be used with messages that contain Content-Length, Content-Type, or Transfer-Encoding header fields. HTTP status codes 204, 205, and 206 MUST NOT be sent on responses using the Capsule Protocol.
When servers accept 0-RTT data, they MUST send a SETTINGS_H3_DATAGRAM setting greater than or equal to the value sent in the connection where the NewSessionTicket was sent. Clients MUST validate the new setting value is >= the stored value, and terminate with H3_SETTINGS_ERROR if not.
The Capsule-Protocol header field is an Item Structured Field (RFC 8941) whose value MUST be a Boolean. A true value indicates Capsule Protocol use on a data stream. Unknown parameters MUST be ignored.
The SETTINGS_H3_DATAGRAM (0x33) HTTP/3 setting allows an endpoint to indicate willingness to receive HTTP/3 Datagrams. Its value MUST be 0 or 1; any other value causes the receiver to terminate the connection with H3_SETTINGS_ERROR.
IANA has registered SETTINGS_H3_DATAGRAM (value 0x33, default 0) in the HTTP/3 Settings registry and H3_DATAGRAM_ERROR (value 0x33) in the HTTP/3 Error Codes registry, both referencing RFC 9297.
IANA has registered the 'Capsule-Protocol' header field in the HTTP Field Name Registry (permanent, RFC 9297) and established a new 'HTTP Capsule Types' registry governing a 62-bit space under the QUIC registration policy. Values 0x00–0x3f require Standards Action or IESG Approval; others use Specification Required. DATAGRAM (0x00) is the initial entry.
Sending the SETTINGS_H3_DATAGRAM setting 'sticks out', allowing probing clients to detect whether a server supports HTTP Datagrams over QUIC DATAGRAM frames. To mitigate this fingerprinting, implementations that support the feature are recommended to always send the setting with value 1, even when the application does not intend to use HTTP Datagrams.
Since use of the Capsule Protocol is restricted to new HTTP upgrade tokens, it is not directly accessible from Web Platform APIs such as JavaScript in web browsers, limiting the attack surface.
Capsule format: Capsule Type (variable-length integer), Capsule Length (variable-length integer encoding the byte length of Capsule Value), Capsule Value (payload of variable length determined by Capsule Length).
DATAGRAM Capsule format: Type field (variable-length integer) = 0x00, Length (variable-length integer), HTTP Datagram Payload (variable length, semantics defined by using extension, may be empty).
HTTP/3 Datagram format: Quarter Stream ID (variable-length integer, client-initiated bidirectional stream ID divided by four) followed by HTTP Datagram Payload (variable length). The Quarter Stream ID field encodes the associated QUIC stream ID / 4.