Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add protocols constructor argument to WebTransport + protocol read arg #598

Merged
merged 11 commits into from
Sep 17, 2024
Merged

Add protocols constructor argument to WebTransport + protocol read arg #598

Changes from 10 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
6b290e1
Add protocols constructor argument to WebTransport
jan-ivar Apr 8, 2024
1aea6f1
Add "if present"
jan-ivar Apr 9, 2024
b5714ad
Specify object internal slot is on
jan-ivar Apr 9, 2024
ce6d137
s/protocols/subprotocols/
jan-ivar Apr 23, 2024
63174b0
maintain subprotocol order in header and reject on empty strings
jan-ivar Apr 23, 2024
4e789c0
Merge branch 'main' into protocols
jan-ivar Jul 10, 2024
55edef9
s/protocols/subprotocols/ in API
jan-ivar Jul 16, 2024
afccefd
s/subprotocol/protocol/ in API only, leaving subprotocol in prose
jan-ivar Jul 30, 2024
3390934
Update to match latest header field names; add notes
jan-ivar Sep 9, 2024
d4f566f
Apply suggestions from code review
nidhijaju Sep 17, 2024
6b82382
Update index.bs
nidhijaju Sep 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 53 additions & 6 deletions index.bs
View file
Open in desktop
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]]
jan-ivar marked this conversation as resolved.
Show resolved Hide resolved
[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 @@ -866,7 +893,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 @@ -884,7 +911,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 @@ -1006,6 +1041,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 subprotocol
nidhijaju marked this conversation as resolved.
Show resolved Hide resolved
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 @@ -1297,6 +1338,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 @@ -1360,6 +1402,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
Loading