Skip to content

Commit

Permalink
Merge pull request #598 from jan-ivar/protocols
Browse files Browse the repository at this point in the history
Add protocols constructor argument to WebTransport + protocol read arg
  • Loading branch information
nidhijaju authored Sep 17, 2024
2 parents 3363834 + 6b82382 commit 11009de
Showing 1 changed file with 53 additions and 6 deletions.
59 changes: 53 additions & 6 deletions index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,8 @@ specification uses that specification and terminology.
There are two main protocol concepts for WebTransport: sessions and streams. Each [=WebTransport
session=] can contain multiple [=WebTransport streams=].

These should not be confused with [=protocol names=] which is an application-level API construct.

## WebTransport session ## {#webtransport-session}

A <dfn for="protocol">WebTransport session</dfn> is a session of WebTransport over an HTTP/3
Expand Down Expand Up @@ -180,13 +182,21 @@ A [=WebTransport session=] has the following capabilities defined in [[!WEB-TRAN
</tbody>
</table>

To <dfn for=session>establish</dfn> a [=WebTransport session=] with an [=/origin=] |origin|,
follow [[!WEB-TRANSPORT-OVERVIEW]]
To <dfn for=session>establish</dfn> a [=WebTransport session=] with an [=/origin=] |origin| and a
|protocols| array, follow [[!WEB-TRANSPORT-OVERVIEW]]
[Section 4.1](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-overview-06#section-4.1-2.2.1),
with using |origin|, [=ASCII serialization of an origin|serialized=] and [=isomorphic encoded=],
as the [:Origin:] header of the request.
When establishing a session, the client MUST NOT provide any [=credentials=].
The resulting underlying transport stream is referred to as the session's <dfn>CONNECT stream</dfn>.
Additionally, if the |protocols| array is non-empty,
add a `WT-Available-Protocols` header field to the CONNECT request, containing
[=isomorphic encoded=] protocols from |protocols| in the order given, following [[!WEB-TRANSPORT-HTTP3]]
[Section 3.4](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/#section-3.4).
<div class="note">
This should reference [[!WEB-TRANSPORT-OVERVIEW]] instead pending
[issue 15](https://github.com/ietf-wg-webtrans/draft-ietf-webtrans-overview/issues/15).
</div>

A [=WebTransport session=] |session| is <dfn for=session>draining</dfn> when the
[=CONNECT stream=] receives an [=session-signal/DRAIN_WEBTRANSPORT_SESSION=] capsule, or when a
Expand Down Expand Up @@ -610,6 +620,7 @@ interface WebTransport {
readonly attribute WebTransportCongestionControl congestionControl;
[EnforceRange] attribute unsigned short? anticipatedConcurrentIncomingUnidirectionalStreams;
[EnforceRange] attribute unsigned short? anticipatedConcurrentIncomingBidirectionalStreams;
readonly attribute DOMString protocol;

readonly attribute Promise&lt;WebTransportCloseInfo&gt; closed;
readonly attribute Promise&lt;undefined&gt; draining;
Expand Down Expand Up @@ -703,6 +714,11 @@ A {{WebTransport}} object has the following internal slots.
<td class="non-normative">The number of concurrently open
[=bidirectional=] streams the application anticipates the server creating, or null.
</tr>
<tr>
<td><dfn>`[[Protocol]]`</dfn>
<td class="non-normative">A string indicating the application-level protocol selected by the server,
if any. Initially an empty string.
</tr>
<tr>
<td><dfn>`[[Closed]]`</dfn>
<td class="non-normative">A promise fulfilled when the associated {{WebTransport}} object is
Expand Down Expand Up @@ -750,6 +766,14 @@ agent MUST run the following steps:
congestion control algorithms that optimize for |congestionControl|, as allowed by
[[!RFC9002]] [Section 7](https://www.rfc-editor.org/rfc/rfc9002#section-7),
then set |congestionControl| to `"default"`.
1. Let |protocols| be {{WebTransport/constructor(url, options)/options}}'s
{{WebTransportOptions/protocols}}
1. If any of the values in |protocols| occur more than once, fail to match
the requirements for elements that comprise the value of `WT-Protocol`
fields as defined by the WebTransport protocol, or have an [=isomorphic encoded=]
length of 0 or exceeding 512, [=throw=] a {{SyntaxError}} exception.
[[!WEB-TRANSPORT-HTTP3]]
[Section 3.4](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/#section-3.4).
1. Let |anticipatedConcurrentIncomingUnidirectionalStreams| be {{WebTransport/constructor(url, options)/options}}'s
{{WebTransportOptions/anticipatedConcurrentIncomingUnidirectionalStreams}}.
1. Let |anticipatedConcurrentIncomingBidirectionalStreams| be {{WebTransport/constructor(url, options)/options}}'s
Expand Down Expand Up @@ -780,6 +804,8 @@ agent MUST run the following steps:
:: |anticipatedConcurrentIncomingUnidirectionalStreams|
: {{[[AnticipatedConcurrentIncomingBidirectionalStreams]]}}
:: |anticipatedConcurrentIncomingBidirectionalStreams|
: {{[[Protocol]]}}
:: an empty string
: {{[[Closed]]}}
:: a new promise
: {{[[Draining]]}}
Expand Down Expand Up @@ -812,15 +838,16 @@ This will ensure the stream is not errored due to a datagram being larger than t
[=ReadableStream/set up/pullAlgorithm=] set to |pullUnidirectionalStreamAlgorithm|, and
[=ReadableStream/set up/highWaterMark=] set to 0.
1. [=Initialize WebTransport over HTTP=] with |transport|, |parsedURL|, |dedicated|,
|requireUnreliable|, |congestionControl|, and |serverCertificateHashes|.
|requireUnreliable|, |congestionControl|, |protocols|, and |serverCertificateHashes|.
1. Return |transport|.

</div>

<div algorithm>
To <dfn>initialize WebTransport over HTTP</dfn>, given a {{WebTransport}} object
<var>transport</var>, a [=URL record=] |url|, a boolean |dedicated|, a boolean
|requireUnreliable|, a {{WebTransportCongestionControl}} |congestionControl|, and a
|requireUnreliable|, a {{WebTransportCongestionControl}} |congestionControl|,
a |protocols| array, and a
sequence&lt;{{WebTransportHash}}&gt; |serverCertificateHashes|, run these steps.

1. Let |client| be |transport|'s [=relevant settings object=].
Expand Down Expand Up @@ -872,7 +899,7 @@ sequence&lt;{{WebTransportHash}}&gt; |serverCertificateHashes|, run these steps.
1. Let |error| be a newly [=DOMException/created=] {{WebTransportError}} whose
{{WebTransportErrorOptions/source}} is `"session"`.
1. [=Cleanup=] |transport| with |error|.
1. [=session/Establish=] a [=WebTransport session=] with |origin| on |connection|.
1. [=session/Establish=] a [=WebTransport session=] with |origin| and |protocols| on |connection|.

Note: This step also contains the transport parameter exchange specified in [[!QUIC-DATAGRAM]].

Expand All @@ -890,7 +917,15 @@ sequence&lt;{{WebTransportHash}}&gt; |serverCertificateHashes|, run these steps.
1. Abort these steps.
1. Set |transport|.{{[[State]]}} to `"connected"`.
1. Set |transport|.{{[[Session]]}} to |session|.
1. If the connection is an HTTP/3 connection, set |transport|'s {{[[Reliability]]}} to `"supports-unreliable"`.
1. Set |transport|.{{[[Protocol]]}} to either the string value of the `WT-Protocol` header field
in the 2xx response to the CONNECT request if present, following [[!WEB-TRANSPORT-HTTP3]]
[Section 3.4](https://datatracker.ietf.org/doc/html/draft-ietf-webtrans-http3/#section-3.4),
or `""` if not present.
<div class="note">
This should reference [[!WEB-TRANSPORT-OVERVIEW]] instead pending
[issue 15](https://github.com/ietf-wg-webtrans/draft-ietf-webtrans-overview/issues/15).
</div>
1. If the connection is an HTTP/3 connection, set |transport|.{{[[Reliability]]}} to `"supports-unreliable"`.
1. If the connection is an HTTP/2 connection [[!WEB-TRANSPORT-HTTP2]], set |transport|'s {{[[Reliability]]}} to `"reliable-only"`.
1. [=Resolve=] |transport|.{{[[Ready]]}} with undefined.

Expand Down Expand Up @@ -1012,6 +1047,12 @@ Note: Setting {{WebTransport/anticipatedConcurrentIncomingUnidirectionalStreams}
{{WebTransport/anticipatedConcurrentIncomingBidirectionalStreams}} does not guarantee
the application will receive the number of streams it anticipates.

: <dfn for="WebTransport" attribute>protocol</dfn>
:: Once a [=WebTransport session=] has been established and the {{protocols}}
constructor option was used to provide a non-empty array, returns the application-level protocol
selected by the server, if any. Otherwise, an empty string.
The getter steps are to return [=this=]'s {{[[Protocol]]}}.

## Methods ## {#webtransport-methods}

<div algorithm>
Expand Down Expand Up @@ -1303,6 +1344,7 @@ dictionary WebTransportOptions {
WebTransportCongestionControl congestionControl = "default";
[EnforceRange] unsigned short? anticipatedConcurrentIncomingUnidirectionalStreams = null;
[EnforceRange] unsigned short? anticipatedConcurrentIncomingBidirectionalStreams = null;
sequence&lt;DOMString&gt; protocols = [];
};

enum WebTransportCongestionControl {
Expand Down Expand Up @@ -1366,6 +1408,11 @@ that determine how the [=WebTransport session=] is established and used.
{{[[AnticipatedConcurrentIncomingBidirectionalStreams]]}} into consideration in its
negotiations with the server.

: <dfn for="WebTransportOptions" dict-member>protocols</dfn>
:: An optionally provided array of application-level <dfn>protocol names</dfn>. The connection
will only be established if the server reports that it has selected one of these
application-level protocols.

<div algorithm>
To <dfn>compute a certificate hash</dfn>, given a |certificate|, perform the following steps:
1. Let |cert| be |certificate|, represented as a DER encoding of
Expand Down

0 comments on commit 11009de

Please sign in to comment.