1.1.Conventions and Definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED","MAY", and "OPTIONAL" in this document are to be interpreted asdescribed in BCP 14[RFC2119][RFC8174] when, and only when, theyappear in all capitals, as shown here.¶

This document uses terminology from[QUIC].¶

Where this document defines protocol types, the definition format uses thenotation fromSection 1.3 of [QUIC]. Where fields within types are integers,they are encoded using the variable-length integer encoding fromSection 16 of [QUIC]. Integer values do not need to be encoded on the minimum number of bytesnecessary.¶

In this document, the term "intermediary" refers to an HTTP intermediary asdefined inSection 3.7 of [HTTP].¶

2.1.HTTP/3 Datagrams

When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM frames uses thefollowing format:¶

HTTP/3 Datagram {  Quarter Stream ID (i),  HTTP Datagram Payload (..),}

Quarter Stream ID:

A variable-length integer that contains the value of the client-initiatedbidirectional stream that this datagram is associated with divided by four (thedivision by four stems from the fact that HTTP requests are sent onclient-initiated bidirectional streams, which have stream IDs that are divisibleby four). The largest legal QUIC stream ID value is 2⁶²-1, so thelargest legal value of the Quarter Stream ID field is 2⁶⁰-1. Receiptof an HTTP/3 Datagram that includes a larger valueMUST be treated as an HTTP/3connection error of type H3_DATAGRAM_ERROR (0x33).¶

HTTP Datagram Payload:

The payload of the datagram, whose semantics are defined by the extension thatis using HTTP Datagrams. Note that this field can be empty.¶

Receipt of a QUIC DATAGRAM frame whose payload is too short to allow parsing theQuarter Stream ID fieldMUST be treated as an HTTP/3 connection error of typeH3_DATAGRAM_ERROR (0x33).¶

HTTP/3 DatagramsMUST NOT be sent unless the corresponding stream's send side isopen. If a datagram is received after the corresponding stream's receive side isclosed, the received datagramsMUST be silently dropped.¶

If an HTTP/3 Datagram is received and its Quarter Stream ID field maps to astream that has not yet been created, the receiverSHALL either drop thatdatagram silently or buffer it temporarily (on the order of a round trip) whileawaiting the creation of the corresponding stream.¶

If an HTTP/3 Datagram is received and its Quarter Stream ID field maps to astream that cannot be created due to client-initiated bidirectional streamlimits, itSHOULD be treated as an HTTP/3 connection error of type H3_ID_ERROR.Generating an error is not mandatory because the QUIC stream limit might beunknown to the HTTP/3 layer.¶

Prioritization of HTTP/3 Datagrams is not defined in this document. FutureextensionsMAY define how to prioritize datagrams andMAY define signaling toallow communicating prioritization preferences.¶

2.2.HTTP Datagrams Using Capsules

When HTTP/3 Datagrams are unavailable or undesirable, HTTP Datagrams can be sentusing the Capsule Protocol; seeSection 3.5.¶

3.1.HTTP Data Streams

This specification defines the "data stream" of an HTTP request as thebidirectional stream of bytes that follows the header section of the requestmessage and the final response message that is either successful (i.e., 2xx) orupgraded (i.e., 101).¶

In HTTP/1.x, the data stream consists of all bytes on the connection that followthe blank line that concludes either the request header section or the finalresponse header section. As a result, only the last HTTP request on an HTTP/1.xconnection can start the Capsule Protocol.¶

In HTTP/2 and HTTP/3, the data stream of a given HTTP request consists of allbytes sent in DATA frames with the corresponding stream ID.¶

The concept of a data stream is particularly relevant for methods such asCONNECT, where there is no HTTP message content after the headers.¶

Data streams can be prioritized using any means suited to stream or requestprioritization. For example, seeSection 11 of [PRIORITY].¶

Data streams are subject to the flow control mechanisms of the underlyinglayers; examples include HTTP/2 stream flow control, HTTP/2 connection flowcontrol, and TCP flow control.¶

3.2.The Capsule Protocol

Definitions of new HTTP upgrade tokens can state that their associated request'sdata stream uses the Capsule Protocol. If they do so, the contents of theassociated request's data stream uses the following format:¶

Capsule Protocol {  Capsule (..) ...,}

Capsule {  Capsule Type (i),  Capsule Length (i),  Capsule Value (..),}

Capsule Type:

A variable-length integer indicating the type of the capsule. An IANA registryis used to manage the assignment of Capsule Types; seeSection 5.4.¶

Capsule Length:

The length, in bytes, of the Capsule Value field, which follows this field,encoded as a variable-length integer. Note that this field can have a value ofzero.¶

Capsule Value:

The payload of this Capsule. Its semantics are determined by the value of theCapsule Type field.¶

An intermediary can identify the use of the Capsule Protocol either through thepresence of the Capsule-Protocol header field (Section 3.4) or by understanding thechosen HTTP Upgrade token.¶

Because new protocols or extensions might define new Capsule Types,intermediaries that wish to allow for future extensibilitySHOULD forwardCapsules without modification unless the definition of the Capsule Type in usespecifies additional intermediary processing. One such Capsule Type is theDATAGRAM Capsule; seeSection 3.5. In particular, intermediariesSHOULDforward Capsules with an unknown Capsule Type without modification.¶

Endpoints that receive a Capsule with an unknown Capsule TypeMUST silentlydrop that Capsule and skip over it to parse the next Capsule.¶

By virtue of the definition of the data stream:¶

• The Capsule Protocol is not in use unless the response includes a 2xx(Successful) or 101 (Switching Protocols) status code.¶
• When the Capsule Protocol is in use, the associated HTTP request and responsedo not carry HTTP content. A future extensionMAY define a new Capsule Type tocarry HTTP content.¶

The Capsule Protocol only applies to definitions of new HTTP upgrade tokens;thus, in HTTP/2 and HTTP/3, it can only be used with the CONNECT method.Therefore, once both endpoints agree to use the Capsule Protocol, the frameusage requirements of the stream change as specified inSection 8.5 of [HTTP/2]andSection 4.4 of [HTTP/3].¶

The Capsule ProtocolMUST NOT be used with messages that contain Content-Length,Content-Type, or Transfer-Encoding header fields. Additionally, HTTP statuscodes 204 (No Content), 205 (Reset Content), and 206 (Partial Content)MUST NOTbe sent on responses that use the Capsule Protocol. A receiver that observes aviolation of these requirementsMUST treat the HTTP message as malformed.¶

When processing Capsules, a receiver might be tempted to accumulate the fulllength of the Capsule Value field in the data stream before handling it. ThisapproachSHOULD be avoided because it can consume flow control in underlyinglayers, and that might lead to deadlocks if the Capsule data exhausts the flowcontrol window.¶

3.3.Error Handling

When a receiver encounters an error processing the Capsule Protocol, thereceiverMUST treat it as if it had received a malformed or incomplete HTTPmessage. For HTTP/3, the handling of malformed messages is described inSection 4.1.2 of [HTTP/3]. For HTTP/2, the handling of malformed messages isdescribed inSection 8.1.1 of [HTTP/2]. For HTTP/1.x, the handling of incompletemessages is described inSection 8 of [HTTP/1.1].¶

Each Capsule's payloadMUST contain exactly the fields identified in itsdescription. A Capsule payload that contains additional bytes after theidentified fields or a Capsule payload that terminates before the end of theidentified fieldsMUST be treated as it if were a malformed or incompletemessage. In particular, redundant length encodingsMUST be verified to beself-consistent.¶

If the receive side of a stream carrying Capsules is terminated cleanly (forexample, in HTTP/3 this is defined as receiving a QUIC STREAM frame with the FINbit set) and the last Capsule on the stream was truncated, thisMUST be treatedas if it were a malformed or incomplete message.¶

3.4.The Capsule-Protocol Header Field

The "Capsule-Protocol" header field is an Item Structured Field; seeSection 3.3 of [STRUCTURED-FIELDS]. Its valueMUST be a Boolean; any othervalue typeMUST be handled as if the field were not present by recipients (forexample, if this field is included multiple times, its type will become a Listand the field will be ignored). This document does not define any parameters forthe Capsule-Protocol header field value, but future documents might defineparameters. ReceiversMUST ignore unknown parameters.¶

Endpoints indicate that the Capsule Protocol is in use on a data stream bysending a Capsule-Protocol header field with a true value. A Capsule-Protocolheader field with a false value has the same semantics as when the header is notpresent.¶

IntermediariesMAY use this header field to allow processing of HTTP Datagramsfor unknown HTTP upgrade tokens. Note that this is only possible for HTTPUpgrade or Extended CONNECT.¶

The Capsule-Protocol header fieldMUST NOT be used on HTTP responses with astatus code that is both different from 101 (Switching Protocols) and outsidethe 2xx (Successful) range.¶

When using the Capsule Protocol, HTTP endpointsSHOULD send the Capsule-Protocolheader field to simplify intermediary processing. Definitions of new HTTPupgrade tokens that use the Capsule ProtocolMAY alter this recommendation.¶

3.5.The DATAGRAM Capsule

This document defines the DATAGRAM (0x00) Capsule Type. This Capsule allows HTTPDatagrams to be sent on a stream using the Capsule Protocol. This isparticularly useful when HTTP is running over a transport that does not supportthe QUIC DATAGRAM frame.¶

Datagram Capsule {  Type (i) = 0x00,  Length (i),  HTTP Datagram Payload (..),}

HTTP Datagram Payload:

The payload of the datagram, whose semantics are defined by the extension thatis using HTTP Datagrams. Note that this field can be empty.¶

HTTP Datagrams sent using the DATAGRAM Capsule have the same semantics as thosesent in QUIC DATAGRAM frames. In particular, the restrictions on when it isallowed to send an HTTP Datagram and how to process them (fromSection 2.1) alsoapply to HTTP Datagrams sent and received using the DATAGRAM Capsule.¶

An intermediary can re-encode HTTP Datagrams as it forwards them. In otherwords, an intermediaryMAY send a DATAGRAM Capsule to forward an HTTP Datagramthat was received in a QUIC DATAGRAM frame and vice versa. IntermediariesMUST NOT perform this re-encoding unless they have identified the use of the CapsuleProtocol on the corresponding request stream; seeSection 3.2.¶

Note that while DATAGRAM Capsules, which are sent on a stream, are reliablydelivered in order, intermediaries can re-encode DATAGRAM Capsules into QUICDATAGRAM frames when forwarding messages, which could result in loss orreordering.¶

If an intermediary receives an HTTP Datagram in a QUIC DATAGRAM frame and isforwarding it on a connection that supports QUIC DATAGRAM frames, theintermediarySHOULD NOT convert that HTTP Datagram to a DATAGRAM Capsule. If theHTTP Datagram is too large to fit in a DATAGRAM frame (for example, because thePath MTU (PMTU) of that QUIC connection is too low or if the maximum UDP payloadsize advertised on that connection is too low), the intermediarySHOULD drop theHTTP Datagram instead of converting it to a DATAGRAM Capsule. This preserves theend-to-end unreliability characteristic that methods such as DatagramPacketization Layer PMTU Discovery (DPLPMTUD) depend on[DPLPMTUD].An intermediary that converts QUIC DATAGRAM frames to DATAGRAM Capsules allowsHTTP Datagrams to be arbitrarily large without suffering any loss. This canmisrepresent the true path properties, defeating methods such as DPLPMTUD.¶

While DATAGRAM Capsules can theoretically carry a payload of length2⁶²-1, most HTTP extensions that use HTTP Datagrams will have theirown limits on what datagram payload sizes are practical. ImplementationsSHOULDtake those limits into account when parsing DATAGRAM Capsules. If an incomingDATAGRAM Capsule has a length that is known to be so large as to not be usable,the implementationSHOULD discard the Capsule without buffering its contentsinto memory.¶

Since QUIC DATAGRAM frames are required to fit within a QUIC packet,implementations that re-encode DATAGRAM Capsules into QUIC DATAGRAM frames mightbe tempted to accumulate the entire Capsule in the stream before re-encoding it.ThisSHOULD be avoided, because it can cause flow control problems; seeSection 3.2.¶

Note that it is possible for an HTTP extension to use HTTP Datagrams withoutusing the Capsule Protocol. For example, if an HTTP extension that uses HTTPDatagrams is only defined over transports that support QUIC DATAGRAM frames, itmight not need a stream encoding. Additionally, HTTP extensions can use HTTPDatagrams with their own data stream protocol. However, new HTTP extensions thatwish to use HTTP DatagramsSHOULD use the Capsule Protocol, as failing to do sowill make it harder for the HTTP extension to support versions of HTTP otherthan HTTP/3 and will prevent interoperability with intermediaries that onlysupport the Capsule Protocol.¶

5.1.HTTP/3 Setting

IANA has registered the following entry in the "HTTP/3 Settings" registrymaintained at <https://www.iana.org/assignments/http3-parameters>:¶

Value:

0x33¶

Setting Name:

SETTINGS_H3_DATAGRAM¶

Default:

0¶

Status:

permanent¶

Reference:

RFC 9297¶

Change Controller:

IETF¶

Contact:

HTTP_WG; HTTP working group; ietf-http-wg@w3.org¶

Notes:

None¶

5.2.HTTP/3 Error Code

IANA has registered the following entry in the "HTTP/3 Error Codes" registrymaintained at <https://www.iana.org/assignments/http3-parameters>:¶

Value:

0x33¶

Name:

H3_DATAGRAM_ERROR¶

Description:

Datagram or Capsule Protocol parse error¶

Status:

permanent¶

Reference:

RFC 9297¶

Change Controller:

IETF¶

Contact:

HTTP_WG; HTTP working group; ietf-http-wg@w3.org¶

Notes:

None¶

5.3.HTTP Header Field Name

IANA has registered the following entry in the "Hypertext Transfer Protocol(HTTP) Field Name Registry" maintained at<https://www.iana.org/assignments/http-fields>:¶

Field Name:

Capsule-Protocol¶

Template:

None¶

Status:

permanent¶

Reference:

RFC 9297¶

Comments:

None¶

5.4.Capsule Types

This document establishes a registry for HTTP Capsule Type codes. The "HTTPCapsule Types" registry governs a 62-bit space and operates under the QUICregistration policy documented inSection 22.1 of [QUIC]. This new registryincludes the common set of fields listed inSection 22.1.1 of [QUIC]. Inaddition to those common fields, all registrations in this registryMUST includea "Capsule Type" field that contains a short name or label for the Capsule Type.¶

Permanent registrations in this registry are assigned using the SpecificationRequired policy (Section 4.6 of [IANA-POLICY]), except for valuesbetween 0x00 and 0x3f (in hexadecimal; inclusive), which are assigned usingStandards Action or IESG Approval as defined in Sections4.9 and4.10 of[IANA-POLICY].¶

Capsule Types with a value of the form 0x29 * N + 0x17 for integer values of Nare reserved to exercise the requirement that unknown Capsule Types be ignored.These Capsules have no semantics and can carry arbitrary values. These valuesMUST NOT be assigned by IANA andMUST NOT appear in the listing of assignedvalues.¶

This registry initially contains the following entry:¶

Value:

0x00¶

Capsule Type:

DATAGRAM¶

Status:

permanent¶

Reference:

RFC 9297¶

Change Controller:

IETF¶

Contact:

MASQUE Working Groupmasque@ietf.org¶

Notes:

None¶