WebSocketStream Class

  • Experimental (WEBPLATEXP0027)

A WebSocket connection whose messages are read and written with streams (https://whatpr.org/websockets/48.html#the-websocketstream-interface): the opened promise gives a ReadableStream of the received messages (a string for a text message, a Uint8Array for a binary message) and a WritableStream to which the messages are written (a string is sent as a text message, a BufferSource as a binary message), and the closed promise gives the status code and the reason of the closing handshake.

[Experimental("WEBPLATEXP0027", UrlFormat = "https://github.com/meziantou/Meziantou.Framework/blob/main/src/Meziantou.Framework.WebPlatform/docs/experimental-apis.md#{0}")]
public sealed class WebSocketStream

Remarks

The connection is a WebSocket of the current global object (the window or the worker of the script that creates the stream): it is established, closed and made to disappear (when its document is unloaded or its worker ends) as a WebSocket is, and its promises are settled by tasks of the event loop of that global object.

The readable stream applies backpressure: a message is read from the network only when the queue of the readable stream is not full (its high water mark is one message), so a server that sends faster than the page reads is slowed down by the network. A write is fulfilled once the message is sent. The streams exist only for the scripts: the WebSocketStream.Opened task of the .NET API gives the extensions and the subprotocol.

See also

Constructors

NameDescription
WebSocketStream(string, WebSocketStreamOptions?)Creates a WebSocketStream and starts to establish its connection (https://whatpr.org/websockets/48.html#dom-websocketstream-websocketstream).

WebSocketStream(string, WebSocketStreamOptions?)

WebSocketStream.cs

Creates a WebSocketStream and starts to establish its connection (https://whatpr.org/websockets/48.html#dom-websocketstream-websocketstream).

public WebSocketStream(string url, WebSocketStreamOptions? options = null)

Parameters

url string
The URL of the server: a ws: or wss: URL (an http: or https: URL is converted), possibly relative to the API base URL of the current global object, without fragment.
options WebSocketStreamOptions?
The subprotocols and the signal that aborts the opening handshake.

Exceptions

DomException
A SyntaxError when the URL is not valid, has another scheme or a fragment, or when a subprotocol is not a valid token or appears twice (ASCII case-insensitively).

See also

Properties

NameDescription
ClosedGets a task that completes when the connection is closed cleanly, with the status code and the reason of the closing handshake. It fails with a WebSocketError when the connection is not closed cleanly, or with the abort reason of the signal.
OpenedGets a task that completes when the connection is established, with the extensions and the subprotocol selected by the server. It fails with a WebSocketError when the connection cannot be established, or with the abort reason of the signal.
UrlGets the URL of the connection, serialized.

Gets a task that completes when the connection is closed cleanly, with the status code and the reason of the closing handshake. It fails with a WebSocketError when the connection is not closed cleanly, or with the abort reason of the signal.

public Task<WebSocketCloseInfo> Closed { get; }

Gets a task that completes when the connection is established, with the extensions and the subprotocol selected by the server. It fails with a WebSocketError when the connection cannot be established, or with the abort reason of the signal.

public Task<WebSocketOpenInfo> Opened { get; }

Property value

Task<WebSocketOpenInfo>

Remarks

For the scripts, the opened promise also gives the readable and writable streams of the messages.

See also

Gets the URL of the connection, serialized.

public string Url { get; }

Methods

NameDescription
Close(WebSocketCloseInfo?)Closes the connection (https://whatpr.org/websockets/48.html#dom-websocketstream-close): starts the closing handshake, or fails the connection when it is not established yet.

Close(WebSocketCloseInfo?)

WebSocketStream.cs

Closes the connection (https://whatpr.org/websockets/48.html#dom-websocketstream-close): starts the closing handshake, or fails the connection when it is not established yet.

public void Close(WebSocketCloseInfo? closeInfo = null)

Parameters

closeInfo WebSocketCloseInfo?
The status code (1000 or a code from 3000 to 4999; 1000 when only a reason is given) and the reason (at most 123 bytes in UTF-8) of the Close frame, or null for a Close frame without status code.

Exceptions

DomException
An InvalidAccessError when the code is not valid, or a SyntaxError when the reason is too long.

See also