Merge pull request #598 from jan-ivar/protocols

Add protocols constructor argument to WebTransport + protocol read arg

index.bs

@@ -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
@@ -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
@@ -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;
@@ -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
@@ -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
@@ -780,6 +804,8 @@ agent MUST run the following steps:
     :: |anticipatedConcurrentIncomingUnidirectionalStreams|
     : {{[[AnticipatedConcurrentIncomingBidirectionalStreams]]}}
     :: |anticipatedConcurrentIncomingBidirectionalStreams|
+    : {{[[Protocol]]}}
+    :: an empty string
     : {{[[Closed]]}}
     :: a new promise
     : {{[[Draining]]}}
@@ -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=].
@@ -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]].
 
@@ -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.
 
@@ -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>
@@ -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 {
@@ -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