Capsule-Protocol
The HTTP Capsule-Protocol request or response header indicates the HTTP Datagram and Capsule Protocol is in use on a CONNECT or extended CONNECT tunnel.
Usage
When establishing a CONNECT or extended CONNECT tunnel for protocols like CONNECT-UDP, CONNECT-IP, or WebTransport, endpoints use the Capsule-Protocol header to signal support for HTTP Datagrams and the Capsule Protocol. This enables multiplexed, potentially unreliable datagram transmission inside an HTTP/2 or HTTP/3 connection.
The header carries a boolean value ?1 using the
Structured Fields syntax. Both
endpoints include the header in their
handshake to confirm bidirectional support. Without agreement from
both sides, the Capsule Protocol remains inactive.
The Capsule Protocol provides a general convention for conveying datagrams in HTTP connections. When QUIC DATAGRAM frames are unavailable or unsuitable, the Capsule Protocol offers an alternative transport method for datagrams over HTTP. This approach complements the Protocol-Upgrade mechanism by extending HTTP's capability to carry non-HTTP protocols over persistent connections.
Values
?1
The boolean value ?1 indicates support for the HTTP Datagram and
Capsule Protocol. This is the only defined value for the header.
The value follows Structured Fields boolean syntax, where ?1
represents true.
Example
A client requesting a WebTransport session includes the header to indicate support for HTTP Datagrams. The server includes the same header in the response to confirm the protocol is active.
Capsule-Protocol: ?1
Takeaway
The Capsule-Protocol header establishes bidirectional agreement between client and server to use HTTP Datagrams and the Capsule Protocol on a CONNECT tunnel, enabling datagram transmission over HTTP connections.