]> Cloudflare

lucas@lucaspardue.com

next generation unicorn sparkling distributed ledger This document updates RFC 9297 with further guidance for extensibility of the HTTP Capsule Protocol. About This Document The latest revision of this draft can be found at . 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 is a sequence of type-length-value tuples that definitions of new HTTP upgrade tokens can choose to use. It allows endpoints to reliably communicate request-related information end-to-end on HTTP request streams, even in the presence of HTTP intermediaries. Clients can indicate in requests that they want the data stream to use the Capsule Protocol by providing an upgrade token and/or a Capsule-Protocol header field; see . Servers confirm Capsule Protocol usage by returning a response in the 2xx (Successful) range, possibly including a Capsule-Protocol header field. The process of initiating the Capsule Protocol for any given data stream identifies the purpose of usage and the Capsule types that endpoints can send or receive. This document updates RFC 9297 with further guidance for extensibility of the Capsule Protocol.

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.

The Extensibility of Capsule Type Usage In order to support extensibility, requires that:

• Endpoints that receive a Capsule with an unknown Capsule Type MUST silently drop that Capsule and skip over it to parse the next Capsule.

The first ambiguity in this text comes from the term "endpoint". It relates to the resource that the Capsule Protocol negotiation applies to, not the general HTTP endpoint. In other words, known or unknown types are scoped only to the request stream Capsule Protocol usage, nothing else. For example, proxying UDP in HTTP makes use of the upgrade token "connect-udp" to enable the Connect Protocol. It describes how DATAGRAM capsules () can be used. Use of other capsule types on that data stream is undefined, the expectation being that they are ignored on receipt. Similarly, proxying IP in HTTP makes use of the upgrade token "connect-ip" to enable the Connect Protocol. It defines ADDRESS_ASSIGN, ADDRESS_REQUEST, and ROUTE_ADVERTISEMENT capsules () and describes how these can be used together with DATAGRAM capsules. An HTTP server could support both UDP and IP proxying and it's implementation would be able to understand all four capsule types. However, use of ADDRESS_ASSIGN, for example, on a "connect-udp" data stream is undefined by . The document requires updated text to resolve this ambuguity. Should this document be adopted, consensus on the resolution can be established.

Negotiating Additional Capsule Type Usage The second ambiguity with the text in comes from ambiguity of intent. Silent dropping of unknown types new can be safely used by extensions without prior arrangement or negotiation. However, some extensions might be built on the assumption that a capsule is processed by the recipient. For example to send a capsule that elicits some response message or behavioural change. Such extensions can benefit from some form of explicit negotiation. There are several approaches to negotiating the use of new capsule types within the scope of a request stream Capsule Protocol. This document does not mandate any specific method but advises protocol designers to use negotiation patterns that fit the end-to-end nature of the Capsule Protocol, where endpoints generate and process capsules. Specifically SETTINGS negotiation ( and ) could be used to extend a connection, changing the scope of Capsule Protocol knowledge for all request streams or a set of upgrade tokens. However, the SETTINGS are not an end-to-end mechanism and therefore this method of negotiation does not work when intermediaries are involved. Negotiation of new capsule types via new upgrade tokens is an end-to-end mechanism. However, while HTTP/1.x clients can offer several token values in the Upgrade mechanism (), extended CONNECT ( and ) does not support this possibility. While HTTP/2 or HTTP/3 clients could use multiple separate requests in order to attempt the selection of a most-preferred upgrade token, this requires additional round trips which might introduce undesirable delays. Header fields provide an end-to-end negotiation mechanism. The Capsule-Protocol header field is itself extensible and parameters could, in theory, be used to negotiate extensions. However, Capsule-Protocol requires that unknown parameters are ignored, so extension designers ought to use an offer-echo pattern that confirms the recipient did process the parameter. Also note that use of Capsule-Protocol is optional and the upgrade tokens can mandate use of the Capsule Protocol without this header field. In such cases, a new header field can be defined to support extension negotiation.

Generic CAPSULE_ERROR code for HTTP/2 and HTTP/3 describes error handling for all HTTP versions. It defined the H3_DATAGRAM_ERROR code for HTTP/3, with the description "Datagram or Capsule Protocol parse error". Subsequent work that relies on using the Capsule protocol has identified that there are situations where using H3_DATAGRAM_ERROR can be confusing, such as where DATAGRAM capsules are expressly not allowed, but some other processing error related to capsules occurs. Furthermore, there is no registered HTTP/2 error code to articulate capsule-related errors (instead, this is delegated to HTTP/2 generic malformed handling defined in ). This document registers two generic error codes, CAPSULE_ERROR and H3_CAPSULE_ERROR (values TBD), for HTTP/2 and HTTP/3 respectively. This can be used as a general-purpose error for anything related to Capsule protocol handling, when a more-specific error is not available or is not preferred.

Security Considerations The ability to send capsule types that the peer may not know, and is therefore required to ignore, can be abused to cause a peer to expend additional processing time. This could become a burden when used unnecessarily or to excess. An endpoint that does not monitor such behavior exposes itself to a risk of denial-of-service attack. Implementations SHOULD track the use of unknown capsule types and set limits on their use. An endpoint MAY treat activity that is suspicious as a reason to close a connection, but false positives will result in disrupting valid connections and requests. For guidance on closing connections see , , and .

IANA Considerations TODO: register error codes

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. Informative References The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document specifies the HTTP/1.1 message syntax, message parsing, connection management, and related security concerns. This document obsoletes portions of RFC 7230. This specification describes an optimized expression of the semantics of the Hypertext Transfer Protocol (HTTP), referred to as HTTP version 2 (HTTP/2). HTTP/2 enables a more efficient use of network resources and a reduced latency by introducing field compression and allowing multiple concurrent exchanges on the same connection. This document obsoletes RFCs 7540 and 8740. The QUIC transport protocol has several features that are desirable in a transport for HTTP, such as stream multiplexing, per-stream flow control, and low-latency connection establishment. This document describes a mapping of HTTP semantics over QUIC. This document also identifies HTTP/2 features that are subsumed by QUIC and describes how HTTP/2 extensions can be ported to HTTP/3. This document describes how to proxy UDP in HTTP, similar to how the HTTP CONNECT method allows proxying TCP in HTTP. More specifically, this document defines a protocol that allows an HTTP client to create a tunnel for UDP communications through an HTTP server that acts as a proxy. This document describes how to proxy IP packets in HTTP. This protocol is similar to UDP proxying in HTTP but allows transmitting arbitrary IP packets. More specifically, this document defines a protocol that allows an HTTP client to create an IP tunnel through an HTTP server that acts as an IP proxy. This document updates RFC 9298. This document defines a mechanism for running the WebSocket Protocol (RFC 6455) over a single stream of an HTTP/2 connection. 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.

Acknowledgments David Schinazi and Tommy Pauly are capsule enthusiasts that suggested some ideas leading to the genesis of this document