]> Google LLC

1600 Amphitheatre Parkway Mountain View CA 94043 United States of America dschinazi.ietf@gmail.com

Web and Internet Transport HTTPBIS secure tunnels masque http-ng HTTP intermediaries sometimes 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. To avoid user-visible failures, it is best for the intermediary 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 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. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the HTTP Working Group mailing list (), which is archived at . Working Group information can be found at . Source for this draft and an issue tracker can be found at .

Introduction HTTP intermediaries (see ) 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 and ). This instructs the client to send future requests to a different intermediary without impacting their active requests.

Gateway Sends GOAWAY

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 ) or connect-udp (see ) 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.

Proxy Sends WRAP_UP

This document specifies a new "WRAP_UP" capsule (see ) 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.

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. This document uses the terms "connection", "client", and "server" from and the terms "intermediary", "proxy", and "gateway" from .

Mechanism This document defines the "WRAP_UP" capsule (see 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.

Proxy Behavior Proxies often know in advance that they will close a request stream. This can be due to maintenance of the proxy itself, load balancing, or applying data usage limits on a particular stream. When a proxy has advance notice that it will soon close a request stream, it MAY send a WRAP_UP capsule to share that information with the client. This can also be used when the proxy wishes to release resources associated with a request stream, such as HTTP Datagrams (see ) or WebTransport streams (see ).

Client Handling When a client receives a WRAP_UP capsule on a request stream, it SHOULD try to wrap up its use of that stream. For example, if the stream carried a connect-udp request and is used as the underlying transport for an HTTP/3 connection, then after receiving a WRAP_UP capsule the client SHOULD NOT send any new requests on the proxied HTTP/3 connection - but existing in-progress proxied requests are not affected by the WRAP_UP capsule.

Minutiae Clients MUST NOT send the WRAP_UP capsule. If a server receives a WRAP_UP capsule, it MUST abort the corresponding request stream. Endpoints MUST NOT send the WRAP_UP capsule with a non-zero Capsule Length. If an endpoint receives a WRAP_UP capsule with a non-zero Capsule Length, it MUST abort the corresponding request stream. Proxies MUST NOT send more than one WRAP_UP capsule on a given stream. If a client receives a second WRAP_UP capsule on a given request stream, it MUST abort the stream. Endpoints that abort the request stream due to an unexpected or malformed WRAP_UP capsule received over HTTP/3 SHOULD use the H3_DATAGRAM_ERROR error code when aborting the stream.

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.

IANA Considerations This document (if approved) will request IANA to add the following entry to the "HTTP Capsule Types" registry maintained at <>.

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

References Normative 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. 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 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. Facebook Apple Inc. Google WebTransport [OVERVIEW] is a protocol framework that enables clients constrained by the Web security model to communicate with a remote server using a secure multiplexed transport. This document describes a WebTransport protocol that is based on HTTP/3 [HTTP3] and provides support for unidirectional streams, bidirectional streams and datagrams, all multiplexed within the same HTTP/3 connection.

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