]> Meta Platforms, Inc.

ietf@bemasc.net

Fastly

kazuhooku@gmail.com

This draft specifies how HTTP intermediaries can translate the Capsule Protocol between HTTP versions. About This Document Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

Introduction The Capsule Protocol defines a framing layer that can be used for protocols running over HTTP. The Capsule Protocol consists of a linear stream of capsules, each with a specified type and size. Endpoints can establish a Capsule Protocol connection using HTTP Extended CONNECT or the HTTP/1.1 Upgrade process. Intermediaries such as HTTP Gateways can play an active role in the Capsule Protocol. To inform intermediaries that this protocol is in use, endpoints can include a "Capsule-Protocol: ?1" header in their request or response. Intermediaries are obligated to pass unrecognized capsule types unmodified, but some capsule types do permit intermediaries to modify them. The Capsule Protocol is defined for HTTP/1.1, HTTP/2, and HTTP/3, and intermediaries can translate Capsule Protocol streams between different versions of HTTP. For example, an HTTP Gateway receiving a request using the "connect-tcp-capsule" Upgrade Token over HTTP/3 might forward it to a backend server using HTTP/1.1 for further processing. However, this translation currently requires the intermediary to recognize the specified Upgrade Token. Unrecognized Upgrade Tokens cannot be translated between HTTP versions.

HTTP version translation of an Upgrade Token. The gateway can only perform this translation if it recognizes the "foo" Upgrade Token. HTTP/2--->| Gateway +--> HTTP/1.1--->| Server | '------' :protocol=foo '-------' Upgrade: foo '------' capsule-protocol=?1 Capsule-Protocol: ?1 ]]>

As a result of this limitation, HTTP intermediaries cannot forward unrecognized Capsule Protocol Upgrade Tokens (CPUTs) unless the backend supports the HTTP version used by the client. In practice, such HTTP version mismatches are common, so intermediaries have preferred not to support unrecognized tokens at all. As a result, each new CPUT requires the cooperation of any HTTP intermediaries. This increases the maintenance burden on intermediaries and impedes the deployment of novel CPUTs. This draft specifies general rules for translating Capsule Protocol requests across HTTP versions, allowing intermediaries to perform such translations for unrecognized CPUTs.

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

Requirements This section describes requirements on HTTP intermediaries that change the HTTP version of a Capsule Protocol request.

Converting an HTTP/1.1 Upgrade request to Extended CONNECT A Convertible Upgrade Request is a request that meets these criteria:

• The HTTP version is "1.1".
• The method is "GET".
• An "Upgrade" header is present and specifies exactly one Upgrade Token.
• The request is known to use the Capsule Protocol, because:
  • A "Capsule-Protocol" header is present with an item value of "?1" (with or without parameters), OR
  • The intermediary knows that this Upgrade Token always uses the Capsule Protocol.
• The request is otherwise well-formed for use with the Capsule Protocol.

Upon receiving a Convertible Upgrade Request, an HTTP intermediary MAY convert it into an Extended CONNECT request () using ordinary HTTP version translation with the following modifications:

• Change the method to "CONNECT".
• Add a ":protocol" pseudo-header containing the specified Upgrade Token.
• Add a "capsule-protocol: ?1" header if no "Capsule-Protocol" header is present.

(Note that ordinary HTTP version translation removes the "Connection" and "Upgrade" headers.) If the intermediary receives a "200 (OK)" response, it MUST convert it to an HTTP/1.1 Upgrade response as follows:

• Change the response code to "101 (Switching Protocols)".
• Add an "Upgrade" header containing the specified Upgrade Token.
• Add a "Connection: Upgrade" header.

After sending this response, the intermediary MUST process all data to and from the client in accordance with the Capsule Protocol. If the intermediary receives any other valid response, it MUST NOT convert it to an HTTP/1.1 Upgrade response, and MUST forward it using ordinary HTTP version translation. If the response status was not 1xx (Informational), the intermediary MAY accept additional HTTP/1.1 requests on this connection to the client.

Converting an Extended CONNECT request to HTTP/1.1 Upgrade A Convertible Extended CONNECT request is a request that meets these criteria:

• The method is "CONNECT".
• The ":protocol" pseudo-header is present, providing an Upgrade Token.
• The request is known to use the Capsule Protocol, because:
  • A "capsule-protocol" header is present with an item value of "?1" (with or without parameters), OR
  • The intermediary recognizes the provided Upgrade Token and knows that it always uses the Capsule Protocol.
• The request is otherwise well-formed for use with the Capsule Protocol.

Upon receiving a Convertible Extended CONNECT Request, an HTTP intermediary MAY convert it into an HTTP/1.1 Upgrade request according to ordinary HTTP version translation, with the following modifications:

• Change the method to "GET".
• Replace the ":protocol" pseudo-header with an "Upgrade" header containing the same Upgrade Token.
• Add a "Connection: Upgrade" header.
• Add a "Capsule-Protocol: ?1" header if no "capsule-protocol" header is present.

If the intermediary receives a correctly formed "101 (Switching Protocols)" response, it MUST change the response code to "200 (OK)". If it receives a 2xx (Successful) response, it SHOULD return a "501 (Not Implemented)" status code, to indicate that the ":protocol" value was not accepted (). Otherwise, it MUST forward any valid responses unmodified. After sending a "200" response, the intermediary MUST process all further data to and from the server in accordance with the Capsule Protocol.

Converting an Extended CONNECT request to Extended CONNECT for a different HTTP version An HTTP intermediary MAY translate a Convertible Extended CONNECT Request between different HTTP versions using ordinary HTTP version translation.

Implications Translation of unrecognized CPUTs across HTTP versions carries some implications for future specifications related to the Capsule Protocol:

• All CPUTs must treat "GET" in HTTP/1.1 as semantically equivalent to Extended CONNECT.
• The "Capsule-Protocol" response header has no effect and should be treated as a hint for later analysis. Intermediaries can process the response as the Capsule Protocol based entirely on the request headers and the response status code.
• Intermediaries' behavior regarding each capsule type is independent of the CPUT. CPUTs cannot change intermediaries' treatment of existing capsule types.
• A Capsule Type or CPUT cannot change the meaning of an HTTP extension. It can only rely on the behaviors that are defined as mandatory for any implementation of that extension. Extensions intended for use with the Capsule Protocol will likely need to define how HTTP version translation works.
• Capsule Protocol endpoints are defined independently of the HTTP version, like ordinary HTTP resources. If an origin server's Capsule Protocol support varies between HTTP versions, clients may observe inconsistent behavior when accessing the origin through a compliant intermediary.
• If a future CPUT specification intends for all clients to be compatible with HTTP version translation by pre-existing intermediaries under this specification, it will have to make the "Capsule-Protocol: ?1" request header mandatory, as permitted by .
• A "Capsule-Protocol: ?0" request header cannot be used to disable HTTP version translation.

All existing CPUTs and Capsule Types already conform to these rules.

Security Considerations When implemented incorrectly, HTTP/1.1 Upgrade carries a risk of request smuggling. (See .) Intermediary implementors should take care to avoid excessive resource consumption by malicious clients. For example, a client might be able to send many short requests over a single HTTP/2 or HTTP/3 connection, each of which requires opening a new, long-lived TCP connection to the backend.

IANA Considerations This document has no IANA actions.

References Normative References This document describes HTTP Datagrams, a convention for conveying multiplexed, potentially unreliable datagrams inside an HTTP connection. In HTTP/3, HTTP Datagrams can be sent unreliably using the QUIC DATAGRAM extension. When the QUIC DATAGRAM frame is unavailable or undesirable, HTTP Datagrams can be sent using the Capsule Protocol, which is a more general convention for conveying data in HTTP connections. HTTP Datagrams and the Capsule Protocol are intended for use by HTTP extensions, not applications. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. The mechanism for running the WebSocket Protocol over a single stream of an HTTP/2 connection is equally applicable to HTTP/3, but the HTTP-version-specific details need to be specified. This document describes how the mechanism is adapted for HTTP/3. This document defines a mechanism for running the WebSocket Protocol (RFC 6455) over a single stream of an HTTP/2 connection. Informative References Meta Platforms, Inc. TCP proxying using HTTP CONNECT has long been part of the core HTTP specification. However, this proxying functionality has several important deficiencies in modern HTTP environments. This specification defines an alternative HTTP proxy service configuration for TCP connections. This configuration is described by a URI Template, similar to the CONNECT-UDP and CONNECT-IP protocols. Meta Platforms, Inc. In HTTP/1.1, the client can request a change to a new protocol on the existing connection. This document discusses the security considerations that apply to data sent by the client before this request is confirmed, and updates RFC 9298 to avoid related security issues.

Acknowledgments TODO acknowledge.