WebTransport over HTTP/3
draft-ietf-webtrans-http3-08

Frindell, et al.          Expires 25 April 2024                 [Page 8]
Internet-Draft               WebTransport-H3                October 2023

   bidirectional stream and SHALL send a special signal value, encoded
   as a variable-length integer, as the first bytes of the stream in
   order to indicate how the remaining bytes on the stream are used.

   The signal value, 0x41, is used by clients and servers to open a
   bidirectional WebTransport stream.  Following this is the associated
   session ID, encoded as a variable-length integer; the rest of the
   stream is the application payload of the WebTransport stream
   (Figure 2).

   Bidirectional Stream {
       Signal Value (i) = 0x41,
       Session ID (i),
       Stream Body (..)
   }

             Figure 2: Bidirectional WebTransport stream format

   This document reserves the special signal value 0x41 as a
   WEBTRANSPORT_STREAM frame type.  While it is registered as an HTTP/3
   frame type to avoid collisions, WEBTRANSPORT_STREAM is not a proper
   HTTP/3 frame, as it lacks length; it is an extension of HTTP/3 frame
   syntax that MUST be supported by any peer negotiating WebTransport.
   Endpoints that implement this extension are also subject to
   additional frame handling requirements.  Endpoints MUST NOT send
   WEBTRANSPORT_STREAM as a frame type on HTTP/3 streams other than the
   very first bytes of a request stream.  Receiving this frame type in
   any other circumstances MUST be treated as a connection error of type
   H3_FRAME_ERROR.

4.3.  Resetting Data Streams

   A WebTransport endpoint may send a RESET_STREAM or a STOP_SENDING
   frame for a WebTransport data stream.  Those signals are propagated
   by the WebTransport implementation to the application.

Frindell, et al.          Expires 25 April 2024                 [Page 9]
Internet-Draft               WebTransport-H3                October 2023

   A WebTransport application SHALL provide an error code for those
   operations.  Since WebTransport shares the error code space with
   HTTP/3, WebTransport application errors for streams are limited to an
   unsigned 32-bit integer, assuming values between 0x00000000 and
   0xffffffff.  WebTransport implementations SHALL remap those error
   codes into the error range reserved for
   WEBTRANSPORT_APPLICATION_ERROR, where 0x00000000 corresponds to
   0x52e4a40fa8db, and 0xffffffff corresponds to 0x52e5ac983162.  Note
   that there are code points inside that range of form "0x1f * N +
   0x21" that are reserved by Section 8.1 of [HTTP3]; those have to be
   skipped when mapping the error codes (i.e. the two HTTP/3 error
   codepoints adjacent to a reserved codepoint would map to two adjacent
   WebTransport application error codepoints).  An example pseudocode
   can be seen in Figure 3.

       first = 0x52e4a40fa8db
       last = 0x52e5ac983162

       def webtransport_code_to_http_code(n):
           return first + n + floor(n / 0x1e)

       def http_code_to_webtransport_code(h):
           assert(first <= h <= last)
           assert((h - 0x21) % 0x1f != 0)
           shifted = h - first
           return shifted - floor(shifted / 0x1f)

          Figure 3: Pseudocode for converting between WebTransport
                 application errors and HTTP/3 error codes

   WebTransport data streams are associated with sessions through a
   header at the beginning of the stream; resetting a stream may result
   in that data being discarded.  Because of that, WebTransport
   application error codes are best effort, as the WebTransport stack is
   not always capable of associating the reset code with a session.  The
   only exception is the situation where there is only one session on a
   given HTTP/3 connection, and no intermediaries between the client and
   the server.

   WebTransport implementations SHALL forward the error code for a
   stream associated with a known session to the application that owns
   that session; similarly, the intermediaries SHALL reset the streams
   with corresponding error code when receiving a reset from the peer.
   If a WebTransport implementation intentionally allows only one
   session over a given HTTP/3 connection, it SHALL forward the error
   codes within WebTransport application error code range to the
   application that owns the only session on that connection.

Frindell, et al.          Expires 25 April 2024                [Page 10]
Internet-Draft               WebTransport-H3                October 2023

4.4.  Datagrams

   Datagrams can be sent using HTTP Datagrams.  The WebTransport
   datagram payload is sent unmodified in the "HTTP Datagram Payload"
   field of an HTTP Datagram (Section 2.1 of [HTTP-DATAGRAM]).  Note
   that the payload field directly follows the Quarter Stream ID field,
   which is at the start of the QUIC DATAGRAM frame payload and refers
   to the CONNECT stream that established the WebTransport session.

4.5.  Buffering Incoming Streams and Datagrams

   In WebTransport over HTTP/3, the client MAY send its SETTINGS frame,
   as well as multiple WebTransport CONNECT requests, WebTransport data
   streams and WebTransport datagrams, all within a single flight.  As
   those can arrive out of order, a WebTransport server could be put
   into a situation where it receives a stream or a datagram without a
   corresponding session.  Similarly, a client may receive a server-
   initiated stream or a datagram before receiving the CONNECT response
   headers from the server.

   To handle this case, WebTransport endpoints SHOULD buffer streams and
   datagrams until those can be associated with an established session.
   To avoid resource exhaustion, the endpoints MUST limit the number of
   buffered streams and datagrams.  When the number of buffered streams
   is exceeded, a stream SHALL be closed by sending a RESET_STREAM and/
   or STOP_SENDING with the WEBTRANSPORT_BUFFERED_STREAM_REJECTED error
   code.  When the number of buffered datagrams is exceeded, a datagram
   SHALL be dropped.  It is up to an implementation to choose what
   stream or datagram to discard.

4.6.  Interaction with HTTP/3 GOAWAY frame

   HTTP/3 defines a graceful shutdown mechanism (Section 5.2 of [HTTP3])
   that allows a peer to send a GOAWAY frame indicating that it will no
   longer accept any new incoming requests or pushes.

   A client receiving GOAWAY cannot initiate CONNECT requests for new
   WebTransport sessions if the stream identifier is equal to or greater
   than the indicated stream ID.

   An HTTP/3 GOAWAY frame is also a signal to applications to initiate
   shutdown for all WebTransport sessions.  To shut down a single
   WebTransport session, either endpoint can send a
   DRAIN_WEBTRANSPORT_SESSION (0x78ae) capsule.

Frindell, et al.          Expires 25 April 2024                [Page 11]
Internet-Draft               WebTransport-H3                October 2023

   DRAIN_WEBTRANSPORT_SESSION Capsule {
     Type (i) = DRAIN_WEBTRANSPORT_SESSION,
     Length (i) = 0
   }

   After sending or receiving either a DRAIN_WEBTRANSPORT_SESSION
   capsule or a HTTP/3 GOAWAY frame, an endpoint MAY continue using the
   session and MAY open new streams.  The signal is intended for the
   application using WebTransport, which is expected to attempt to
   gracefully terminate the session as soon as possible.

5.  Session Termination

   A WebTransport session over HTTP/3 is considered terminated when
   either of the following conditions is met:

   *  the CONNECT stream is closed, either cleanly or abruptly, on
      either side; or

   *  a CLOSE_WEBTRANSPORT_SESSION capsule is either sent or received.

   Upon learning that the session has been terminated, the endpoint MUST
   reset the send side and abort reading on the receive side of all of
   the streams associated with the session (see Section 2.4 of
   [RFC9000]) using the WEBTRANSPORT_SESSION_GONE error code; it MUST
   NOT send any new datagrams or open any new streams.

   To terminate a session with a detailed error message, an application
   MAY send an HTTP capsule [HTTP-DATAGRAM] of type
   CLOSE_WEBTRANSPORT_SESSION (0x2843).  The format of the capsule SHALL
   be as follows:

   CLOSE_WEBTRANSPORT_SESSION Capsule {
     Type (i) = CLOSE_WEBTRANSPORT_SESSION,
     Length (i),
     Application Error Code (32),
     Application Error Message (..8192),
   }

   CLOSE_WEBTRANSPORT_SESSION has the following fields:

   Application Error Code:  A 32-bit error code provided by the
      application closing the connection.

   Application Error Message:  A UTF-8 encoded error message string
      provided by the application closing the connection.  The message
      takes up the remainder of the capsule, and its length MUST NOT
      exceed 1024 bytes.

Frindell, et al.          Expires 25 April 2024                [Page 12]
Internet-Draft               WebTransport-H3                October 2023

   An endpoint that sends a CLOSE_WEBTRANSPORT_SESSION capsule MUST
   immediately send a FIN.  The endpoint MAY send a STOP_SENDING to
   indicate it is no longer reading from the CONNECT stream.  The
   recipient MUST close the stream upon receiving a FIN.  If any
   additional stream data is received on the CONNECT stream after
   receiving a CLOSE_WEBTRANSPORT_SESSION capsule, the stream MUST be
   reset with code H3_MESSAGE_ERROR.

   Cleanly terminating a CONNECT stream without a
   CLOSE_WEBTRANSPORT_SESSION capsule SHALL be semantically equivalent
   to terminating it with a CLOSE_WEBTRANSPORT_SESSION capsule that has
   an error code of 0 and an empty error string.

   In some scenarios, an endpoint might want to send a
   CLOSE_WEBTRANSPORT_SESSION with detailed close information and then
   immediately close the underlying QUIC connection.  If the endpoint
   were to do both of those simultaneously, the peer could potentially
   receive the CONNECTION_CLOSE before receiving the
   CLOSE_WEBTRANSPORT_SESSION, thus never receiving the application
   error data contained in the latter.  To avoid this, the endpoint
   SHOULD wait until all of the data on the CONNECT stream is
   acknowledged before sending the CONNECTION_CLOSE; this gives
   CLOSE_WEBTRANSPORT_SESSION properties similar to that of the QUIC
   CONNECTION_CLOSE mechanism as a best-effort mechanism of delivering
   application close metadata.

6.  Negotiating the Draft Version

   [[RFC editor: please remove this section before publication.]]

   The wire format aspects of the protocol are negotiated by changing
   the codepoint used for the SETTINGS_WEBTRANSPORT_MAX_SESSIONS
   parameter.  Because of that, any WebTransport endpoint MUST wait for
   the peer's SETTINGS frame before sending or processing any
   WebTransport traffic.  When multiple versions are supported by both
   of the peers, the most recent version supported by both is selected.

7.  Security Considerations

   WebTransport over HTTP/3 satisfies all of the security requirements
   imposed by [OVERVIEW] on WebTransport protocols, thus providing a
   secure framework for client-server communication in cases when the
   client is potentially untrusted.

Frindell, et al.          Expires 25 April 2024                [Page 13]
Internet-Draft               WebTransport-H3                October 2023

   WebTransport over HTTP/3 requires explicit opt-in through the use of
   an HTTP/3 setting; this avoids potential protocol confusion attacks
   by ensuring the HTTP/3 server explicitly supports it.  It also
   requires the use of the Origin header, providing the server with the
   ability to deny access to Web-based clients that do not originate
   from a trusted origin.

   Just like HTTP traffic going over HTTP/3, WebTransport pools traffic
   to different origins within a single connection.  Different origins
   imply different trust domains, meaning that the implementations have
   to treat each transport as potentially hostile towards others on the
   same connection.  One potential attack is a resource exhaustion
   attack: since all of the transports share both congestion control and
   flow control context, a single client aggressively using up those
   resources can cause other transports to stall.  The user agent thus
   SHOULD implement a fairness scheme that ensures that each transport
   within connection gets a reasonable share of controlled resources;
   this applies both to sending data and to opening new streams.

   A client could attempt to exhaust resources by opening too many
   WebTransport sessions at once.  In cases when the client is
   untrusted, the user agent SHOULD limit the number of outgoing
   sessions the client can open.

8.  IANA Considerations

8.1.  Upgrade Token Registration

   The following entry is added to the "Hypertext Transfer Protocol
   (HTTP) Upgrade Token Registry" registry established by Section 16.7
   of [HTTP].

   The "webtransport" label identifies HTTP/3 used as a protocol for
   WebTransport:

   Value:  webtransport

   Description:  WebTransport over HTTP/3

   Reference:  This document and [I-D.ietf-webtrans-http2]

8.2.  HTTP/3 SETTINGS Parameter Registration

   The following entry is added to the "HTTP/3 Settings" registry
   established by [HTTP3]:

Frindell, et al.          Expires 25 April 2024                [Page 14]
Internet-Draft               WebTransport-H3                October 2023

   The SETTINGS_WEBTRANSPORT_MAX_SESSIONS parameter indicates that the
   specified HTTP/3 endpoint is WebTransport-capable and, for servers,
   the number of concurrent sessions it is willing to receive.  The
   default value for the SETTINGS_WEBTRANSPORT_MAX_SESSIONS parameter is
   "0", meaning that the endpoint is not willing to receive any
   WebTransport sessions.

   Setting Name:  WEBTRANSPORT_MAX_SESSIONS

   Value:  0xc671706a

   Default:  0

   Specification:  This document

8.3.  Frame Type Registration

   The following entry is added to the "HTTP/3 Frame Type" registry
   established by [HTTP3]:

   The WEBTRANSPORT_STREAM frame is reserved for the purpose of avoiding
   collision with WebTransport HTTP/3 extensions:

   Code:  0x41

   Frame Type:  WEBTRANSPORT_STREAM

   Specification:  This document

8.4.  Stream Type Registration

   The following entry is added to the "HTTP/3 Stream Type" registry
   established by [HTTP3]:

   The "WebTransport stream" type allows unidirectional streams to be
   used by WebTransport:

   Code:  0x54

   Stream Type:  WebTransport stream

   Specification:  This document

   Sender:  Both

Frindell, et al.          Expires 25 April 2024                [Page 15]
Internet-Draft               WebTransport-H3                October 2023

8.5.  HTTP/3 Error Code Registration

   The following entry is added to the "HTTP/3 Error Code" registry
   established by [HTTP3]:

   Name:  WEBTRANSPORT_BUFFERED_STREAM_REJECTED

   Value:  0x3994bd84

   Description:  WebTransport data stream rejected due to lack of
      associated session.

   Specification:  This document.

   Name:  WEBTRANSPORT_SESSION_GONE

   Value:  0x170d7b68

   Description:  WebTransport data stream aborted because the associated
      WebTransport session has been closed.

   Specification:  This document.

   In addition, the following range of entries is registered:

   Name:  WEBTRANSPORT_APPLICATION_ERROR

   Value:  0x52e4a40fa8db to 0x52e5ac983162 inclusive, with the
      exception of the codepoints of form 0x1f * N + 0x21.

   Description:  WebTransport application error codes.

   Specification:  This document.

8.6.  Capsule Types

   The following entries are added to the "HTTP Capsule Types" registry
   established by [HTTP-DATAGRAM]:

   The CLOSE_WEBTRANSPORT_SESSION capsule.

   Value:  0x2843
   Capsule Type:  CLOSE_WEBTRANSPORT_SESSION
   Status:  permanent
   Specification:  This document
   Change Controller:  IETF
   Contact:  WebTransport Working Group webtransport@ietf.org
      (mailto:webtransport@ietf.org)

Frindell, et al.          Expires 25 April 2024                [Page 16]
Internet-Draft               WebTransport-H3                October 2023

   Notes:  None

   The DRAIN_WEBTRANSPORT_SESSION capsule.

   Value:  0x78ae
   Capsule Type:  DRAIN_WEBTRANSPORT_SESSION
   Status:  provisional (when this document is approved this will become
      permanent)
   Specification:  This document
   Change Controller:  IETF
   Contact:  WebTransport Working Group webtransport@ietf.org
      (mailto:webtransport@ietf.org)
   Notes:  None

9.  References

9.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-DATAGRAM]
              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>.

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

   [OVERVIEW] Vasiliev, V., "The WebTransport Protocol Framework", Work
              in Progress, Internet-Draft, draft-ietf-webtrans-overview-
              06, 6 September 2023,
              <https://datatracker.ietf.org/doc/html/draft-ietf-
              webtrans-overview-06>.

   [QUIC-DATAGRAM]
              Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable
              Datagram Extension to QUIC", RFC 9221,
              DOI 10.17487/RFC9221, March 2022,
              <https://www.rfc-editor.org/rfc/rfc9221>.

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

Frindell, et al.          Expires 25 April 2024                [Page 17]
Internet-Draft               WebTransport-H3                October 2023

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66,
              RFC 3986, DOI 10.17487/RFC3986, January 2005,
              <https://www.rfc-editor.org/rfc/rfc3986>.

   [RFC6454]  Barth, A., "The Web Origin Concept", RFC 6454,
              DOI 10.17487/RFC6454, December 2011,
              <https://www.rfc-editor.org/rfc/rfc6454>.

   [RFC6585]  Nottingham, M. and R. Fielding, "Additional HTTP Status
              Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012,
              <https://www.rfc-editor.org/rfc/rfc6585>.

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

   [RFC8441]  McManus, P., "Bootstrapping WebSockets with HTTP/2",
              RFC 8441, DOI 10.17487/RFC8441, September 2018,
              <https://www.rfc-editor.org/rfc/rfc8441>.

   [RFC9000]  Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based
              Multiplexed and Secure Transport", RFC 9000,
              DOI 10.17487/RFC9000, May 2021,
              <https://www.rfc-editor.org/rfc/rfc9000>.

   [RFC9218]  Oku, K. and L. Pardue, "Extensible Prioritization Scheme
              for HTTP", RFC 9218, DOI 10.17487/RFC9218, June 2022,
              <https://www.rfc-editor.org/rfc/rfc9218>.

   [RFC9220]  Hamilton, R., "Bootstrapping WebSockets with HTTP/3",
              RFC 9220, DOI 10.17487/RFC9220, June 2022,
              <https://www.rfc-editor.org/rfc/rfc9220>.

9.2.  Informative References

   [I-D.ietf-webtrans-http2]
              Frindell, A., Kinnear, E., Pauly, T., Thomson, M.,
              Vasiliev, V., and G. Xie, "WebTransport over HTTP/2", Work
              in Progress, Internet-Draft, draft-ietf-webtrans-http2-06,
              10 July 2023, <https://datatracker.ietf.org/doc/html/
              draft-ietf-webtrans-http2-06>.

Appendix A.  Changelog

Frindell, et al.          Expires 25 April 2024                [Page 18]
Internet-Draft               WebTransport-H3                October 2023

A.1.  Changes between draft versions 02 and 07

   The following changes make the draft-02 and draft-07 versions of this
   protocol incompatible:

   *  draft-07 requires SETTINGS_WEBTRANSPORT_MAX_SESSIONS (#86) and
      uses it for version negotiation (#129)

   *  draft-07 explicitly requires SETTINGS_ENABLE_CONNECT_PROTOCOL to
      be enabled (#93)

   *  draft-07 explicitly requires SETTINGS_H3_DATAGRAM to be enabled
      (#106)

   *  draft-07 only allows WEBTRANSPORT_STREAM at the beginning of the
      stream

   The following changes that are present in draft-07 can be also
   implemented by a draft-02 implementation safely:

   *  Expanding stream reset error code space from 8 to 32 bits (#115)

   *  WEBTRANSPORT_SESSION_GONE error code (#75)

   *  Handling for HTTP GOAWAY (#76)

   *  DRAIN_WEBTRANSPORT_SESSION capsule (#79)

   *  Disallowing following redirects automatically (#113)

Authors' Addresses

   Alan Frindell
   Facebook
   Email: afrind@fb.com

   Eric Kinnear
   Apple Inc.
   Email: ekinnear@apple.com

   Victor Vasiliev
   Google
   Email: vasilvv@google.com

Frindell, et al.          Expires 25 April 2024                [Page 19]