The HTTP Wrap Up Capsule
draft-schinazi-httpbis-wrap-up-00

HTTPBIS                                                      D. Schinazi
Internet-Draft                                                Google LLC
Intended status: Standards Track                             5 July 2024
Expires: 6 January 2025

                        The HTTP Wrap Up Capsule
                   draft-schinazi-httpbis-wrap-up-00

Abstract

   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

   This note is to be removed before publishing as an RFC.

   The latest revision of this draft can be found at
   https://davidschinazi.github.io/draft-schinazi-httpbis-wrap-
   up/#go.draft-schinazi-httpbis-wrap-up.html.  Status information for
   this document may be found at https://datatracker.ietf.org/doc/draft-
   schinazi-httpbis-wrap-up/.

   Discussion of this document takes place on the HTTP Working Group
   mailing list (mailto:ietf-http-wg@w3.org), which is archived at
   https://lists.w3.org/Archives/Public/ietf-http-wg/.  Working Group
   information can be found at https://httpwg.org/.

   Source for this draft and an issue tracker can be found at
   https://github.com/DavidSchinazi/draft-schinazi-httpbis-wrap-up.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

Schinazi                 Expires 6 January 2025                 [Page 1]
Internet-Draft          The HTTP Wrap Up Capsule               July 2024

   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  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Conventions and Definitions . . . . . . . . . . . . . . .   4
   2.  Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . .   4
     2.1.  Proxy Behavior  . . . . . . . . . . . . . . . . . . . . .   5
     2.2.  Client Handling . . . . . . . . . . . . . . . . . . . . .   5
     2.3.  Minutiae  . . . . . . . . . . . . . . . . . . . . . . . .   5
   3.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
   4.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
   5.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   6
     5.1.  Normative References  . . . . . . . . . . . . . . . . . .   6
     5.2.  Informative References  . . . . . . . . . . . . . . . . .   6
   Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .   7
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   7

Schinazi                 Expires 6 January 2025                 [Page 2]
Internet-Draft          The HTTP Wrap Up Capsule               July 2024

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.

   +--------+      +---------+      +--------+
   | Client |      | Gateway |      | Origin |
   |        |      |       * |      |      * |
   |        +======+ GOAWAY| +~~~~~~+      | |
   |      <----------------+               | |
   |                         HTTP Responses| |
   |      <--------------------------------+ |
   |        +======+         +~~~~~~+        |
   +--------+  ^   +---------+   ^  +--------+
               |                 |
        TLS --'                   '-- TLS

                       Figure 1: 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 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.

Schinazi                 Expires 6 January 2025                 [Page 3]
Internet-Draft          The HTTP Wrap Up Capsule               July 2024

   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.

   +--------+      +---------+      +--------+
   | Client |      |  Proxy  |      | Origin |
   |        |      |       * |      |      * |
   |        +======+WRAP_UP| |      |      | |
   |      <----------------+ |      |      | |
   |        +~~~~~~~~~~~~~~~~+~~~~~~+      | |
   |                         HTTP Responses| |
   |      <--------------------------------+ |
   |        +~~~~~~+~~~~~~~~~+~~~~~~+        |
   |        +======+         |   ^  +        |
   +--------+  ^   +---------+   |  +--------+
               |                 |
        TLS --'                   '-- TLS

                       Figure 2: Proxy Sends WRAP_UP

   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.

1.1.  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 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

   This document uses the terms "connection", "client", and "server"
   from Section 3.3 of [HTTP] and the terms "intermediary", "proxy", and
   "gateway" from Section 3.7 of [HTTP].

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.

Schinazi                 Expires 6 January 2025                 [Page 4]
Internet-Draft          The HTTP Wrap Up Capsule               July 2024

2.1.  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
   Section 2 of [HTTP-DGRAM]) or WebTransport streams (see
   [WEBTRANSPORT]).

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

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

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

Schinazi                 Expires 6 January 2025                 [Page 5]
Internet-Draft          The HTTP Wrap Up Capsule               July 2024

   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

5.  References

5.1.  Normative References

   [HTTP]     Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP Semantics", STD 97, RFC 9110,
              DOI 10.17487/RFC9110, June 2022,
              <https://www.rfc-editor.org/rfc/rfc9110>.

   [HTTP-DGRAM]
              Schinazi, D. and L. Pardue, "HTTP Datagrams and the
              Capsule Protocol", RFC 9297, DOI 10.17487/RFC9297, August
              2022, <https://www.rfc-editor.org/rfc/rfc9297>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

5.2.  Informative References

   [CONNECT-UDP]
              Schinazi, D., "Proxying UDP in HTTP", RFC 9298,
              DOI 10.17487/RFC9298, August 2022,
              <https://www.rfc-editor.org/rfc/rfc9298>.

Schinazi                 Expires 6 January 2025                 [Page 6]
Internet-Draft          The HTTP Wrap Up Capsule               July 2024

   [HTTP/2]   Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113,
              DOI 10.17487/RFC9113, June 2022,
              <https://www.rfc-editor.org/rfc/rfc9113>.

   [HTTP/3]   Bishop, M., Ed., "HTTP/3", RFC 9114, DOI 10.17487/RFC9114,
              June 2022, <https://www.rfc-editor.org/rfc/rfc9114>.

   [WEBTRANSPORT]
              Frindell, A., Kinnear, E., and V. Vasiliev, "WebTransport
              over HTTP/3", Work in Progress, Internet-Draft, draft-
              ietf-webtrans-http3-09, 4 March 2024,
              <https://datatracker.ietf.org/doc/html/draft-ietf-
              webtrans-http3-09>.

Acknowledgments

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

Author's Address

   David Schinazi
   Google LLC
   1600 Amphitheatre Parkway
   Mountain View, CA 94043
   United States of America
   Email: dschinazi.ietf@gmail.com

Schinazi                 Expires 6 January 2025                 [Page 7]