The HTTP Wrap Up Capsule

Status of This Memo

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 6 January 2025.¶

Copyright Notice

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.¶

Table of Contents

1. Introduction

HTTP intermediaries (see Section 3.7 of [HTTP]) can provide a variety of benefits to HTTP systems, such as load balancing, caching, and privacy improvements. Deployments of intermediaries also need to be maintained, which can sometimes require taking intermediaries temporarily offline. Additionally, sometimes intermediaries need to terminate long-lived request streams in order to facilitate load balancing or impose data limits. However, Web browsers commonly cannot retry failed proxied requests when they cannot ascertain whether an in-progress request was acted on.¶

When a long-lived HTTP connection to a gateway carries many short-lived streams, it is currently possible to inform the client of an upcoming graceful termination by leveraging the GOAWAY frame (see Section 5.2 of [HTTP/3] and Section 6.8 of [HTTP/2]). This instructs the client to send future requests to a different intermediary without impacting their active requests.¶

However, GOAWAY is not well suited for cases where there is a single long-lived request. For example, this happens when the client sends a CONNECT (see Section 9.3.6 of [HTTP]) or connect-udp (see [CONNECT-UDP]) request to the proxy, and then uses the newly established tunnel as the underlying transport to then establish a second HTTP connection directly to the origin. In that situation, the proxy cannot inspect the contents of the tunnel, nor inject any data into it; the proxy only sees a single long-lived request. The proxy is responsible for managing the lifetime of the tunnel, but can only terminate it abortively. Such abrupt termination can lead to truncated content, which the client cannot safely request again.¶

To avoid user-visible failures, it is best for the proxy to inform the client of upcoming request stream terminations in advance of the actual termination so that the client can wrap up existing operations related to that stream and start sending new work to a different stream or connection.¶

This document specifies a new "WRAP_UP" capsule (see Section 3 of [HTTP-DGRAM]) that allows a proxy to instruct a client that it should not start new requests on a tunneled connection, while still allowing it to finish existing requests.¶

2. Mechanism

This document defines the "WRAP_UP" capsule (see Section 4 for the value). The WRAP_UP capsule allows a proxy to indicate to a client that it wishes to close the request stream that the capsule was sent on. The WRAP_UP capsule has no Capsule Value.¶

3. Security Considerations

While it might be tempting for clients to implement the WRAP_UP capsule by treating it as if they had received a GOAWAY inside the encryption of the end-to-end connection, doing so has security implications. GOAWAY carries semantics around which requests have been acted on, and those can have security implications. Since WRAP_UP is sent by a proxy outside of the end-to-end encryption, it cannot be trusted to ascertain whether any requests were handled by the origin. Because of this, client implementations can only use receipt of WRAP_UP as a hint and MUST NOT use it to make determinations on whether any requests were handled by the origin or not.¶

4. IANA Considerations

This document (if approved) will request IANA to add the following entry to the "HTTP Capsule Types" registry maintained at <https://www.iana.org/assignments/masque>.¶

Value:

0x272DDA5E (will be changed to a lower value if this document is approved)¶

Capsule Type:

WRAP_UP¶

Status:

provisional (will be permanent if this document is approved)¶

Reference:

This document¶

Change Controller:

IETF¶

Contact:

ietf-http-wg@w3.org¶

Notes:

None¶

Acknowledgments

This mechanism was inspired by the GOAWAY frame from HTTP/2.¶

Author's Address