Hypertext Transfer Protocol (HTTP) over QUIC

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 as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

Field definitions are given in Augmented Backus-Naur Form (ABNF), as defined in [RFC5234].¶

This document uses the variable-length integer encoding from [QUIC-TRANSPORT].¶

Protocol elements called “frames” exist in both this document and [QUIC-TRANSPORT]. Where frames from [QUIC-TRANSPORT] are referenced, the frame name will be prefaced with “QUIC.” For example, “QUIC APPLICATION_CLOSE frames.” References without this preface refer to frames defined in Section 5.2.¶

Where multiple versions are listed, the order of the values reflects the server’s preference (with the first value being the most preferred version). Origins SHOULD list only versions which are supported by the alternative, but MAY omit supported versions for any reason.¶

• RFC Editor’s Note: Please remove this section prior to publication of a final version of this document.

Only implementations of the final, published RFC can identify themselves as “hq”. Until such an RFC exists, implementations MUST NOT identify themselves using this string.¶

Implementations of draft versions of the protocol MUST add the string “-“ and the corresponding draft number to the identifier. For example, draft-ietf-quic-http-01 is identified using the string “hq-01”.¶

Non-compatible experiments that are based on these draft versions MUST append the string “-“ and an experiment name to the identifier. For example, an experimental implementation based on draft-ietf-quic-http-09 which reserves an extra stream for unsolicited transmission of 1980s pop music might identify itself as “hq-09-rickroll”. Note that any label MUST conform to the “token” syntax defined in Section 3.2.6 of [RFC7230]. Experimenters are encouraged to coordinate their experiments on the quic@ietf.org mailing list.¶

Since most connection-level concerns will be managed by QUIC, the primary use of Streams 2 and 3 will be for the SETTINGS frame when the connection opens and for PRIORITY frames subsequently.¶

A pair of unidirectional streams is used rather than a single bidirectional stream. This allows either peer to send data as soon they are able. Depending on whether 0-RTT is enabled on the connection, either client or server might be able to send stream data first after the cryptographic handshake completes.¶

A client sends an HTTP request on a client-initiated, bidirectional QUIC stream. A server sends an HTTP response on the same stream as the request.¶

1. one header block (see Section 5.2.2) containing the message headers (see [RFC7230], Section 3.2),
2. the payload body (see [RFC7230], Section 3.3), sent as a series of DATA frames (see Section 5.2.1),
3. optionally, one header block containing the trailer-part, if present (see [RFC7230], Section 4.1.2).

In addition, prior to sending the message header block indicated above, a response may contain zero or more header blocks containing the message headers of informational (1xx) HTTP responses (see [RFC7230], Section 3.2 and [RFC7231], Section 6.2).¶

PUSH_PROMISE frames MAY be interleaved with the frames of a response message indicating a pushed resource related to the response. These PUSH_PROMISE frames are not part of the response, but carry the headers of a separate HTTP request message. See Section 4.4 for more details.¶

The “chunked” transfer encoding defined in Section 4.1 of [RFC7230] MUST NOT be used.¶

Trailing header fields are carried in an additional header block following the body. Such a header block is a sequence of HEADERS frames with End Header Block set on the last frame. Senders MUST send only one header block in the trailers section; receivers MUST discard any subsequent header blocks.¶

An HTTP request/response exchange fully consumes a QUIC stream. After sending a request, a client closes the stream for sending; after sending a response, the server closes the stream for sending and the QUIC stream is fully closed.¶

A server can send a complete response prior to the client sending an entire request if the response does not depend on any portion of the request that has not been sent and received. When this is true, a server MAY request that the client abort transmission of a request without error by triggering a QUIC STOP_SENDING with error code HTTP_EARLY_RESPONSE, sending a complete response, and cleanly closing its streams. Clients MUST NOT discard complete responses as a result of having their request terminated abruptly, though clients can always discard responses at their discretion for other reasons. Servers MUST NOT abort a response in progress as a result of receiving a solicited RST_STREAM.¶

HTTP/QUIC uses the priority scheme described in [RFC7540], Section 5.3. In this priority scheme, a given request can be designated as dependent upon another request, which expresses the preference that the latter stream (the “parent” request) be allocated resources before the former stream (the “dependent” request). Taken together, the dependencies across all requests in a connection form a dependency tree. The structure of the dependency tree changes as PRIORITY frames add, remove, or change the dependency links between requests.¶

HTTP/2 defines its priorities in terms of streams whereas HTTP over QUIC identifies requests. The PRIORITY frame Section 5.2.3 identifies a request either by identifying the stream that carries a request or by using a Push ID (Section 5.2.6). Other than the means of identifying requests, the prioritization system is identical to that in HTTP/2.¶

Only a client can send PRIORITY frames. A server MUST NOT send a PRIORITY frame.¶

HTTP/QUIC supports server push as described in [RFC7540]. During connection establishment, the client enables server push by sending a MAX_PUSH_ID frame (see Section 5.2.8). A server cannot use server push until it receives a MAX_PUSH_ID frame.¶

As with server push for HTTP/2, the server initiates a server push by sending a PUSH_PROMISE frame that includes request header fields attributed to the request. The PUSH_PROMISE frame is sent on the client-initiated, bidirectional stream that carried the request that generated the push. This allows the server push to be associated with a request. Ordering of a PUSH_PROMISE in relation to certain parts of the response is important (see Section 8.2.1 of [RFC7540]).¶

Unlike HTTP/2, the PUSH_PROMISE does not reference a stream; when a server fulfills a promise, the stream that carries the stream headers references a Push ID. This allows a server to fulfill promises in the order that best suits its needs.¶

The server push response is conveyed on a push stream. A push stream is a server-initiated, unidirectional stream. A push stream includes a header (see Figure 1) that identifies the PUSH_PROMISE that it fulfills. This header consists of a Push ID, encoded as a variable-length integer. The Push ID identifies a server push (see Section 5.2.6).¶

A push stream always starts with a Push ID. A client MUST treat receiving a push stream that contains a truncated variable-length integer as a connection error of type HTTP_MALFORMED_PUSH.¶

A server SHOULD use Push IDs sequentially, starting at 0. A client uses the MAX_PUSH_ID frame (Section 5.2.8) to limit the number of pushes that a server can promise. A client MUST treat receipt of a push stream with a Push ID that is greater than the maximum Push ID as a connection error of type HTTP_MALFORMED_PUSH.¶

Each Push ID MUST only be used once in a push stream header. If a push stream header includes a Push ID that was used in another push stream header, the client MUST treat this as a connection error of type HTTP_MALFORMED_PUSH. The same Push ID can be used in multiple PUSH_PROMISE frames (see Section 5.2.6).¶

After the push stream header, a push contains a response (Section 4.2), with response headers, a response body (if any) carried by DATA frames, then trailers (if any) carried by HEADERS frames.¶

If a promised server push is not needed by the client, the client SHOULD send a CANCEL_PUSH frame; if the push stream is already open, a QUIC STOP_SENDING frame with an appropriate error code can be used instead (e.g., HTTP_PUSH_REFUSED, HTTP_PUSH_ALREADY_IN_CACHE; see Section 7). This asks the server not to transfer the data and indicates that it will be discarded upon receipt.¶

Length:

A variable-length integer that describes the length of the Frame Payload. This length does not include the frame header.

Type:

An 8-bit type for the frame.

Flags:

An 8-bit field containing flags. The Type field determines the semantics of flags.

Frame Payload:

A payload, the semantics of which are determined by the Type field.

The following error codes are defined for use in QUIC RST_STREAM, STOP_SENDING, and CONNECTION_CLOSE frames when using HTTP/QUIC.¶

STOPPING (0x00):

This value is reserved by the transport to be used in response to QUIC STOP_SENDING frames.

HTTP_NO_ERROR (0x01):

No error. This is used when the connection or stream needs to be closed, but there is no error to signal.

HTTP_PUSH_REFUSED (0x02):

The server has attempted to push content which the client will not accept on this connection.

HTTP_INTERNAL_ERROR (0x03):

An internal error has occurred in the HTTP stack.

HTTP_PUSH_ALREADY_IN_CACHE (0x04):

The server has attempted to push content which the client has cached.

HTTP_REQUEST_CANCELLED (0x05):

The client no longer needs the requested data.

HTTP_HPACK_DECOMPRESSION_FAILED (0x06):

HPACK failed to decompress a frame and cannot continue.

HTTP_CONNECT_ERROR (0x07):

The connection established in response to a CONNECT request was reset or abnormally closed.

HTTP_EXCESSIVE_LOAD (0x08):

The endpoint detected that its peer is exhibiting a behavior that might be generating excessive load.

HTTP_VERSION_FALLBACK (0x09):

The requested operation cannot be served over HTTP/QUIC. The peer should retry over HTTP/2.

HTTP_MALFORMED_HEADERS (0x0A):

A HEADERS frame has been received with an invalid format.

HTTP_MALFORMED_PRIORITY (0x0B):

A PRIORITY frame has been received with an invalid format.

HTTP_MALFORMED_SETTINGS (0x0C):

A SETTINGS frame has been received with an invalid format.

HTTP_MALFORMED_PUSH_PROMISE (0x0D):

A PUSH_PROMISE frame has been received with an invalid format.

HTTP_MALFORMED_DATA (0x0E):

A DATA frame has been received with an invalid format.

HTTP_INTERRUPTED_HEADERS (0x0F):

A HEADERS frame without the End Header Block flag was followed by a frame other than HEADERS.

HTTP_WRONG_STREAM (0x10):

A frame was received on stream where it is not permitted.

HTTP_MULTIPLE_SETTINGS (0x11):

More than one SETTINGS frame was received.

HTTP_MALFORMED_PUSH (0x12):

A push stream header was malformed or included an invalid Push ID.

HTTP_MALFORMED_MAX_PUSH_ID (0x13):

A MAX_PUSH_ID frame has been received with an invalid format.

HTTP_UNEXPECTED_GOAWAY (0x14):

A GOAWAY frame has been received by a server.

HTTP_MALFORMED_GOAWAY (0x15):

A GOAWAY frame was malformed or contained an invalid Stream ID.

HTTP/QUIC permits use of a larger number of streams (2^62-1) then HTTP/2. The considerations about exhaustion of stream identifier space apply, though the space is significantly larger such that it is likely that other limits in QUIC are reached first, such as the limit on the connection flow control window.¶

Many framing concepts from HTTP/2 can be elided away on QUIC, because the transport deals with them. Because frames are already on a stream, they can omit the stream number. Because frames do not block multiplexing (QUIC’s multiplexing occurs below this layer), the support for variable-maximum-length packets can be removed. Because stream termination is handled by QUIC, an END_STREAM flag is not required.¶

Frame payloads are largely drawn from [RFC7540]. However, QUIC includes many features (e.g. flow control) which are also present in HTTP/2. In these cases, the HTTP mapping does not re-implement them. As a result, several HTTP/2 frame types are not required in HTTP/QUIC. Where an HTTP/2-defined frame is no longer used, the frame ID has been reserved in order to maximize portability between HTTP/2 and HTTP/QUIC implementations. However, even equivalent frames between the two mappings are not identical.¶

Many of the differences arise from the fact that HTTP/2 provides an absolute ordering between frames across all streams, while QUIC provides this guarantee on each stream only. As a result, if a frame type makes assumptions that frames from different streams will still be received in the order sent, HTTP/QUIC will break them.¶

For example, implicit in the HTTP/2 prioritization scheme is the notion of in-order delivery of priority changes (i.e., dependency tree mutations): since operations on the dependency tree such as reparenting a subtree are not commutative, both sender and receiver must apply them in the same order to ensure that both sides have a consistent view of the stream dependency tree. HTTP/2 specifies priority assignments in PRIORITY frames and (optionally) in HEADERS frames. To achieve in-order delivery of priority changes in HTTP/QUIC, PRIORITY frames are sent on the control stream and the PRIORITY section is removed from the HEADERS frame.¶

Frame type definitions in HTTP/QUIC often use the QUIC variable-length integer encoding. In particular, Stream IDs use this encoding, which allow for a larger range of possible values than the encoding used in HTTP/2. Redefinition of the encoding of extension frame types might be necessary if the encoding includes a Stream ID.¶

Other than this issue, frame type HTTP/2 extensions are typically portable to QUIC simply by replacing Stream 0 in HTTP/2 with Stream 2 or 3 in HTTP/QUIC. HTTP/QUIC extensions will not assume ordering, but would not be harmed by ordering, and would be portable to HTTP/2 in the same manner.¶

DATA (0x0):

Padding is not defined in HTTP/QUIC frames. See Section 5.2.1.

HEADERS (0x1):

As described above, the PRIORITY region of HEADERS is not supported. A separate PRIORITY frame MUST be used. Padding is not defined in HTTP/QUIC frames. See Section 5.2.2.

PRIORITY (0x2):

As described above, the PRIORITY frame is sent on the control stream. See Section 5.2.3.

RST_STREAM (0x3):

RST_STREAM frames do not exist, since QUIC provides stream lifecycle management. The same code point is used for the CANCEL_PUSH frame (Section 5.2.4).

SETTINGS (0x4):

SETTINGS frames are sent only at the beginning of the connection. See Section 5.2.5 and Section 8.3.

PUSH_PROMISE (0x5):

The PUSH_PROMISE does not reference a stream; instead the push stream references the PUSH_PROMISE frame using a Push ID. See Section 5.2.6.

PING (0x6):

PING frames do not exist, since QUIC provides equivalent functionality.

GOAWAY (0x7):

GOAWAY is sent only from server to client and does not contain an error code. See Section 5.2.7.

WINDOW_UPDATE (0x8):

WINDOW_UPDATE frames do not exist, since QUIC provides flow control.

CONTINUATION (0x9):

CONTINUATION frames do not exist; instead, larger HEADERS/PUSH_PROMISE frames than HTTP/2 are permitted, and HEADERS frames can be used in series.

Frame types defined by extensions to HTTP/2 need to be separately registered for HTTP/QUIC if still applicable. The IDs of frames defined in [RFC7540] have been reserved for simplicity. See Section 10.3.¶

An important difference from HTTP/2 is that settings are sent once, at the beginning of the connection, and thereafter cannot change. This eliminates many corner cases around synchronization of changes.¶

Some transport-level options that HTTP/2 specifies via the SETTINGS frame are superseded by QUIC transport parameters in HTTP/QUIC. The HTTP-level options that are retained in HTTP/QUIC have the same value as in HTTP/2.¶

SETTINGS_HEADER_TABLE_SIZE:

See Section 5.2.5.2.

SETTINGS_ENABLE_PUSH:

This is removed in favor of the MAX_PUSH_ID which provides a more granular control over server push.

SETTINGS_MAX_CONCURRENT_STREAMS:

QUIC controls the largest open Stream ID as part of its flow control logic. Specifying SETTINGS_MAX_CONCURRENT_STREAMS in the SETTINGS frame is an error.

SETTINGS_INITIAL_WINDOW_SIZE:

QUIC requires both stream and connection flow control window sizes to be specified in the initial transport handshake. Specifying SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS frame is an error.

SETTINGS_MAX_FRAME_SIZE:

This setting has no equivalent in HTTP/QUIC. Specifying it in the SETTINGS frame is an error.

SETTINGS_MAX_HEADER_LIST_SIZE:

See Section 5.2.5.2.

Settings need to be defined separately for HTTP/2 and HTTP/QUIC. The IDs of settings defined in [RFC7540] have been reserved for simplicity. See Section 10.4.¶

QUIC has the same concepts of “stream” and “connection” errors that HTTP/2 provides. However, because the error code space is shared between multiple components, there is no direct portability of HTTP/2 error codes.¶

NO_ERROR (0x0):

HTTP_NO_ERROR in Section 7.1.

PROTOCOL_ERROR (0x1):

No single mapping. See new HTTP_MALFORMED_* error codes defined in Section 7.1.

INTERNAL_ERROR (0x2):

HTTP_INTERNAL_ERROR in Section 7.1.

FLOW_CONTROL_ERROR (0x3):

Not applicable, since QUIC handles flow control. Would provoke a QUIC_FLOW_CONTROL_RECEIVED_TOO_MUCH_DATA from the QUIC layer.

SETTINGS_TIMEOUT (0x4):

Not applicable, since no acknowledgement of SETTINGS is defined.

STREAM_CLOSED (0x5):

Not applicable, since QUIC handles stream management. Would provoke a QUIC_STREAM_DATA_AFTER_TERMINATION from the QUIC layer.

FRAME_SIZE_ERROR (0x6)

No single mapping. See new error codes defined in Section 7.1.

REFUSED_STREAM (0x7):

Not applicable, since QUIC handles stream management. Would provoke a QUIC_TOO_MANY_OPEN_STREAMS from the QUIC layer.

CANCEL (0x8):

HTTP_REQUEST_CANCELLED in Section 7.1.

COMPRESSION_ERROR (0x9):

HTTP_HPACK_DECOMPRESSION_FAILED in Section 7.1.

CONNECT_ERROR (0xa):

HTTP_CONNECT_ERROR in Section 7.1.

ENHANCE_YOUR_CALM (0xb):

HTTP_EXCESSIVE_LOAD in Section 7.1.

INADEQUATE_SECURITY (0xc):

Not applicable, since QUIC is assumed to provide sufficient security on all connections.

HTTP_1_1_REQUIRED (0xd):

HTTP_VERSION_FALLBACK in Section 7.1.

Error codes need to be defined for HTTP/2 and HTTP/QUIC separately. See Section 10.5.¶

This document creates a new registration for the identification of HTTP/QUIC in the “Application Layer Protocol Negotiation (ALPN) Protocol IDs” registry established in [RFC7301].¶

Protocol:

HTTP over QUIC

Identification Sequence:

0x68 0x71 (“hq”)

Specification:

This document

This document creates a new registration for version-negotiation hints in the “Hypertext Transfer Protocol (HTTP) Alt-Svc Parameter” registry established in [RFC7838].¶

Parameter:

“quic”

Specification:

This document, Section 2.1

This document establishes a registry for HTTP/QUIC frame type codes. The “HTTP/QUIC Frame Type” registry manages an 8-bit space. The “HTTP/QUIC Frame Type” registry operates under either of the “IETF Review” or “IESG Approval” policies [RFC8126] for values between 0x00 and 0xef, with values between 0xf0 and 0xff being reserved for Experimental Use.¶

While this registry is separate from the “HTTP/2 Frame Type” registry defined in [RFC7540], it is preferable that the assignments parallel each other. If an entry is present in only one registry, every effort SHOULD be made to avoid assigning the corresponding value to an unrelated operation.¶

Frame Type:

A name or label for the frame type.

Code:

The 8-bit code assigned to the frame type.

Specification:

A reference to a specification that includes a description of the frame layout, its semantics, and flags that the frame type uses, including any parts of the frame that are conditionally present based on the value of flags.

The entries in the following table are registered by this document.¶

This document establishes a registry for HTTP/QUIC settings. The “HTTP/QUIC Settings” registry manages a 16-bit space. The “HTTP/QUIC Settings” registry operates under the “Expert Review” policy [RFC8126] for values in the range from 0x0000 to 0xefff, with values between and 0xf000 and 0xffff being reserved for Experimental Use. The designated experts are the same as those for the “HTTP/2 Settings” registry defined in [RFC7540].¶

While this registry is separate from the “HTTP/2 Settings” registry defined in [RFC7540], it is preferable that the assignments parallel each other. If an entry is present in only one registry, every effort SHOULD be made to avoid assigning the corresponding value to an unrelated operation.¶

Name:

A symbolic name for the setting. Specifying a setting name is optional.

Code:

The 16-bit code assigned to the setting.

Specification:

An optional reference to a specification that describes the use of the setting.

The entries in the following table are registered by this document.¶

This document establishes a registry for HTTP/QUIC error codes. The “HTTP/QUIC Error Code” registry manages a 16-bit space. The “HTTP/QUIC Error Code” registry operates under the “Expert Review” policy [RFC8126].¶

Registrations for error codes are required to include a description of the error code. An expert reviewer is advised to examine new registrations for possible duplication with existing error codes. Use of existing registrations is to be encouraged, but not mandated.¶

Name:

A name for the error code. Specifying an error code name is optional.

Code:

The 16-bit error code value.

Description:

A brief description of the error code semantics, longer if no detailed specification is provided.

Specification:

An optional reference for a specification that defines the error code.

The entries in the following table are registered by this document.¶

• Changes for integer encodings in QUIC (#595,#905)

• Track changes in QUIC error code usage (#485)

• Made push ID sequential, add MAX_PUSH_ID, remove SETTINGS_ENABLE_PUSH (#709)
• Guidance about keep-alive and QUIC PINGs (#729)
• Expanded text on GOAWAY and cancellation (#757)

• Cite RFC 5234 (#404)
• Return to a single stream per request (#245,#557)
• Use separate frame type and settings registries from HTTP/2 (#81)
• SETTINGS_ENABLE_PUSH instead of SETTINGS_DISABLE_PUSH (#477)
• Restored GOAWAY (#696)
• Identify server push using Push ID rather than a stream ID (#702,#281)
• DATA frames cannot be empty (#700)

None.¶

• Track changes in transport draft

• SETTINGS changes (#181):
  • SETTINGS can be sent only once at the start of a connection; no changes thereafter
  • SETTINGS_ACK removed
  • Settings can only occur in the SETTINGS frame a single time
  • Boolean format updated
• Alt-Svc parameter changed from “v” to “quic”; format updated (#229)
• Closing the connection control stream or any message control stream is a fatal error (#176)
• HPACK Sequence counter can wrap (#173)
• 0-RTT guidance added
• Guide to differences from HTTP/2 and porting HTTP/2 extensions added (#127,#242)

• Changed “HTTP/2-over-QUIC” to “HTTP/QUIC” throughout (#11,#29)
• Changed from using HTTP/2 framing within Stream 3 to new framing format and two-stream-per-request model (#71,#72,#73)
• Adopted SETTINGS format from draft-bishop-httpbis-extended-settings-01
• Reworked SETTINGS_ACK to account for indeterminate inter-stream order (#75)
• Described CONNECT pseudo-method (#95)
• Updated ALPN token and Alt-Svc guidance (#13,#87)
• Application-layer-defined error codes (#19,#74)

• Adopted as base for draft-ietf-quic-http
• Updated authors/editors list