[WIP] The WebSocketStream Interface

Author: ricea

index.bs

@@ -795,6 +795,128 @@ the following list:
 
 </div>
 
+
+
+# The {{WebSocketStream}} interface # {#the-websocketstream-interface}
+
+The Web IDL definition for the {{WebSocketStream}} class is given as follows:
+
+<xmp class="idl">
+dictionary WebSocketOpenInfo {
+  ReadableStream readable;
+  WritableStream writable;
+  DOMString extensions;
+  DOMString protocol;
+};
+
+dictionary WebSocketCloseInfo {
+  [Clamp] unsigned short code;
+  USVString reason = "";
+};
+
+dictionary WebSocketStreamOptions {
+  sequence<USVString> protocols;
+  AbortSignal signal;
+};
+
+[
+    Exposed=(Window,Worker)
+] interface WebSocketStream {
+  constructor(USVString url, optional WebSocketStreamOptions options);
+  readonly attribute USVString url;
+  readonly attribute Promise<WebSocketOpenInfo> opened;
+  readonly attribute Promise<WebSocketCloseInfo> closed;
+  undefined close(optional WebSocketCloseInfo closeInfo);
+};
+</xmp>
+
+A {{WebSocketStream}} object has an associated <dfn>url</dfn> (a [=URL record=]).
+
+A {{WebSocketStream}} object has an associated <dfn>opened promise</dfn>.
+
+A {{WebSocketStream}} object has an associated <dfn>closed promise</dfn>.
+
+A {{WebSocketStream}} object has an associated <dfn>was ever connected flag</dfn>, which is
+initially unset.
+
+<dl class="domintro non-normative">
+ : <code>|socket| = new {{WebSocketStream/constructor(url, options)|WebSocketStream}}(|url| [, |options| ]</code>
+ :: Creates a new {{WebSocketStream}} object, immediately establishing the associating WebSocket
+  connection.
+
+  |url| is a string giving the <a dfn spec=url>URL</a> over which the connection is established.
+  Only "`ws`" or "`wss`" schemes are allowed; others will cause a "{{SyntaxError}}"
+  {{DOMException}}. URLs with [=fragments=] will also cause such an exception.
+
+  The |options| argument is an object whose properties can be set as follows:
+
+  : {{WebSocketStreamOptions/protocols}}
+  :: An array of strings. If it is omitted, it is equivalent to an empty array. Each string in the
+   array is a subprotocol name. The connection will only be established if the server reports that
+   it has selected one of these subprotocols. The subprotocol names have to match the requirements
+   for elements that comprise the value of \`<a http-header>`Sec-WebSocket-Protocol`</a>\` fields as
+   defined by The WebSocket protocol.  [[!WSP]]
+
+  : {{WebSocketStreamOptions/signal}}
+  :: An {{AbortSignal}} that can be used to abort the handshake. After the handshake is complete the
+   signal does nothing.
+
+ : <code>|socket| . {{WebSocketStream/url}}</code>
+ :: Returns the <a lt="url">URL that was used</a> to establish the WebSocket connection.
+
+ : <code>|socket| . {{WebSocketStream/opened}}</code>
+ :: Returns a {{promise}} which resolves when the handshake successfully completes, or rejects if
+  the handshake fails. On success, it resolves to an object with the following properties:
+
+  : {{WebSocketOpenInfo/readable}}
+  :: A {{ReadableStream}} that can be used to read messages from the server. Each chunk read
+   corresponds to one message. Text messages will be read as strings; binary messages will be read
+   as ArrayBuffer objects.
+
+   The stream can be closed by calling {{ReadableStream/cancel()}} on
+   {{WebSocketOpenInfo/readable}}. If the argument passed to {{ReadableStream/cancel()}} is an
+   object with a {{WebSocketCloseInfo/code}} property and an <span class=allow-2119>optional</span> {{WebSocketCloseInfo/reason}}
+   property then {{WebSocketCloseInfo/code}} will be used as [=the WebSocket connection close
+   code=] and {{WebSocketCloseInfo/reason}} or the empty string will be used as [=the WebSocket
+   connection close reason=].
+
+   If no messages are read, or if messages are read slower than they are sent, then backpressure
+   will be applied and eventually the server will stop sending new messages.
+
+  : {{WebSocketOpenInfo/writable}}
+  :: A {{WritableStream}} that can be used to send messages to the server. Each chunk written will
+   be converted to one messages. Strings will be sent as text messages; {{BufferSource}} chunks will
+   be sent as binary messages.
+
+   The WebSocket can be closed by calling {{WritableStream/close()}} on
+   {{WebSocketOpenInfo/writable}}.
+
+   The stream can also be closed by calling {{WritableStream/abort()}}
+   {{WebSocketOpenInfo/writable}}. If an argument is passed to {{WritableStream/abort()}} then it
+   can be used to specify [=the WebSocket connection close code=] and [=the WebSocket connection
+   close reason=] as with {{ReadableStream/cancel()}} above.
+
+  : {{WebSocketOpenInfo/extensions}}
+  :: The [=extensions in use=] for the connection.
+
+  : {{WebSocketOpenInfo/protocol}}
+  :: The [=subprotocol in use=] for the connection.
+
+ : <code>|socket| . {{WebSocketStream/closed}}</code>
+ :: A {{promise}} which resolves when the connection is closed. If the connection did not close
+  [=cleanly=] then the promise is rejected. When the connection closes [=cleanly=] the promise is
+  resolved with an object with properties {{WebSocketCloseInfo/code}} and
+  {{WebSocketCloseInfo/reason}}, giving [=the WebSocket connection close code=] and [=the WebSocket
+  connection close reason=] the were supplied by the server.
+
+ : <code>|socket| . {{WebSocketStream/close()}}</code>
+ :: Close the connection, optionally supplying an object with {{WebSocketCloseInfo/code}} and
+  {{WebSocketCloseInfo/reason}} properties to indicate [=the WebSocket connection close code=] and
+  [=the WebSocket connection close reason=] that will be sent to the remote server. If the handshake
+  is still in progress then it will be aborted and {{WebSocketCloseInfo/code}} and
+  {{WebSocketCloseInfo/reason}} will be ignored.
+</dl>
+
 <h2 id="acks" class="no-num">Acknowledgments</h2>
 
 Until the creation of this standard in 2021, the text here was maintained in the <a