index.bs

<pre class="metadata">
Title: WebTransport
Shortname: webtransport
Level: none
Status: w3c/ED
Group: webtransport
ED: https://w3c.github.io/webtransport/
TR: https://www.w3.org/TR/webtransport/
Editor: Bernard Aboba, w3cid 65611, Microsoft Corporation
Editor: Victor Vasiliev, w3cid 113328,Google
Editor: Yutaka Hirano, w3cid 100504,Google
Former Editor: Peter Thatcher, Google
Former Editor: Robin Raymond, Optical Tone Ltd.
Abstract:
  This document defines a set of ECMAScript APIs in WebIDL to allow data to be
  sent and received between a browser and server, utilizing [[WEB-TRANSPORT-HTTP3]].
  This specification is being developed in conjunction with a protocol
  specification developed by the IETF WEBTRANS Working Group.
Repository: w3c/webtransport
Indent: 2
Markup Shorthands: markdown yes
Boilerplate: omit conformance
</pre>
<pre class="biblio">
{
  "quic": {
    "authors": ["Jana Iyengar", "Martin Thomson"],
    "href": "https://tools.ietf.org/html/draft-ietf-quic-transport",
    "title": "QUIC: A UDP-Based Multiplexed and Secure Transport",
    "status": "Internet-Draft",
    "publisher": "IETF"
  },
  "quic-datagram": {
    "authors": ["Tommy Pauly", "Eric Kinnear", "David Schinazi"],
    "href": "https://datatracker.ietf.org/doc/html/draft-ietf-quic-datagram/",
    "title": "An Unreliable Datagram Extension to QUIC",
    "status": "Internet-Draft",
    "publisher": "IETF"
  },
    "http3-datagram": {
    "authors": ["David Schinazi", "Lucas Pardue"],
    "href": "https://datatracker.ietf.org/doc/html/draft-ietf-masque-h3-datagram",
    "title": "Using QUIC Datagrams with HTTP/3",
    "status": "Internet-Draft",
    "publisher": "IETF"
  },
  "web-transport-overview": {
    "authors": ["Victor Vasiliev"],
    "href": "https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-overview",
    "title": "WebTransport Protocol Framework",
    "status": "Internet-Draft",
    "publisher": "IETF"
  },
  "web-transport-quic": {
    "authors": ["Victor Vasiliev"],
    "href": "https://datatracker.ietf.org/doc/html/draft-vvv-webtransport-quic",
    "title": "WebTransport over QUIC",
    "status": "Internet-Draft",
    "publisher": "IETF"
  },
  "web-transport-http3": {
    "authors": ["Victor Vasiliev"],
    "href": "https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/",
    "title": "WebTransport over HTTP/3",
    "status": "Internet-Draft",
    "publisher": "IETF"
  }
}
</pre>
<pre class="link-defaults">
spec:streams; type:interface; text:ReadableStream
spec:html; type:dfn; for:/; text:origin
spec:fetch; type:dfn; for:/; text:fetch
spec:url; type:dfn; text:scheme
spec:url; type:dfn; text:fragment
</pre>
<pre class="anchors">
urlPrefix: http://www.ecma-international.org/ecma-262/6.0/index.html; spec: ECMASCRIPT-6.0
  type: dfn
    text: fulfilled; url: sec-promise-objects
    text: rejected; url: sec-promise-objects
    text: pending; url: sec-promise-objects
    text: resolved; url: sec-promise-objects
    text: settled; url: sec-promise-objects
</pre>

# Introduction #    {#introduction}

*This section is non-normative.*

This specification uses [[!WEB-TRANSPORT-HTTP3]] to send data to and receive
data from servers. It can be used like WebSockets but with support for multiple
streams, unidirectional streams, out-of-order delivery, and reliable as well as
unreliable transport.

Note: The API presented in this specification represents a preliminary proposal
based on work-in-progress within the IETF WEBTRANS WG. Since the [[!WEB-TRANSPORT-HTTP3]]
specification is a work-in-progress, both the protocol and API are likely to
change significantly going forward.

# Conformance #  {#conformance}

As well as sections marked as non-normative, all authoring guidelines,
diagrams, examples, and notes in this specification are non-normative.
Everything else in this specification is normative.

The key words *MUST* and *SHOULD* are to be interpreted as described in
[[!RFC2119]].

This specification defines conformance criteria that apply to a single product:
the user agent that implements the interfaces that it contains.

Conformance requirements phrased as algorithms or specific steps may be
implemented in any manner, so long as the end result is equivalent. (In
particular, the algorithms defined in this specification are intended to be
easy to follow, and not intended to be performant.)

Implementations that use ECMAScript to implement the APIs defined in this
specification MUST implement them in a manner consistent with the ECMAScript
Bindings defined in the Web IDL specification [[!WEBIDL]], as this
specification uses that specification and terminology.

# Terminology #  {#terminology}

The {{EventHandler}} interface, representing a callback used for event
handlers, and the {{ErrorEvent}} interface are defined in [[!HTML]].

The concepts [=queue a task=] and [=networking task source=] are defined in
[[!HTML]].

The terms [=event=], [=event handlers=] and [=event handler event types=] are
defined in [[!HTML]].

When referring to exceptions, the terms [=throw=] and [=create=] are defined in
[[!WEBIDL]].

The terms [=fulfilled=], [=rejected=], [=resolved=], [=pending=] and
[=settled=] used in the context of Promises are defined in [[!ECMASCRIPT-6.0]].

The terms {{ReadableStream}} and {{WritableStream}} are defined in
[[!WHATWG-STREAMS]].

# Protocol concepts # {#protocol-concepts}

A <dfn>WebTransport session</dfn> is a session of WebTransport over HTTP/3.
There may be multiple [=WebTransport session=]s on one [=connection=], when pooling is enabled.

[=WebTransport session=] has the following capabilities defined in [[!WEB-TRANSPORT-HTTP3]].

<table class="data" dfn-for="session">
 <thead>
  <tr>
   <th>capability
   <th>definition
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><dfn>send a datagram</dfn>
   <td>[[!WEB-TRANSPORT-HTTP3]]
   [section 4.4](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/#section-4.4)
  </tr>
  <tr>
   <td><dfn>receive a datagram</dfn>
   <td>[[!WEB-TRANSPORT-HTTP3]]
   [section 4.4](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/#section-4.4)
  </tr>
  <tr>
   <td><dfn>create an [=stream/outgoing=] stream</dfn>
   <td>[[!WEB-TRANSPORT-HTTP3]]
   [section 4.1](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/#section-4.1)
  </tr>
  <tr>
   <td><dfn>create a [=stream/bidirectional=] stream</dfn>
   <td>[[!WEB-TRANSPORT-HTTP3]]
   [section 4.2](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/#section-4.2)
  </tr>
  <tr>
   <td><dfn>receive an [=stream/incoming=] stream</dfn>
   <td>[[!WEB-TRANSPORT-HTTP3]]
   [section 4.1](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/#section-4.1)
  </tr>
  <tr>
   <td><dfn>receive a [=stream/bidirectional=] stream</dfn>
   <td>[[!WEB-TRANSPORT-HTTP3]]
   [section 4.3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/#section-4.3)
  </tr>
 </tbody>
</table>

To <dfn for=session>establish</dfn> a [=WebTransport session=], follow [[!WEB-TRANSPORT-HTTP3]]
[section 3.3](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/#section-3.3).

To <dfn for=session>terminate</dfn> a [=WebTransport session=] |session| with an integer |code|,
follow [[!WEB-TRANSPORT-HTTP3]]
[section 5](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/#section-5).

<dfn>WebTransport stream</dfn> is a concept for HTTP/3 stream on a [=WebTransport session=].

A [=WebTransport stream=] is one of <dfn for=stream>incoming</dfn>, <dfn for=stream>outgoing</dfn>
or <dfn for=stream>bidirectional</dfn>.

[=WebTransport stream=] has the following capabilities:

<table class="data" dfn-for="stream">
 <thead>
  <tr>
   <th>capability
   <th>definition
   <th>incoming
   <th>outgoing
   <th>bidirectional
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><dfn>send</dfn> bytes (potentially with FIN)
   <td>[[!QUIC]]
   [section 2.2](https://datatracker.ietf.org/doc/html/draft-ietf-quic-transport#section-2.2)
   <td>No
   <td>Yes
   <td>Yes
  </tr>
  <tr>
   <td><dfn>receive</dfn> bytes (potentially with FIN)
   <td>[[!QUIC]]
   [section 2.2](https://datatracker.ietf.org/doc/html/draft-ietf-quic-transport#section-2.2)
   <td>Yes
   <td>No
   <td>Yes
  </tr>
  <tr>
   <td><dfn>send STOP_SENDING</dfn>
   <td>[[!QUIC]]
   [section 3.5](https://datatracker.ietf.org/doc/html/draft-ietf-quic-transport#section-3.5)
   <td>Yes
   <td>No
   <td>Yes
  </tr>
  <tr>
   <td><dfn>reset</dfn> a [=WebTransport stream=]
   <td>[[!QUIC]]
   [section 19.4](https://datatracker.ietf.org/doc/html/draft-ietf-quic-transport#section-19.4)
   <td>No
   <td>Yes
   <td>Yes
  </tr>
 </tbody>
</table>


# `UnidirectionalStreamsTransport` Mixin #  {#unidirectional-streams-transport}

A {{UnidirectionalStreamsTransport}} can send and receive unidirectional
streams.  Data within a stream is delivered in order, but data between streams
may be delivered out of order.  Data is generally sent reliably, but
retransmissions may be disabled or the stream may aborted to produce a form of
unreliability.  All stream data is encrypted and congestion-controlled.

<pre class="idl">
interface mixin UnidirectionalStreamsTransport {
  Promise&lt;SendStream&gt; createUnidirectionalStream(optional SendStreamParameters parameters = {});
  /* a ReadableStream of ReceiveStream objects */
  readonly attribute ReadableStream incomingUnidirectionalStreams;
};
</pre>

## Methods ##  {#unidirectional-streams-transport-methods}

: <dfn for="UnidirectionalStreamsTransport" method>createUnidirectionalStream()</dfn>

:: Creates a {{SendStream}} object for an outgoing unidirectional stream.  Note
   that in some transports, the mere creation of a stream is not immediately
   visible to the peer until it is used to send data.

   When `createUnidirectionalStream()` method is called, the user agent MUST
   run the following steps:
     1. Let |transport| be the `UnidirectionalStreamsTransport` on which
        `createUnidirectionalStream` is invoked.
     1. If |transport|'s {{WebTransport/state}} is `"closed"` or `"failed"`,
        immediately return a new [=rejected=] promise with a newly created
        {{InvalidStateError}} and abort these steps.
     1. Let |p| be a new promise.
     1. Return |p| and continue the remaining steps [=in parallel=].
     1. [=SendStream/Create=] a {{SendStream}} with |transport| and |p| when all
        of the following conditions are met:
         1. The |transport|'s {{WebTransport/state}} is `"connected"`.
         1. Stream creation flow control is not being violated by exceeding the
            max stream limit set by the remote endpoint, as specified in
            [[!QUIC]].
         1. |p| has not been [=settled=].
     1. Queue a task to [=reject=] |p| with a newly created {{InvalidStateError}}
        when all of the following conditions are met:
         1. The |transport|'s state is `"closed"` or `"failed"`.
         1. |p| has not been [=settled=].

: <dfn for="UnidirectionalStreamsTransport" attribute>incomingUnidirectionalStreams</dfn>
:: A {{ReadableStream}} of unidirectional streams, each represented by a
   {{ReceiveStream}} object, that have been received from the remote host.

   The getter steps for `incomingUnidirectionalStreams` are:
     1. Let |transport| be the `UnidirectionalStreamsTransport` on which
        the `incomingUnidirectionalStreams` getter is invoked.
     1. Return |transport|'s [=[[ReceivedStreams]]=].
     1. For each unidirectional stream received, create a corresponding
        {{ReceiveStream}} and insert it into [=[[ReceivedStreams]]=]. As data
        is received over the unidirectional stream, insert that data into the
        corresponding `ReceiveStream` object.  When the remote side closes or
        aborts the stream, close or abort the corresponding `ReceiveStream`.

## Procedures ##  {#unidirectional-streams-transport-procedures}

### Add SendStream to UnidirectionalStreamsTransport ### {#add-sendstream}

<div algorithm="create a SendStream">

To <dfn export for="SendStream" lt="create|creating">create</dfn> a
{{SendStream}} given a <var>transport</var> and a promise |p|, run the following
steps:

1. Reserve a unidirectional stream |association| in the underlying transport.
1. Queue a task to run the following sub-steps:
  1. If |transport|'s state is `"closed"` or `"failed"`, abort these sub-steps.
  1. Let |stream| be a newly created {{SendStream}} for |association|.
  1. Add |stream| to |transport|'s [=[[OutgoingStreams]]=].
  1. Resolve |p| with |stream|.

</div>

## SendStreamParameters Dictionary ##  {#send-stream-parameters}

The <dfn dictionary>SendStreamParameters</dfn> dictionary includes information
relating to stream configuration.

<pre class="idl">
dictionary SendStreamParameters {
};
</pre>

# `DatagramDuplexStream` Interface #  {#duplex-stream}

A <dfn interface>DatagramDuplexStream</dfn> is a generic duplex stream.

<pre class="idl">
[Exposed=(Window,Worker)]
interface DatagramDuplexStream {
  readonly attribute ReadableStream readable;
  readonly attribute WritableStream writable;
};
</pre>

## Internal slots ## {#datagramduplexstream-internal-slots}

A {{DatagramDuplexStream}} object has the following internal slots.

<table class="data" dfn-for="DatagramDuplexStream">
 <thead>
  <tr>
   <th>Internal Slot
   <th>Description (<em>non-normative</em>)
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><dfn>\[[Readable]]</dfn>
   <td class="non-normative">A {{ReadableStream}} for incoming datagrams.
  </tr>
  <tr>
   <td><dfn>\[[Writable]]</dfn>
   <td class="non-normative">A {{WritableStream}} for outgoing datagrams.
  </tr>
  <tr>
   <td><dfn>\[[IncomingDatagramsQueue]]</dfn>
   <td class="non-normative">A queue of [=pairs=] of an incoming datagram and a timestamp.
  </tr>
  <tr>
   <td><dfn>\[[IncomingDatagramsPullPromise]]</dfn>
   <td class="non-normative">A promise set by [=pullDatagrams=], to wait for an incoming datagram.
  </tr>
  <tr>
   <td><dfn>\[[IncomingDatagramsHighWaterMark]]</dfn>
   <td class="non-normative">An integer representing the [=high water mark=] of the incoming
   datagrams.
  </tr>
  <tr>
   <td><dfn>\[[IncomingDatagramsExpirationDuration]]</dfn>
   <td class="non-normative">A {{double}} value representing the expiration duration for incoming
   datagrams (in milliseconds), or null.
  </tr>
  <tr>
   <td><dfn>\[[OutgoingDatagramsQueue]]</dfn>
   <td class="non-normative">A queue of tuples of an outgoing datagram, a timestamp and a promise
   which is resolved when the datagram is sent or discarded.
  </tr>
  <tr>
   <td><dfn>\[[OutgoingDatagramsHighWaterMark]]</dfn>
   <td class="non-normative">An integer representing the [=high water mark=] of the outgoing
   datagrams.
  </tr>
  <tr>
   <td><dfn>\[[OutgoingDatagramsExpirationDuration]]</dfn>
   <td class="non-normative">A {{double}} value representing the expiration duration for outgoing
   datagrams (in milliseconds), or null.
  </tr>
 </tbody>
</table>

 To <dfn export for="DatagramDuplexStream" lt="create|creating">create</dfn> a
 {{DatagramDuplexStream}} given a
 <dfn export for="DatagramDuplexStream/create"><var>readable</var></dfn>, and
 a <dfn export for="DatagramDuplexStream/create"><var>writable</var></dfn>,
 perform the following steps.

 1. Let |stream| be a [=new=] {{DatagramDuplexStream}}, with:
    : [=[[Readable]]=]
    :: |readable|
    : [=[[Writable]]=]
    :: |writable|
    : [=[[IncomingDatagramsQueue]]=]
    :: an empty queue
    : [=[[IncomingDatagramsPullPromise]]=]
    :: null
    : [=[[IncomingDatagramsHighWaterMark]]=]
    :: an [=implementation-defined=] integer
    : [=[[IncomingDatagramsExpirationDuration]]=]
    :: null
    : [=[[OutgoingDatagramsQueue]]=]
    :: an empty queue
    : [=[[OutgoingDatagramsHighWaterMark]]=]
    :: an [=implementation-defined=] integer
       <div class="note">
        <p>This implementation-defined value should be tuned to ensure decent throughput, without
           jeopardizing the timeliness of transmitted data.</p>
       </div>
    : [=[[OutgoingDatagramsExpirationDuration]]=]
    :: null
 1. Return |stream|.

## Attributes ##  {#datagram-duplex-stream-attributes}

: <dfn for="DatagramDuplexStream" attribute>readable</dfn>
:: The getter steps are:
     1. Return [=this=].`[[Readable]]`.

: <dfn for="DatagramDuplexStream" attribute>writable</dfn>
:: The getter steps are:
     1. Return [=this=].`[[Writable]]`.

## Procedures ## {#datagram-duplex-stream-procedures}

To <dfn>pullDatagrams</dfn>, given a {{WebTransport}} object |transport|, run these steps:
1. Let |datagrams| be |transport|'s [=[[Datagrams]]=].
1. Assert: |datagrams|'s [=[[IncomingDatagramsPullPromise]]=] is null.
1. Let |queue| be |datagrams|'s [=[[IncomingDatagramsQueue]]=].
1. If |queue| is empty, then:
  1. Set |datagrams|'s [=[[IncomingDatagramsPullPromise]]=] to a new promise.
  1. Return |datagrams|'s [=[[IncomingDatagramsPullPromise]]=].
1. Let |bytes| and |timestamp| be the result of [=dequeuing=] |queue|.
1. Let |chunk| be a new {{Uint8Array}} object representing |bytes|.
1. [=ReadableStream/Enqueue=] |chunk| to |transport|'s [=[[Datagrams]]=]' s
   [=DatagramDuplexStream/[[Readable]]=].
1. Return [=a promise resolved with=] undefined.

To <dfn>receiveDatagrams</dfn>, given a {{WebTransport}} object |transport|, run these steps:
1. Let |timestamp| be a timestamp representing now.
1. Let |queue| be |datagrams|'s [=[[IncomingDatagramsQueue]]=].
1. Let |duration| be |datagrams|'s [=[[IncomingDatagramsExpirationDuration]]=].
1. If |duration| is null, then set |duration| to an [=implementation-defined=] value.
1. Let |session| be |transport|'s [=[[Session]]=].
1. While there are [=session/receive a datagram|available incoming datagrams=] on |session|:
  1. Let |datagram| be the result of [=session/receiving a datagram=] with |session|.
  1. Let |timestamp| be a timestamp representing now.
  1. Let |chunk| be a [=pair=] of |datagram| and |timestamp|.
  1. [=Enqueue=] |chunk| to |queue|.
1. Let |toBeRemoved| be the length of |queue| minus |datagrams|'s
   [=[[IncomingDatagramsHighWaterMark]]=].
1. If |toBeRemoved| is positive, repeat [=dequeuing=] |queue| |toBeRemoved| times.
1. While |queue| is not empty:
  1. Let |bytes| and |timestamp| be |queue|'s first element.
  1. If more than |duration| milliseconds have passed since |timestamp|, then [=dequeue=] |queue|.
  1. Otherwise, [=break=] this loop.
1. If |queue| is not empty and |datagrams|'s [=[[IncomingDatagramsPullPromise]]=] is non-null, then:
  1. Let |bytes| and |timestamp| be the result of [=dequeuing=] |queue|.
  1. Let |promise| be |datagrams|'s [=[[IncomingDatagramsPullPromise]]=].
  1. Set |datagrams|'s [=[[IncomingDatagramsPullPromise]]=] to null.
  1. [=Queue a global task=] on the [=network task source=] with |transport|'s
     [=relevant global object=] and a task that runs the following steps:
    1. Let |chunk| be a new {{Uint8Array}} object representing |bytes|.
    1. [=ReadableStream/Enqueue=] |chunk| to |datagrams|'s [=DatagramDuplexStream/[[Readable]]=].
    1. [=Resolve=] |promise| with undefined.

The user agent SHOULD run [=receiveDatagrams=] for any {{WebTransport}} object whose
[=[[State]]=] is `"connected"` as soon as reasonably possible whenever the algorithm can make
progress.

The <dfn>writeDatagrams</dfn> algorithm is given a |transport| as parameter and
|data| as input. It is defined by running the following steps:
1. Let |session| be |transport|'s [=[[Session]]=].
1. Let |timestamp| be a timestamp representing now.
1. If |data| is not a {{Uint8Array}} object, then return [=a promise rejected with=] a {{TypeError}}.
1. Let |promise| be a new promise.
1. Let |bytes| be a copy of bytes which |data| represents.
1. Let |chunk| be a tuple of |bytes|, |timestamp| and |promise|.
1. Let |datagrams| be |transport|'s [=[[Datagrams]]=].
1. Enqueue |chunk| to |datagrams|'s [=[[OutgoingDatagramsQueue]]=].
1. If the length of |datagrams|'s [=[[OutgoingDatagramsQueue]]=] is less than
   |datagrams|'s [=[[OutgoingDatagramsHighWaterMark]]=], then [=resolve=] |promise| with undefined.
1. Return |promise|.

Note: The associated {{WritableStream}} calls [=writeDatagrams=] only when all the promises that
have been returned by [=writeDatagrams=] have been resolved. Hence the timestamp and the expiration
duration work well only when the web developer pays attention to
{{WritableStreamDefaultWriter/ready|WritableStreamDefaultWriter.ready}}.

To <dfn>sendDatagrams</dfn>, given a {{WebTransport}} object |transport|, run these steps:
1. Let |queue| be |datagrams|'s [=[[OutgoingDatagramsQueue]]=].
1. Let |duration| be |datagrams|'s [=[[OutgoingDatagramsExpirationDuration]]=].
1. If |duration| is null, then set |duration| to an [=implementation-defined=] value.
1. While |queue| is not empty:
  1. Let |bytes|, |timestamp| and |promise| be |queue|'s first element.
  1. If more than |duration| milliseconds have passed since |timestamp|, then:
     1. [=Resolve=] |promise| with undefined.
     1. Remove the first element from |queue|.
  1. Otherwise, break this loop.
1. While |queue| is not empty:
  1. Let |bytes|, |timestamp| and |promise| be |queue|'s first element.
  1. If it is not possible to send |bytes| to the network immediately, then break this loop.
  1. [=session/Send a datagram=], with |session| and |bytes|.
  1. [=Resolve=] |promise| with undefined.
  1. Remove the first element from |queue|.

The user agent SHOULD run [=sendDatagrams=] for any {{WebTransport}} object whose
[=[[State]]=] is `"connected"` as soon as reasonably possible whenever the algorithm can make
progress.

# `WebTransport` Interface #  {#web-transport}

`WebTransport` provides an API to the HTTP/3 transport functionality
defined in [[!WEB-TRANSPORT-HTTP3]]. It implements {{UnidirectionalStreamsTransport}}
as well as stats and transport state information.

<pre class="idl">
[Exposed=(Window,Worker)]
interface WebTransport {
  constructor(USVString url, optional WebTransportOptions options = {});

  Promise&lt;WebTransportStats&gt; getStats();
  readonly attribute WebTransportState state;
  readonly attribute Promise&lt;undefined&gt; ready;
  readonly attribute Promise&lt;WebTransportCloseInfo&gt; closed;
  undefined close(optional WebTransportCloseInfo closeInfo = {});
  attribute EventHandler onstatechange;

  readonly attribute unsigned short maxDatagramSize;
  readonly attribute DatagramDuplexStream datagrams;

  Promise&lt;BidirectionalStream&gt; createBidirectionalStream();
  /* a ReadableStream of BidirectionalStream objects */
  readonly attribute ReadableStream incomingBidirectionalStreams;
};

WebTransport includes UnidirectionalStreamsTransport;
</pre>

## Internal slots ## {#webtransport-internal-slots}

A {{WebTransport}} object has the following internal slots.

<table class="data" dfn-for="WebTransport">
 <thead>
  <tr>
   <th>Internal Slot
   <th>Description (<em>non-normative</em>)
  </tr>
 </thead>
 <tbody>
  <tr>
   <td><dfn>\[[OutgoingStreams]]</dfn>
   <td class="non-normative">A sequence of {{SendStream}} objects.
  </tr>
  <tr>
   <td><dfn>\[[ReceivedStreams]]</dfn>
   <td class="non-normative">A {{ReadableStream}} consisting of {{ReceiveStream}} objects.
  </tr>
  <tr>
   <td><dfn>\[[ReceivedBidirectionalStreams]]</dfn>
   <td class="non-normative">A {{ReadableStream}} consisting of {{BidirectionalStream}} objects.
  </tr>
  <tr>
   <td><dfn>\[[State]]</dfn>
   <td class="non-normative">A {{WebTransportState}}.
  </tr>
  <tr>
   <td><dfn>\[[Ready]]</dfn>
   <td class="non-normative">A promise fulfilled when the associated [=WebTransport session=]
   gets [=session/established=], or rejected if the [=session/establish|establishment process=]
   failed.
  </tr>
  <tr>
   <td><dfn>\[[Closed]]</dfn>
   <td class="non-normative">A promise fulfilled when the associated {{WebTransport}} object is
   closed gracefully, or rejected when it is closed abruptly or failed on initialization.
  </tr>
  <tr>
   <td><dfn>\[[Datagrams]]</dfn>
   <td class="non-normative">A {{DatagramDuplexStream}}.
  </tr>
  <tr>
  <tr>
   <td><dfn>\[[Session]]</dfn>
   <td class="non-normative">A [=WebTransport session=] for this {{WebTransport}} object, or null.
  </tr>
</table>

## Constructor ##  {#webtransport-constructor}

When the {{WebTransport/constructor()}} constructor is invoked, the user
agent MUST run the following steps:
1. Let |parsedURL| be the [=URL record=] resulting from [=URL parser|parsing=]
   {{WebTransport/constructor(url, options)/url}}.
1. If |parsedURL| is a failure, [=throw=] a {{SyntaxError}} exception.
1. If |parsedURL| [=scheme=] is not `https`, [=throw=] a {{SyntaxError}} exception.
1. If |parsedURL| [=fragment=] is not null, [=throw=] a {{SyntaxError}} exception.
1. Let |allowPooling| be {{WebTransport/constructor(url, options)/options}}'s
   {{WebTransportOptions/allowPooling}} if it exists, and false otherwise.
1. Let |dedicated| be the negation of |allowPooling|.
1. Let |serverCertificateFingerprints| be {{WebTransport/constructor(url, options)/options}}'s
   {{WebTransportOptions/serverCertificateFingerprints}} if it exists, and null otherwise.
1. If |dedicated| is false and |serverCertificateFingerprints| is non-null, then [=throw=] a
   {{TypeError}}.
1. Let |incomingDatagrams| be a [=new=] {{ReadableStream}}.
1. Let |outgoingDatagrams| be a [=new=] {{WritableStream}}.
1. Let |datagrams| be the result of [=DatagramDuplexStream/creating=] a
   {{DatagramDuplexStream}}, its [=DatagramDuplexStream/create/readable=] set to
   |incomingDatagrams| and its [=DatagramDuplexStream/create/writable=] set to |outgoingDatagrams|.
1. Let |transport| be a newly constructed {{WebTransport}} object, with:
    : [=[[OutgoingStreams]]=]
    :: empty
    : [=[[ReceivedStreams]]=]
    :: a new {{ReadableStream}}
    : [=[[ReceivedBidirectionalStreams]]=]
    :: a new {{ReadableStream}}
    : [=[[State]]=]
    :: `"connecting"`
    : [=[[Ready]]=]
    :: a new promise
    : [=[[Closed]]=]
    :: a new promise
    : [=[[Datagrams]]=]
    :: |datagrams|
    : [=[[Session]]=]
    :: null
1. Let |pullAlgorithm| be an action that runs [=pullDatagrams=] with |transport|.
1. Let |writeAlgorithm| be an action that runs [=writeDatagrams=] with |transport|.
1. [=ReadableStream/Set up=] |incomingDatagrams| with [=ReadableStream/set up/pullAlgorithm=]
   set to |pullAlgorithm|, and [=ReadableStream/set up/highWaterMark=] set to 0.
1. [=WritableStream/Set up=] |outgoingDatagrams| with [=WritableStream/set up/writeAlgorithm=]
   set to |writeAlgorithm|.
1. Let |promise| be the result of [=initialize WebTransport over HTTP|initializing WebTransport
   over HTTP=], with |transport|, |parsedURL| and |dedicated|.
1. [=Upon fulfillment=] of |promise|, run these steps:
   1. If |transport|'s [=[[State]]=] is not `"connecting"`, then abort these steps.
   1. Set |transport|'s [=[[State]]=] to `"connected"`.
   1. Resolve |transport|'s [=[[Ready]]=] with {{undefined}}.
1. [=Upon rejection=] of |promise| with |error|, run these steps:
   1. Set |transport|'s [=[[State]]=] to `"failed"`.
   1. Reject |transport|'s [=[[Ready]]=] with |error|.
   1. Reject |transport|'s [=[[Closed]]=] with |error|.
1. Return |transport|.

<div algorithm="initialize WebTransport over HTTP">
To <dfn>initialize WebTransport over HTTP</dfn>, given a {{WebTransport}} object
<var>transport</var>, a [=URL record=] |url|, and a boolean |dedicated|, run these steps.

1. Let |promise| be a new promise.
1. Let |networkPartitionKey| be the result of [=determining the network partition key=] with
   |transport|'s [=relevant settings object=].
1. Return |promise| and run the following steps [=in parallel=].
1. Let |connection| be the result of [=obtain a connection|obtaining a connection=] with
   |networkPartitionKey|, |url|'s [=url/origin=], false, [=obtain a connection/http3Only=] set to
   true, and [=obtain a connection/dedicated=] set to |dedicated|.
1. If |connection| is failure, then reject |promise| with a {{TypeError}} and abort these steps.
1. Wait for |connection| to receive the first SETTINGS frame, and let |settings| be a dictionary that
   represents the SETTINGS frame.
1. If |settings| doesn't contain SETTINGS_ENABLE_WEBTRANPORT with a value of 1, or it doesn't
   contain H3_DATAGRAM with a value of 1, then reject |promise| with a {{TypeError}} and abort
   these steps.
1. [=session/Establish=] a [=WebTransport session=] on |connection|.
1. If the previous step fails, then reject |promise| with a {{TypeError}} and abort these steps.
1. Set |transport|'s [=[[Session]]=] to the established [=WebTransport session=].
1. Resolve |promise| with {{undefined}}.

</div>

## Attributes ##  {#webtransport-attributes}

: <dfn for="WebTransport" attribute>state</dfn>
:: The current state of the transport. On getting, it MUST return [=this=]'s [=[[State]]=].
: <dfn for="WebTransport" attribute>ready</dfn>
:: On getting, it MUST return [=this=]'s [=[[Ready]]=].
: <dfn for="WebTransport" attribute>closed</dfn>
:: On getting, it MUST return [=this=]'s [=[[Closed]]=].
:: This promise MUST be [=resolved=] when the transport is closed; an
   implementation SHOULD include error information in the `reason` and
   `errorCode` fields of {{WebTransportCloseInfo}}.
: <dfn for="WebTransport" attribute>onstatechange</dfn>
:: This event handler, of event handler event type `statechange`, MUST be fired
   any time the [=[[State]]=] changes, unless the state changes
   due to calling {{WebTransport/close}}.
: <dfn for="WebTransport" attribute>maxDatagramSize</dfn>
:: The maximum size data that may be passed to
   {{DatagramTransport/datagrams}}' {{DatagramDuplexStream/writable}}.
: <dfn for="WebTransport" attribute>datagrams</dfn>
:: A single duplex stream for sending and receiving datagrams over this session.
   The getter steps for the `datagrams` attribute SHALL be:
     1. Return [=this=]'s [=[[Datagrams]]=].
: <dfn for="WebTransport" attribute>incomingBidirectionalStreams</dfn>
:: Returns a {{ReadableStream}} of {{BidirectionalStream}}s that have been
   received from the remote host.

   The getter steps for the `incomingBidirectionalStreams` attribute SHALL be:

     1. Return [=[[ReceivedBidirectionalStreams]]=].
     1. For each bidirectional stream received, create a corresponding
        {{BidirectionalStream}} and insert it into [=[[ReceivedBidirectionalStreams]]=].
        As data is received over the bidirectional stream, insert that data into the
        corresponding {{BidirectionalStream}}.  When the remote side closes or aborts
        the stream, close or abort the corresponding {{BidirectionalStream}}.

## Methods ##  {#webtransport-methods}

: <dfn for="WebTransport" method>close(closeInfo)</dfn>
:: Terminates the [=WebTransport session=] associated with the WebTransport object.

   When close is called, the user agent MUST run the following steps:
     1. Let |transport| be [=this=].
     1. If |transport|'s [=[[State]]=] is `"closed"` or `"failed"`,
        then abort these steps.
     1. Set |transport|'s [=[[State]]=] to `"closed"`.
     1. Let |session| be |transport|'s [=[[Session]]=].
     1. [=session/Terminate=] |session| with |closeInfo|.{{WebTransportCloseInfo/errorCode}}.

: <dfn for="WebTransport" method>getStats()</dfn>
:: Gathers stats for this {{WebTransport}}'s HTTP/3
   connection and reports the result asynchronously.</p>

   When close is called, the user agent MUST run the following steps:
     1. Let |transport| be the WebTransport on which `getStats` is invoked.
     1. Let |p| be a new promise.
     1. If the URL scheme associated with |transport| is not `https`,
        [=reject=] |p| with {{NotSupportedError}} and return |p|.
     1. Return |p| and continue the following steps [=in parallel=].
         1. Gather the stats from the underlying QUIC connection.
         1. Once stats have been gathered, resolve |p| with the
            {{WebTransportStats}} object, representing the gathered stats.

: <dfn for="WebTransport" method>createBidirectionalStream()</dfn>
:: Creates a {{BidirectionalStream}} object for an outgoing bidirectional
   stream.  Note that the mere creation of a stream is not immediately visible to the peer until
   it is used to send data.

   When `createBidirectionalStream` is called, the user agent MUST run the
   following steps:

   1. Let |transport| be [=this=].
   1. If |transport|'s {{WebTransport/state}} is `"closed"` or `"failed"`,
      immediately return a new [=rejected=] promise with a newly created
      {{InvalidStateError}} and abort these steps.
   1. Let |p| be a new promise.
   1. Return |p| and continue the remaining steps [=in parallel=].
   1. [=WebTransport/create a BidirectionalStream=] with |transport|
      and |p| when all of the following conditions are met:
       1. The |transport|'s {{WebTransport/state}} is `"connected"`.
       1. Stream creation flow control is not being violated by exceeding the
          max stream limit set by the remote endpoint, as specified in
          [[!QUIC]].
       1. |p| has not been [=settled=].
   1. Queue a task to [=reject=] |p| with a newly created {{InvalidStateError}}
      when all of the following conditions are met:
       1. The |transport|'s state is `"closed"` or `"failed"`.
       1. |p| has not been [=settled=].

<div algorithm="create a BidirectionalStream">

 To <dfn for="WebTransport">create a {{BidirectionalStream}}</dfn>
 given a <var>transport</var> and a promise |p|, run the following steps:

1. Reserve a bidirectional stream |association| in the underlying transport.
1. Queue a task to run the following sub-steps:
  1. If |transport|'s state is `"closed"` or `"failed"`, abort these sub-steps.
  1. Let |stream| be a newly created {{BidirectionalStream}} object for |association|.
  1. Add |stream| to |transport|'s [=[[ReceivedBidirectionalStreams]]=].
  1. Add |stream| to |transport|'s [=[[OutgoingStreams]]=].
  1. Resolve |p| with |stream|.

</div>

## Configuration ##  {#web-transport-configuration}

<pre class="idl">
dictionary WebTransportOptions {
  boolean allowPooling;
  sequence&lt;RTCDtlsFingerprint&gt; serverCertificateFingerprints;
};
</pre>

<dfn dictionary>WebTransportOptions</dfn> is a dictionary of parameters
that determine how WebTransport connection is established and used.

: <dfn for="WebTransportOptions" dict-member>allowPooling</dfn>
:: When set to true, the WebTransport connection can be pooled, that is, the network connection for
   the WebTransport session can be shared with other HTTP/3 sessions.

: <dfn for="WebTransportOptions" dict-member>serverCertificateFingerprints</dfn>
:: This option is only supported for transports using dedicated connections.
   For transport protocols that do not support this feature, having this
   field non-empty SHALL result in a {{NotSupportedError}} exception being thrown.
:: If supported and non-empty, the user agent SHALL deem a server certificate
   trusted if and only if it can successfully [=verify a certificate
   fingerprint=] against {{WebTransportOptions/serverCertificateFingerprints}}
   and satisfies [=custom certificate requirements=].  The user agent SHALL
   ignore any fingerprint that uses an unknown {{RTCDtlsFingerprint/algorithm}}
   or has a malformed {{RTCDtlsFingerprint/value}}.  If empty, the user agent
   SHALL use certificate verification procedures it would use for normal
   [=fetch=] operations.
:: This cannot be used with {{WebTransportOptions/allowPooling}}.

<div algorithm="compute a certificate fingerprint">
To <dfn>compute a certificate fingerprint</dfn>, do the following:
1. Let |cert| be the input certificate, represented as a DER encoding of
   Certificate message defined in [[!RFC5280]].
1. Compute the SHA-256 hash of |cert|.  Format it as `fingerprint` BNF
   rule described in Section 5 of [[!RFC8122]].

</div>

<div algorithm="verify a certificate fingerprint">
To <dfn>verify a certificate fingerprint</dfn>, do the following:
1. Let |fingerprints| be the input array of fingerprints.
1. Let |referenceFingerprint| be the [=compute a certificate fingerprint|computed
   fingerprint=] of the input certificate.
1. For every fingerprint |fingerprint| in |fingerprints|:
   1. If {{RTCDtlsFingerprint/algorithm}} of |fingerprint| is equal to "sha-256",
      and {{RTCDtlsFingerprint/value}} of |fingerprint| is equal to
      |referenceFingerprint|, the certificate is valid.  Return true.
1. Return false.

</div>

The <dfn>custom certificate requirements</dfn> are as follows: the certificate
MUST be an X.509v3 certificate as defined in [[!RFC5280]], the current time
MUST be within the validity period of the certificate as defined in Section
4.1.2.5 of [[!RFC5280]] and the total length of the validity period MUST NOT
exceed two weeks.

Issue: Reconsider the time period above.  We want it to be sufficiently large
that applications using this for ephemeral certificates can do so without
having to fight the clock skew, but small enough to discourage long-term use
without key rotation.

## `WebTransportState` Enum ##  {#web-transport-state-enum}

<dfn enum>WebTransportState</dfn> indicates the state of the transport.

<pre class="idl">
enum WebTransportState {
  "connecting",
  "connected",
  "closed",
  "failed"
};
</pre>

: <dfn for="WebTransportState" enum-value>"connecting"</dfn>
:: The transport is in the process of negotiating a secure connection. Once a
   secure connection is negotiated, incoming data can flow through.
: <dfn for="WebTransportState" enum-value>"connected"</dfn>
:: The transport has completed negotiation of a secure connection. Outgoing
   data and media can now flow through.
: <dfn for="WebTransportState" enum-value>"closed"</dfn>
:: The transport has been closed intentionally via a call to
   {{WebTransport/close()}} or receipt of a closing message from the remote
   side.  When the {{WebTransport}}'s [=[[State]]=]
   transitions to `closed` the user agent MUST run the following steps:

   1. Let |transport| be the {{WebTransport}}.
   1. Close the {{ReadableStream}} in |transport|'s [=[[ReceivedStreams]]=].
   1. Close the {{ReadableStream}} in |transport|'s
      [=[[ReceivedBidirectionalStreams]]=].
   1. For each {{SendStream}} in |transport|'s [=[[OutgoingStreams]]=]
      run the following:

     1. Let |stream| be the {{SendStream}}.
     1. Remove the |stream| from the |transport|'s [=[[OutgoingStreams]]=].

: <dfn for="WebTransportState" enum-value>"failed"</dfn>
:: The transport has been closed as the result of an error (such as receipt of
   an error alert). When the WebTransport's [=[[State]]=] transitions to
   `failed` the user agent MUST run the following steps:

   1. Close the {{ReadableStream}} in |transport|'s [=[[ReceivedStreams]]=].
   1. Close the {{ReadableStream}} in |transport|'s
      [=[[ReceivedBidirectionalStreams]]=].
   1. For each {{SendStream}} in |transport|'s [=[[OutgoingStreams]]=]
      run the following:

     1. Remove the |stream| from the |transport|'s [=[[OutgoingStreams]]=].

## `WebTransportCloseInfo` Dictionary ##  {#web-transport-close-info}

The <dfn dictionary>WebTransportCloseInfo</dfn> dictionary includes information
relating to the error code for closing a {{WebTransport}}. This
information is used to set the error code and reason for a CONNECTION_CLOSE
frame.

<pre class="idl">
dictionary WebTransportCloseInfo {
  unsigned long long errorCode = 0;
  DOMString reason = "";
};
</pre>

The dictionary SHALL have the following attributes:

: <dfn for="WebTransportCloseInfo" dict-member>errorCode</dfn>
:: The error code communicated to the peer.
: <dfn for="WebTransportCloseInfo" dict-member>reason</dfn>
:: The reason for closing the {{WebTransport}}.

## `WebTransportStats` Dictionary ##  {#web-transport-stats}

The <dfn dictionary>WebTransportStats</dfn> dictionary includes information
on HTTP/3 connection stats.

Issue: Now that quic-transport has been removed, this section needs to be
revised. Some of those are safe to expose for HTTP/2 and HTTP/3 connections
(like min-RTT), while most would either result in information disclosure
or are impossible to define for pooled connections.

<pre class="idl">
dictionary WebTransportStats {
  DOMHighResTimeStamp timestamp;
  unsigned long long bytesSent;
  unsigned long long packetsSent;
  unsigned long numOutgoingStreamsCreated;
  unsigned long numIncomingStreamsCreated;
  unsigned long long bytesReceived;
  unsigned long long packetsReceived;
  DOMHighResTimeStamp minRtt;
  unsigned long numReceivedDatagramsDropped;
};
</pre>

The dictionary SHALL have the following attributes:

: <dfn for="WebTransportStats" dict-member>timestamp</dfn>
:: The `timestamp` for when the stats are gathered, relative to the
   UNIX epoch (Jan 1, 1970, UTC).
: <dfn for="WebTransportStats" dict-member>bytesSent</dfn>
:: The number of bytes sent on the QUIC connection, including retransmissions.
   Does not include UDP or any other outer framing.
: <dfn for="WebTransportStats" dict-member>packetsSent</dfn>
:: The number of packets sent on the QUIC connection, including retransmissions.
: <dfn for="WebTransportStats" dict-member>numOutgoingStreamsCreated</dfn>
:: The number of outgoing QUIC streams created on the QUIC connection.
: <dfn for="WebTransportStats" dict-member>numIncomingStreamsCreated</dfn>
:: The number of incoming QUIC streams created on the QUIC connection.
: <dfn for="WebTransportStats" dict-member>bytesReceived</dfn>
:: The number of total bytes received on the QUIC connection, including
   duplicate data for streams. Does not include UDP or any other outer framing.
: <dfn for="WebTransportStats" dict-member>packetsReceived</dfn>
:: The number of total packets received on the QUIC connection, including
   packets that were not processable.
: <dfn for="WebTransportStats" dict-member>minRtt</dfn>
:: The minimum RTT observed on the entire connection.
: <dfn for="WebTransportStats" dict-member>numReceivedDatagramsDropped</dfn>
:: The number of datagrams that were dropped, due to too many datagrams buffered
   between calls to {{DatagramTransport/datagrams}}' {{DatagramDuplexStream/readable}}.

# Interface `SendStream` #  {#send-stream}

A <dfn interface>SendStream</dfn> is a {{WritableStream}} of {{Uint8Array}}
that can be written to, to transmit data to the remote host.

<pre class="idl">
[ Exposed=(Window,Worker) ]
interface SendStream : WritableStream /* of Uint8Array */ {
  readonly attribute Promise&lt;StreamAbortInfo&gt; writingAborted;
  undefined abortWriting(optional StreamAbortInfo abortInfo = {});
};
</pre>

## Overview ##  {#outgoing-stream-overview}

The {{SendStream}} will be initialized by running the {{WritableStream}}
initialization steps.

## Attributes ##  {#outgoing-stream-attributes}

: <dfn attribute for="SendStream">writingAborted</dfn>
:: The `writingAborted` attribute represents a promise that is [=fulfilled=]
    when the a message from the remote side aborting the stream is received.
    For QUIC, that message is a STOP_SENDING frame. When the stream receives
    this mesage, the user agent MUST run the following:
      1. Let |stream| be the {{SendStream}} object.
      1. Let |transport| be the {{WebTransport}}, which the |stream| was created
         from.
      1. Remove the stream from the |transport|'s [=[[OutgoingStreams]]=].
      1. [=Resolve=] the promise with the resulting {{StreamAbortInfo}} with
         the {{StreamAbortInfo/errorCode}} set to the value from the aborting
         message from the remote side.

## Methods ##  {#outgoing-stream-methods}

: <dfn method for="SendStream">abortWriting()</dfn>
:: A hard shutdown of the {{SendStream}}. It may be called regardless of
   whether the {{SendStream}} was created by the local or remote peer. When
   the `abortWriting` method is called, the user agent MUST run the following
   steps:
     1. Let |stream| be the {{SendStream}} object which is about to abort
        writing.
     1. Let |transport| be the {{WebTransport}}, which the |stream| was created
        from.
     1. Remove the stream from the transport's [=[[OutgoingStreams]]=].
     1. Let |abortInfo| be the first argument.
     1. Start the closing procedure by sending a RST_STREAM frame with its
        error code set to the value of |abortInfo.errorCode|.

## `StreamAbortInfo` Dictionary ##  {#stream-abort-info}

The <dfn dictionary>StreamAbortInfo</dfn> dictionary includes information
relating to the error code for aborting an incoming or outgoing stream (
in either a RST_STREAM frame or a STOP_SENDING frame).

<pre class="idl">
dictionary StreamAbortInfo {
  [EnforceRange] octet errorCode = 0;
};
</pre>

The dictionary SHALL have the following fields:

: <dfn for="StreamAbortInfo" dict-member>errorCode</dfn>
:: The error code. The default value of 0 means "CLOSING."

# Interface `ReceiveStream` #  {#receive-stream}

A <dfn interface>ReceiveStream</dfn> is a {{ReadableStream}} of {{Uint8Array}}
that can be read from, to consume data received from the remote host.

<pre class="idl">
[ Exposed=(Window,Worker) ]
interface ReceiveStream : ReadableStream /* of Uint8Array */ {
  readonly attribute Promise&lt;StreamAbortInfo&gt; readingAborted;
  undefined abortReading(optional StreamAbortInfo abortInfo = {});
};
</pre>

## Overview ##  {#incoming-stream-overview}

The {{ReceiveStream}} will be initialized by running the {{ReadableStream}}
initialization steps.

## Attributes ##  {#incoming-stream-attributes}

: <dfn attribute for="ReceiveStream">readingAborted</dfn>
:: The `readingAborted` attribute represents a promise that is [=fulfilled=]
    when the a message from the remote side aborting the stream is received.
    For QUIC, that message is a RST_STREAM frame. When the stream receives
    this mesage, the user agent MUST run the following:
      1. Let |stream| be the {{ReceiveStream}} object for which the abort
         message was received.
      1. Let |transport| be the {{WebTransport}}, which the |stream| was created
         from.
      1. [=Resolve=] the promise with the resulting {{StreamAbortInfo}} with
         the {{StreamAbortInfo/errorCode}} set to the value from the aborting
         message from the remote side.

## Methods ##  {#incoming-stream-methods}

: <dfn method for="ReceiveStream">abortReading()</dfn>
:: A hard shutdown of the {{ReceiveStream}}. It may be called regardless of
   whether the {{ReceiveStream}} was created by the local or remote peer. When
   the `abortWriting` method is called, the user agent MUST run the following
   steps:
     1. Let |stream| be the {{ReceiveStream}} object which is about to abort
        reading.
     1. Let |transport| be the {{WebTransport}}, which the |stream| was created
        from.
     1. Let |abortInfo| be the first argument.
     1. Start the closing procedure by sending a message to the remote side
        indicating that the stream has been aborted (using a
        STOP_SENDING frame) with its error code set to the value of
        |abortInfo.errorCode|.

# Interface `BidirectionalStream` #  {#bidirectional-stream}

<pre class="idl">
[ Exposed=(Window,Worker) ]
interface BidirectionalStream {
  readonly attribute ReceiveStream readable;
  readonly attribute SendStream writable;
};
</pre>

The {{BidirectionalStream}} will initialize with the following:

1. Let |duplexStream| be the {{BidirectionalStream}}.
1. Let |duplexStream| have a <dfn attribute for="BidirectionalStream">\[[Readable]]</dfn>
   internal slot initialized to a new {{ReceiveStream}}.
1. Let |duplexStream| have a <dfn attribute for="BidirectionalStream">\[[Writable]]</dfn>
   internal slot initialized to a new {{SendStream}}.

# Protocol Mappings # {#protocol-mapping}

*This section is non-normative.*

This section describes the [[QUIC]] protocol behavior of methods defined
in this specification, utilizing [[WEB-TRANSPORT-HTTP3]].

  <table class="data">
    <colgroup class="header"><col></colgroup>
    <colgroup><col></colgroup>
    <thead>
      <tr>
        <th>Method</th>
        <th>QUIC Protocol Action</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>{{ReceiveStream/abortReading}}</td>
        <td>send STOP_SENDING with code</td>
      </tr>
      <tr>
        <td>{{SendStream/abortWriting}}</td>
        <td>send RESET_STREAM with code</td>
      </tr>
      <tr>
        <td>{{BidirectionalStream/writable}}.abort()</td>
        <td>send RESET_STREAM</td>
      </tr>
      <tr>
        <td>{{BidirectionalStream/writable}}.close()</td>
        <td>send STREAM_FINAL</td>
      </tr>
      <tr>
        <td>{{BidirectionalStream/writable}}.getWriter().write()</td>
        <td>send STREAM</td>
      </tr>
      <tr>
        <td>{{BidirectionalStream/writable}}.getWriter().close()</td>
        <td>send STREAM_FINAL</td>
      </tr>
      <tr>
        <td>{{BidirectionalStream/writable}}.getWriter().abort()</td>
        <td>send RESET_STREAM</td>
      </tr>
      <tr>
        <td>{{BidirectionalStream/readable}}.cancel()</td>
        <td>send STOP_SENDING</td>
      </tr>
      <tr>
        <td>{{BidirectionalStream/readable}}.getReader().read()</td>
        <td>receive STREAM or STREAM_FINAL</td>
      </tr>
      <tr>
        <td>{{BidirectionalStream/readable}}.getReader().cancel()</td>
        <td>send STOP_SENDING</td>
      </tr>
    </tbody>
  </table>

# Privacy and Security Considerations #  {#privacy-security}

This section is non-normative; it specifies no new behaviour, but instead
summarizes information already present in other parts of the specification.

## Confidentiality of Communications ##  {#confidentiality}

The fact that communication is taking place cannot be hidden from adversaries
that can observe the network, so this has to be regarded as public information.

All of the transport protocols described in this document use either TLS
[[RFC8446]] or a semantically equivalent protocol, thus providing all of the
security properties of TLS, including confidentiality and integrity of the
traffic. Http3Transport uses the same certificate
verification mechanism as outbound HTTP requests, thus relying on the same
public key infrastructure for authentication of the remote server. In
WebTransport, certificate verification errors are fatal; no interstitial
allowing bypassing certificate validation is available.

## State Persistence ##  {#state-persistence}

WebTransport by itself does not create any new unique identifiers or new ways
to persistently store state, nor does it automatically expose any of the
existing persistent state to the server. For instance, none of the transports
defined in this document automatically send cookies, support HTTP
authentication or caching invalidation mechanisms. Since they use TLS, they may
support TLS session tickets, which could be used by the server (though not by
passive network observers) to correlate different connections from the same
client. This is not specific to WebTransport by itself, but rather an inherent
property of all TLS-based protocols; thus, this is out-of-scope for this
specification.

## Protocol Security ##  {#protocol-security}

WebTransport imposes a set of requirements as described in
[[!WEB-TRANSPORT-OVERVIEW]], including: 

1. Ensuring that the remote server is aware that the
   connection in question originates from a Web application; this is required
   to prevent cross-protocol attacks. [[WEB-TRANSPORT-HTTP3]] uses ALPN
   [[RFC7301]] for this purpose.
1. Allowing the server to filter connections based on the
   origin of the resource originating the transport session.

Protocol security considerations related are described in the
*Security Considerations* sections of [[!WEB-TRANSPORT-HTTP3]].

Networking APIs can be commonly used to scan the local network for available
hosts, and thus be used for fingerprinting and other forms of attacks.
WebTransport follows the [WebSocket
approach](https://html.spec.whatwg.org/multipage/web-sockets.html#feedback-from-the-protocol)
to this problem: the specific connection error is not returned until an
endpoint is verified to be a WebTransport endpoint; thus, the Web application
cannot distinguish between a non-existing endpoint and the endpoint that is not
willing to accept connections from the Web.

# Examples #  {#examples}

## Sending a buffer of datagrams ##  {#example-datagrams}

*This section is non-normative.*

Sending a buffer of datagrams can be achieved by using the
{{DatagramTransport/datagrams}}' {{DatagramDuplexStream/writable}} attribute. In the
following example datagrams are only sent if the {{DatagramTransport}} is ready to send.

<pre class="example" highlight="js">
async function sendDatagrams(url, datagrams) {
  const wt = new WebTransport(url);
  const writer = wt.datagrams.writable.getWriter();
  for (const datagram of datagrams) {
    await writer.ready;
    writer.write(datagram).catch(() => {});
  }
}
</pre>

## Sending datagrams at a fixed rate ##  {#example-fixed-rate}

*This section is non-normative.*

Sending datagrams at a fixed rate regardless if the transport is ready to send
can be achieved by simply using {{DatagramTransport/datagrams}}'
{{DatagramDuplexStream/writable}} and not using the `ready` attribute. More complex
scenarios can utilize the `ready` attribute.

<pre class="example" highlight="js">
// Sends datagrams every 100 ms.
async function sendFixedRate(url, createDatagram, ms = 100) {
  const wt = new WebTransport(url);
  await wt.ready;
  const writer = wt.datagrams.writable.getWriter();
  const datagram = createDatagram();
  setInterval(() => writer.write(datagram).catch(() => {}), ms);
}
</pre>

## Receiving datagrams ##  {#example-receiving-datagrams}

*This section is non-normative.*

Datagrams can be received by reading from the
transport.{{DatagramTransport/datagrams}}.{{DatagramTransport/datagrams}}.{{DatagramDuplexStream/readable}}
attribute. Null values may indicate that packets are not being processed quickly
enough.

<pre class="example" highlight="js">
async function receiveDatagrams(url) {
  const wt = new WebTransport(url);
  for await (const datagram of wt.datagrams.readable) {
    // Process the datagram
  }
}
</pre>

## Sending a stream ##  {#example-sending-stream}

*This section is non-normative.*

Sending data as a one-way stream can be achieved by using the
{{UnidirectionalStreamsTransport/createUnidirectionalStream}} function and the
resulting stream's writer.

<pre class="example" highlight="js">
async function sendData(url, data) {
  const wt = new WebTransport(url);
  const writable = await wt.createUnidirectionalStream();
  const writer = writable.getWriter();
  await writer.write(data);
  await writer.close();
}
</pre>

Encoding can also be done through pipes from a {{ReadableStream}}, for example using
{{TextEncoderStream}}.

<pre class="example" highlight="js">
async function sendText(url, readableStreamOfTextData) {
  const wt = new WebTransport(url);
  const writable = await wt.createUnidirectionalStream();
  await readableStreamOfTextData
    .pipeThrough(new TextEncoderStream("utf-8"))
    .pipeTo(writable);
}
</pre>

## Receiving incoming streams ##  {#example-receiving-incoming-streams}

*This section is non-normative.*

Reading incoming streams can be achieved by iterating over the
{{UnidirectionalStreamsTransport/incomingUnidirectionalStreams}} attribute,
and then consuming each {{ReceiveStream}} by iterating over its chunks.

<pre class="example" highlight="js">
async function receiveData(url, processTheData) {
  const wt = new WebTransport(url);
  for await (const readable of wt.incomingUnidirectionalStreams) {
    // consume streams individually, reporting per-stream errors
    ((async () => {
      try {
        for await (const chunk of readable.getReader()) {
          processTheData(chunk);
        }
      } catch (e) {
        console.error(e);
      }
    })());
  }
}
</pre>

Decoding can also be done through pipes to new WritableStreams, for example using
{{TextDecoderStream}}. This example assumes text output should not be
interleaved, and therefore only reads one stream at a time.

<pre class="example" highlight="js">
async function receiveText(url, createWritableStreamForTextData) {
  const wt = new WebTransport(url);
  for await (const readable of wt.incomingUnidirectionalStreams) {
    // consume sequentially to not interleave output, reporting per-stream errors
    try {
      await readable
       .pipeThrough(new TextDecoderStream("utf-8"))
       .pipeTo(createWritableStreamForTextData());
    } catch (e) {
      console.error(e);
    }
  }
}
</pre>

## Complete example ##  {#example-complete}

*This section is non-normative.*

This example illustrates use of the closed and ready promises, opening
of uni-directional and bi-directional streams by either the client or
the server, and sending and receiving datagrams.

<pre class="example" highlight="js">
// Adds an entry to the event log on the page, optionally applying a specified
// CSS class.

let wt, streamNumber, datagramWriter;

connect.onclick = async () => {
  try {
    const url = document.getElementById('url').value;

    wt = new WebTransport(url);
    addToEventLog('Initiating connection...');
    await wt.ready;
    addToEventLog('Connection ready.');

    wt.closed
      .then(() => addToEventLog('Connection closed normally.'))
      .catch(() => addToEventLog('Connection closed abruptly.', 'error'));

    streamNumber = 1;
    datagramWriter = wt.datagrams.writable.getWriter();

    readDatagrams();
    acceptUnidirectionalStreams();
    document.forms.sending.elements.send.disabled = false;
    document.getElementById('connect').disabled = true;
  } catch (e) {
    addToEventLog(&#96;Connection failed. ${e}&#96;, 'error');
  }
}

sendData.onclick = async () => {
  const form = document.forms.sending.elements;
  const rawData = sending.data.value;
  const data = new TextEncoder('utf-8').encode(rawData);
  try {
    switch (form.sendtype.value) {
      case 'datagram': {
        await datagramWriter.write(data);
        addToEventLog(&#96;Sent datagram: ${rawData}&#96;);
        break;
      }
      case 'unidi': {
        const writable = await wt.createUnidirectionalStream();
        const writer = writable.getWriter();
        await writer.write(data);
        await writer.close();
        addToEventLog(&#96;Sent a unidirectional stream with data: ${rawData}&#96;);
        break;
      }
      case 'bidi': {
        const duplexStream = await wt.createBidirectionalStream();
        const n = streamNumber++;
        readFromIncomingStream(duplexStream.readable, n);

        const writer = duplexStream.writable.getWriter();
        await writer.write(data);
        await writer.close();
        addToEventLog(&#96;Sent bidirectional stream #${n} with data: ${rawData}&#96;);
        break;
      }
    }
  } catch (e) {
    addToEventLog(&#96;Error while sending data: ${e}&#96;, 'error');
  }
}

// Reads datagrams into the event log until EOF is reached.
async function readDatagrams() {
  try {
    const decoder = new TextDecoderStream('utf-8');

    for await (const data of wt.datagrams.readable.pipeThrough(decoder)) {
      addToEventLog(&#96;Datagram received: ${data}&#96;);
    }
    addToEventLog('Done reading datagrams!');
  } catch (e) {
    addToEventLog(&#96;Error while reading datagrams: ${e}&#96;, 'error');
  }
}

async function acceptUnidirectionalStreams() {
  try {
    for await (const readable of wt.incomingUnidirectionalStreams) {
      const number = streamNumber++;
      addToEventLog(&#96;New incoming unidirectional stream #${number}&#96;);
      readFromIncomingStream(readable, number);
    }
    addToEventLog('Done accepting unidirectional streams!');
  } catch (e) {
    addToEventLog(&#96;Error while accepting streams ${e}&#96;, 'error');
  }
}

async function readFromIncomingStream(readable, number) {
  try {
    const decoder = new TextDecoderStream('utf-8');
    for await (const chunk of readable.pipeThrough(decoder)) {
      addToEventLog(&#96;Received data on stream #${number}: ${chunk}&#96;);
    }
    addToEventLog(&#96;Stream #${number} closed&#96;);
  } catch (e) {
    addToEventLog(&#96;Error while reading from stream #${number"}: ${e}&#96;, 'error');
    addToEventLog(&#96;    ${e.message}&#96;);
  }
}

function addToEventLog(text, severity = 'info') {
  const log = document.getElementById('event-log');
  const previous = log.lastElementChild;
  const entry = document.createElement('li');
  entry.innerText = text;
  entry.className = &#96;log-${severity}&#96;;
  log.appendChild(entry);

  // If the previous entry in the log was visible, scroll to the new element.
  if (previous &&
      previous.getBoundingClientRect().top < log.getBoundingClientRect().bottom) {
    entry.scrollIntoView();
  }
}
</pre>

# Acknowledgements #  {#acknowledgements}
The editors wish to thank the Working Group chairs and Team Contact, Jan-Ivar Bruaroey, Will Law
and Yves Lafon, for their support.

The {{WebTransport}} interface is based on the `QuicTransport` interface
initially described in the [W3C ORTC CG](https://www.w3.org/community/ortc/),
and has been adapted for use in this specification.