| Internet-Draft | HTTP Capsule Extension Guidance | October 2024 |
| Pardue | Expires 24 April 2025 | [Page] |
This document updates RFC 9297 with further guidance for extensibility of the HTTP Capsule Protocol.¶
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://LPardue.github.io/draft-pardue-capsule-ext-guidance/draft-pardue-capsule-ext-guidance.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-pardue-capsule-ext-guidance/.¶
Source for this draft and an issue tracker can be found at https://github.com/LPardue/draft-pardue-capsule-ext-guidance.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 24 April 2025.¶
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
The Capsule Protocol [CAPSULE] 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 Section 3 of [CAPSULE]. 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.¶
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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
In order to support extensibility, Section 3.2 of [CAPSULE] 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 [UDP-PROXYING] makes use of the upgrade token "connect-udp" to enable the Connect Protocol. It describes how DATAGRAM capsules (Section 3.5 of [CAPSULE]) 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 [IP-PROXYING] makes use of the upgrade token "connect-ip" to enable the Connect Protocol. It defines ADDRESS_ASSIGN, ADDRESS_REQUEST, and ROUTE_ADVERTISEMENT capsules (Section 4.7 of [IP-PROXYING]) 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 [UDP-PROXYING].¶
The [CAPSULE] document requires updated text to resolve this ambuguity. Should this document be adopted, consensus on the resolution can be established.¶
The second ambiguity with the text in Section 3.2 of [CAPSULE] 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 (Section 5.5 of [HTTP/2] and Section 9 of [HTTP/3]) 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 (Section 7.8 of [HTTP]), extended CONNECT ([EXT-CONNECT2] and [EXTCONNECT3]) 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.¶
Section 3.3 of [CAPSULE] 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 Section 8.1.1 of [HTTP/2]).¶
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.¶
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 Section 9.6 of [HTTP/1.1], Section 5.5 of [HTTP/2], and Section 9 of [HTTP/3].¶
TODO: register error codes¶
David Schinazi and Tommy Pauly are capsule enthusiasts that suggested some ideas leading to the genesis of this document¶