WebTransport over HTTP/2

1.1. Terminology

The keywords "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.¶

This document follows terminology defined in Section 1.2 of [OVERVIEW]. Note that this document distinguishes between a WebTransport server and an HTTP/2 server. An HTTP/2 server is the server that terminates HTTP/2 connections; a WebTransport server is an application that accepts WebTransport sessions, which can be accessed using HTTP/2 and this protocol.¶

3.1. Establishing a Transport-Capable HTTP/2 Connection

In order to indicate support for WebTransport, both the client and the server MUST send a SETTINGS_WEBTRANSPORT_MAX_SESSIONS value greater than "0" in their SETTINGS frame. Endpoints MUST NOT use any WebTransport-related functionality unless the parameter has been negotiated.¶

3.2. Extended CONNECT in HTTP/2

[RFC8441] defines an extended CONNECT method in Section 4, enabled by the SETTINGS_ENABLE_CONNECT_PROTOCOL parameter. An endpoint needs to send both SETTINGS_ENABLE_CONNECT_PROTOCOL and SETTINGS_WEBTRANSPORT_MAX_SESSIONS for WebTransport to be enabled.¶

3.3. Creating a New Session

As WebTransport sessions are established over HTTP, they are identified using the https URI scheme [RFC7230].¶

In order to create a new WebTransport session, a client can send an HTTP CONNECT request. The :protocol pseudo-header field ([RFC8441]) MUST be set to webtransport (Section 7.1 of [WEBTRANSPORT-H3]). The :scheme field MUST be https. Both the :authority and the :path value MUST be set; those fields indicate the desired WebTransport server. In a Web context, the request MUST include an Origin header field [ORIGIN] that includes the origin of the site that requested the creation of the session.¶

Upon receiving an extended CONNECT request with a :protocol field set to webtransport, the HTTP server checks if the identified resource supports WebTransport sessions. If the resource does not, the server SHOULD reply with status code 406 (Section 15.5.7 of [RFC9110]). If it does, it MAY accept the session by replying with a 2xx series status code, as defined in Section 15.3 of [SEMANTICS]. The WebTransport server MUST verify the Origin header to ensure that the specified origin is allowed to access the server in question.¶

A WebTransport session is established when the server sends a 2xx response. A server generates that response from the request header, not from the contents of the request. To enable clients to resend data when attempting to re-establish a session that was rejected by a server, a server MUST NOT process any capsules on the request stream unless it accepts the WebTransport session.¶

A client MAY optimistically send any WebTransport capsules associated with a CONNECT request, without waiting for a response, to the extent allowed by flow control. This can reduce latency for data sent by a client at the start of a WebTransport session. For example, a client might choose to send datagrams or flow control updates before receiving any response from the server.¶

3.4. Flow Control

Flow control governs the amount of resources that can be consumed or data that can be sent. WebTransport over HTTP/2 allows a server to limit the number of sessions that a client can create on a single connection; see Section 3.4.1.¶

For data, there are five applicable levels of flow control for data that is sent or received using WebTransport over HTTP/2:¶

1. TCP flow control.¶
2. HTTP/2 connection flow control, which governs the total amount of data in DATA frames for all HTTP/2 streams.¶
3. HTTP/2 stream flow control, which limits the data on a single HTTP/2 stream. For a WebTransport session, this includes all capsules, including those that are exempt from WebTransport session-level flow control.¶
4. WebTransport session-level flow control, which limits the total amount of stream data that can be sent or received on streams within the WebTransport session. Note that this does not limit other types of capsules within a WebTransport session, such as control messages or datagrams.¶
5. WebTransport stream flow control, which limits data on individual streams within a session.¶

TCP and HTTP/2 define the first three levels of flow control. This document defines the final two.¶

4.1. Transport Properties

The WebTransport framework [OVERVIEW] defines a set of optional transport properties that clients can use to determine the presence of features which might allow additional optimizations beyond the common set of properties available via all WebTransport protocols.¶

Because WebTransport over TCP-based HTTP semantics relies on the underlying protocols to provide in order and reliable delivery, there are some notable differences from the way in which QUIC handles application data. For example, endpoints send stream data in order. As there is no ordering mechanism available for the receiver to reassemble incoming data, receivers assume that all data arriving in WT_STREAM capsules is contiguous and in order.¶

Below are details about support in WebTransport over HTTP/2 for the properties defined by the WebTransport framework.¶

Stream Independence:

WebTransport over HTTP/2 does not support stream independence, as HTTP/2 inherently has head-of-line blocking.¶

Partial Reliability:

WebTransport over HTTP/2 does not support partial reliability, as HTTP/2 retransmits any lost data. This means that any datagrams sent via WebTransport over HTTP/2 will be retransmitted regardless of the preference of the application. The receiver is permitted to drop them, however, if it is unable to buffer them.¶

Pooling Support:

WebTransport over HTTP/2 supports pooling, as multiple transports using WebTransport over HTTP/2 may share the same underlying HTTP/2 connection and therefore share a congestion controller and other transport context. Note that WebTransport streams over HTTP/2 are contained within a single HTTP/2 stream and do not compete with other pooled WebTransport sessions for per-stream resources.¶

Connection Mobility:

WebTransport over HTTP/2 does not support connection mobility, unless an underlying transport protocol that supports multipath or migration, such as MPTCP [MPTCP], is used underneath HTTP/2 and TLS. Without such support, WebTransport over HTTP/2 connections cannot survive network transitions.¶

4.2. WebTransport Streams

WebTransport streams have identifiers and states that mirror the identifiers ((Section 2.1 of [RFC9000])) and states (Section 3 of [RFC9000]) of QUIC streams as closely as possible to aid in ease of implementation.¶

WebTransport streams are identified by a numeric value, or stream ID. Stream IDs are only meaningful within the WebTransport session in which they were created. They share the same semantics as QUIC stream IDs, with client initiated streams having even-numbered stream IDs and server-initiated streams having odd-numbered stream IDs. Similarly, they can be bidirectional or unidirectional, indicated by the second least significant bit of the stream ID.¶

Because WebTransport does not provide an acknowledgement mechanism for WebTransport capsules, it relies on the underlying transport's in order delivery to inform stream state transitions. Wherever QUIC relies on receiving an ack for a packet to transition between stream states, WebTransport performs that transition immediately.¶

5.1. PADDING Capsule

A PADDING capsule is an HTTP capsule [HTTP-DATAGRAM] of type=0x190B4D38 and has no semantic value. PADDING capsules can be used to introduce additional data between other HTTP datagrams and can also be used to provide protection against traffic analysis or for other reasons.¶

Note that, when used with WebTransport over HTTP/2, the PADDING capsule exists alongside the ability to pad HTTP/2 frames (Section 10.7 of [RFC9113]). HTTP/2 padding is hop-by-hop and can be modified by intermediaries, while the PADDING capsule traverses intermedaries. The PADDING capsule is also constrained to be no smaller than the capsule overhead itself.¶

PADDING Capsule {
  Type (i) = 0x190B4D38,
  Length (i),
  Padding (..),
}

The Padding field MUST be set to an all-zero sequence of bytes of any length as specified by the Length field.¶

5.2. WT_RESET_STREAM Capsule

A WT_RESET_STREAM capsule is an HTTP capsule [HTTP-DATAGRAM] of type=0x190B4D39 and allows either endpoint to abruptly terminate the sending part of a WebTransport stream.¶

After sending a WT_RESET_STREAM capsule, an endpoint ceases transmission of WT_STREAM capsules on the identified stream. A receiver of a WT_RESET_STREAM capsule can discard any data that it already received on that stream.¶

WT_RESET_STREAM Capsule {
  Type (i) = 0x190B4D39,
  Length (i),
  Stream ID (i),
  Application Protocol Error Code (i),
}

The WT_RESET_STREAM capsule defines the following fields:¶

Stream ID:

A variable-length integer encoding of the WebTransport stream ID of the stream being terminated.¶

Application Protocol Error Code:

A variable-length integer containing the application protocol error code that indicates why the stream is being closed.¶

Unlike the equivalent QUIC frame, this capsule does not include a Final Size field. In-order delivery of WT_STREAM capsules ensures that the amount of session-level flow control consumed by a stream is always known by both endpoints.¶

5.3. WT_STOP_SENDING Capsule

An HTTP capsule [HTTP-DATAGRAM] called WT_STOP_SENDING (type=0x190B4D3A) is introduced to communicate that incoming data is being discarded on receipt per application request. WT_STOP_SENDING requests that a peer cease transmission on a WebTransport stream.¶

WT_STOP_SENDING Capsule {
  Type (i) = 0x190B4D3A,
  Length (i),
  Stream ID (i),
  Application Protocol Error Code (i),
}

The WT_STOP_SENDING capsule defines the following fields:¶

Stream ID:

A variable-length integer carrying the WebTransport stream ID of the stream being ignored.¶

Application Protocol Error Code:

A variable-length integer containing the application-specified reason the sender is ignoring the stream.¶

5.4. WT_STREAM Capsule

WT_STREAM capsules implicitly create a WebTransport stream and carry stream data.¶

The Type field in the WT_STREAM capsule is either 0x190B4D3B or 0x190B4D3C. The least significant bit in the capsule type is the FIN bit (0x01), indicating when set that the capsule marks the end of the stream in one direction. Stream data consists of any number of 0x190B4D3B capsules followed by a terminal 0x190B4D3C capsule.¶

WT_STREAM Capsule {
  Type (i) = 0x190B4D3B..0x190B4D3C,
  Length (i),
  Stream ID (i),
  Stream Data (..),
}

WT_STREAM capsules contain the following fields:¶

Stream ID:

The stream ID for the stream.¶

Stream Data:

Zero or more bytes of data for the stream. Empty WT_STREAM capsules MUST NOT be used unless they open or close a stream; an endpoint MAY treat an empty WT_STREAM capsule that neither starts nor ends a stream as a session error.¶

5.5. WT_MAX_DATA Capsule

An HTTP capsule [HTTP-DATAGRAM] called WT_MAX_DATA (type=0x190B4D3D) is introduced to inform the peer of the maximum amount of data that can be sent on the WebTransport session as a whole.¶

WT_MAX_DATA Capsule {
  Type (i) = 0x190B4D3D,
  Length (i),
  Maximum Data (i),
}

WT_MAX_DATA capsules contain the following field:¶

Maximum Data:

A variable-length integer indicating the maximum amount of data that can be sent on the entire connection, in units of bytes.¶

All data sent in WT_STREAM capsules counts toward this limit. The sum of the lengths of Stream Data fields in WT_STREAM capsules MUST NOT exceed the value advertised by a receiver.¶

The WT_MAX_DATA capsule defines special intermediary handling, as described in Section 3.2 of [HTTP-DATAGRAM]. Intermedaries MUST consume WT_MAX_DATA capsules for flow control purposes and MUST generate and send appropriate flow control signals for their limits; see Section 3.4.3.¶

5.6. WT_MAX_STREAM_DATA Capsule

An HTTP capsule [HTTP-DATAGRAM] called WT_MAX_STREAM_DATA (type=0x190B4D3E) is introduced to inform a peer of the maximum amount of data that can be sent on a WebTransport stream.¶

WT_MAX_STREAM_DATA Capsule {
  Type (i) = 0x190B4D3E,
  Length (i),
  Stream ID (i),
  Maximum Stream Data (i),
}

WT_MAX_STREAM_DATA capsules contain the following fields:¶

Stream ID:

The stream ID of the affected WebTransport stream, encoded as a variable-length integer.¶

Maximum Stream Data:

A variable-length integer indicating the maximum amount of data that can be sent on the identified stream, in units of bytes.¶

All data sent in WT_STREAM capsules for the identified stream counts toward this limit. The sum of the lengths of Stream Data fields in WT_STREAM capsules on the identified stream MUST NOT exceed the value advertised by a receiver.¶

The WT_MAX_STREAM_DATA capsule defines special intermediary handling, as described in Section 3.2 of [HTTP-DATAGRAM]. Intermedaries MUST consume WT_MAX_STREAM_DATA capsules for flow control purposes and MUST generate and send appropriate flow control signals for their limits; see Section 3.4.3.¶

5.7. WT_MAX_STREAMS Capsule

An HTTP capsule [HTTP-DATAGRAM] called WT_MAX_STREAMS is introduced to inform the peer of the cumulative number of streams of a given type it is permitted to open. A WT_MAX_STREAMS capsule with a type of 0x190B4D3F applies to bidirectional streams, and a WT_MAX_STREAMS capsule with a type of 0x190B4D40 applies to unidirectional streams.¶

WT_MAX_STREAMS Capsule {
  Type (i) = 0x190B4D3F..0x190B4D40,
  Length (i),
  Maximum Streams (i),
}

WT_MAX_STREAMS capsules contain the following field:¶

Maximum Streams:

A count of the cumulative number of streams of the corresponding type that can be opened over the lifetime of the connection. This value cannot exceed 2⁶⁰, as it is not possible to encode stream IDs larger than 2⁶²-1.¶

An endpoint MUST NOT open more streams than permitted by the current stream limit set by its peer. For instance, a server that receives a unidirectional stream limit of 3 is permitted to open streams 3, 7, and 11, but not stream 15.¶

Note that this limit includes streams that have been closed as well as those that are open.¶

The WT_MAX_STREAMS capsule defines special intermediary handling, as described in Section 3.2 of [HTTP-DATAGRAM]. Intermedaries MUST consume WT_MAX_STREAMS capsules for flow control purposes and MUST generate and send appropriate flow control signals for their limits.¶

5.8. WT_DATA_BLOCKED Capsule

A sender SHOULD send a WT_DATA_BLOCKED capsule (type=0x190B4D41) when it wishes to send data but is unable to do so due to WebTransport session-level flow control. WT_DATA_BLOCKED capsules can be used as input to tuning of flow control algorithms.¶

WT_DATA_BLOCKED Capsule {
  Type (i) = 0x190B4D41,
  Length (i),
  Maximum Data (i),
}

WT_DATA_BLOCKED capsules contain the following field:¶

Maximum Data:

A variable-length integer indicating the session-level limit at which blocking occurred.¶

The WT_DATA_BLOCKED capsule defines special intermediary handling, as described in Section 3.2 of [HTTP-DATAGRAM]. Intermedaries MUST consume WT_DATA_BLOCKED capsules for flow control purposes and MUST generate and send appropriate flow control signals for their limits; see Section 3.4.3.¶

5.9. WT_STREAM_DATA_BLOCKED Capsule

A sender SHOULD send a WT_STREAM_DATA_BLOCKED capsule (type=0x190B4D42) when it wishes to send data but is unable to do so due to stream-level flow control. This capsule is analogous to WT_DATA_BLOCKED.¶

WT_STREAM_DATA_BLOCKED Capsule {
  Type (i) = 0x190B4D42,
  Length (i),
  Stream ID (i),
  Maximum Stream Data (i),
}

WT_STREAM_DATA_BLOCKED capsules contain the following fields:¶

Stream ID:

A variable-length integer indicating the WebTransport stream that is blocked due to flow control.¶

Maximum Stream Data:

A variable-length integer indicating the offset of the stream at which the blocking occurred.¶

The WT_STREAM_DATA_BLOCKED capsule defines special intermediary handling, as described in Section 3.2 of [HTTP-DATAGRAM]. Intermedaries MUST consume WT_STREAM_DATA_BLOCKED capsules for flow control purposes and MUST generate and send appropriate flow control signals for their limits; see Section 3.4.3.¶

5.10. WT_STREAMS_BLOCKED Capsule

A sender SHOULD send a WT_STREAMS_BLOCKED capsule (type=0x190B4D43 or 0x190B4D44) when it wishes to open a stream but is unable to do so due to the maximum stream limit set by its peer. A WT_STREAMS_BLOCKED capsule of type 0x190B4D43 is used to indicate reaching the bidirectional stream limit, and a STREAMS_BLOCKED capsule of type 0x190B4D44 is used to indicate reaching the unidirectional stream limit.¶

A WT_STREAMS_BLOCKED capsule does not open the stream, but informs the peer that a new stream was needed and the stream limit prevented the creation of the stream.¶

WT_STREAMS_BLOCKED Capsule {
  Type (i) = 0x190B4D43..0x190B4D44,
  Length (i),
  Maximum Streams (i),
}

WT_STREAMS_BLOCKED capsules contain the following field:¶

Maximum Streams:

A variable-length integer indicating the maximum number of streams allowed at the time the capsule was sent. This value cannot exceed 2⁶⁰, as it is not possible to encode stream IDs larger than 2⁶²-1.¶

The WT_STREAMS_BLOCKED capsule defines special intermediary handling, as described in Section 3.2 of [HTTP-DATAGRAM]. Intermedaries MUST consume WT_STREAMS_BLOCKED capsules for flow control purposes and MUST generate and send appropriate flow control signals for their limits.¶

5.11. DATAGRAM Capsule

WebTransport over HTTP/2 uses the DATAGRAM capsule defined in Section 3.5 of [HTTP-DATAGRAM] to carry datagram traffic.¶

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

When used in WebTransport over HTTP/2, DATAGRAM capsules contain the following fields:¶

HTTP Datagram Payload:

The content of the datagram to be delivered.¶

The data in DATAGRAM capsules is not subject to flow control. The receiver MAY discard this data if it does not have sufficient space to buffer it.¶

An intermediary could forward the data in a DATAGRAM capsule over another protocol, such as WebTransport over HTTP/3. In QUIC, a datagram frame can span at most one packet. Because of that, the applications have to know the maximum size of the datagram they can send. However, when proxying the datagrams, the hop-by-hop MTUs can vary.¶

Section 3.5 of [HTTP-DATAGRAM] indicates that intermediaries that forward DATAGRAM capsules where QUIC datagrams [DATAGRAM] are available forward the contents of the capsule as native QUIC datagrams, rather than as HTTP datagrams in a DATAGRAM capsule. Similarly, when forwarding DATAGRAM capsules used as part of a WebTransport over HTTP/2 session on a WebTransport session that natively supports QUIC datagrams, such as WebTransport over HTTP/3 [WEBTRANSPORT-H3], intermediaries follow the requirements in [WEBTRANSPORT-H3] to use native QUIC datagrams.¶

10.1. HTTP/2 SETTINGS Parameter Registration

The following entry is added to the "HTTP/2 Settings" registry established by [RFC7540]:¶

The SETTINGS_WEBTRANSPORT_MAX_SESSIONS parameter indicates that the specified HTTP/2 connection is WebTransport-capable and the number of concurrent sessions an endpoint is willing to receive. The default value for the SETTINGS_MAX_WEBTRANSPORT_SESSIONS parameter is "0", meaning that the endpoint is not willing to receive any WebTransport sessions.¶

Setting Name:

WEBTRANSPORT_MAX_SESSIONS¶

Value:

0x2b603743¶

Default:

0¶

Specification:

This document¶

10.2. Capsule Types

The following entries are added to the "HTTP Capsule Types" registry established by [HTTP-DATAGRAM]:¶

The PADDING capsule.¶

Value:

0x190B4D38¶

Capsule Type:

PADDING¶

Status:

permanent¶

Specification:

This document¶

Change Controller:

IETF¶

Contact:

WebTransport Working Group webtransport@ietf.org¶

Notes:

None¶

The WT_RESET_STREAM capsule.¶

Value:

0x190B4D39¶

Capsule Type:

WT_RESET_STREAM¶

Status:

permanent¶

Specification:

This document¶

Change Controller:

IETF¶

Contact:

WebTransport Working Group webtransport@ietf.org¶

Notes:

None¶

The WT_STOP_SENDING capsule.¶

Value:

0x190B4D3A¶

Capsule Type:

WT_STOP_SENDING¶

Status:

permanent¶

Specification:

This document¶

Change Controller:

IETF¶

Contact:

WebTransport Working Group webtransport@ietf.org¶

Notes:

None¶

The WT_STREAM capsule.¶

Value:

0x190B4D3B..0x190B4D3C¶

Capsule Type:

WT_STREAM¶

Status:

permanent¶

Specification:

This document¶

Change Controller:

IETF¶

Contact:

WebTransport Working Group webtransport@ietf.org¶

Notes:

None¶

The WT_MAX_DATA capsule.¶

Value:

0x190B4D3D¶

Capsule Type:

WT_MAX_DATA¶

Status:

permanent¶

Specification:

This document¶

Change Controller:

IETF¶

Contact:

WebTransport Working Group webtransport@ietf.org¶

Notes:

None¶

The WT_MAX_STREAM_DATA capsule.¶

Value:

0x190B4D3E¶

Capsule Type:

WT_MAX_STREAM_DATA¶

Status:

permanent¶

Specification:

This document¶

Change Controller:

IETF¶

Contact:

WebTransport Working Group webtransport@ietf.org¶

Notes:

None¶

The WT_MAX_STREAMS capsule.¶

Value:

0x190B4D3F..0x190B4D40¶

Capsule Type:

WT_MAX_STREAMS¶

Status:

permanent¶

Specification:

This document¶

Change Controller:

IETF¶

Contact:

WebTransport Working Group webtransport@ietf.org¶

Notes:

None¶

The WT_DATA_BLOCKED capsule.¶

Value:

0x190B4D41¶

Capsule Type:

WT_DATA_BLOCKED¶

Status:

permanent¶

Specification:

This document¶

Change Controller:

IETF¶

Contact:

WebTransport Working Group webtransport@ietf.org¶

Notes:

None¶

The WT_STREAM_DATA_BLOCKED capsule.¶

Value:

0x190B4D42¶

Capsule Type:

WT_STREAM_DATA_BLOCKED¶

Status:

permanent¶

Specification:

This document¶

Change Controller:

IETF¶

Contact:

WebTransport Working Group webtransport@ietf.org¶

Notes:

None¶

The WT_STREAMS_BLOCKED capsule.¶

Value:

0x190B4D43..0x190B4D44¶

Capsule Type:

WT_STREAMS_BLOCKED¶

Status:

permanent¶

Specification:

This document¶

Change Controller:

IETF¶

Contact:

WebTransport Working Group webtransport@ietf.org¶

Notes:

None¶

10.3. HTTP Header Field Name

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

Field Name:

WebTransport-Init¶

Template:

None¶

Status:

permanent¶

Reference:

This document¶

Comments:

None¶