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.

Table of Contents

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. The header is an advisory indication that simplifies processing for intermediaries. Whether capsules are used on a tunnel is determined by the definition of the protocol or upgrade token in use, not by a mutual header exchange.

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. The value follows Structured Fields boolean syntax, where ?1 represents true. A false value ?0 is also defined and carries the same meaning as omitting the header.

Example

A client establishing a UDP proxying tunnel through extended CONNECT with the connect-udp protocol includes the header to indicate the Capsule Protocol is in use. The server echoes the header in the response. WebTransport endpoints define capsule use through the protocol itself and ignore this header.

Capsule-Protocol: ?1

The boolean with a silent failure mode

The value is a structured-field item, ?1, and the type rule carries a trap: a duplicated Capsule-Protocol header parses as a list rather than an item, and the recipient treats the field as absent. Sending the header twice disables the mechanism silently instead of erroring, so proxied paths adding headers deserve a check.

A stream under the capsule protocol stops being ordinary HTTP. The request and response carry no content, and Content-Length, Content-Type, and Transfer-Encoding are forbidden outright, and 204, 205, and 206 are prohibited as responses, with violations treated as malformed messages. The capsule sequence itself is length-prefixed values where unknown types are skipped, letting the protocol extend without breaking intermediaries.

Datagram capsules explain a subtlety about reliability: an intermediary is permitted to re-encode between capsules on a stream and QUIC datagram frames, so a datagram delivered reliably on one leg travels unreliably on the next where re-encoding happens, and end-to-end delivery guarantees follow the weakest hop.

MASQUE is where the header lives in production. UDP and IP proxying both run over the capsule protocol through upgrade tokens and extended CONNECT, and Cloudflare's WARP clients ship MASQUE as the default tunnel, carrying exactly this header in the documented handshake. Apple's Private Relay runs on MASQUE over HTTP/3 as well, with the capsule-level detail undocumented.

See also

Last updated: August 17, 2026