WebSockets API
The WebSocketStream() constructor creates a new
WebSocketStream object instance.
Syntax
new WebSocketStream(url)
new WebSocketStream(url, options)
Parameters
url- : A string representing the URL of the WebSocket server you want to connect to with this
WebSocketStreaminstance. Allowed URL schemes are"ws","wss","http", and"https".
- : A string representing the URL of the WebSocket server you want to connect to with this
options- : An object that can contain the following properties:
protocols- : A single string or an array of strings representing the sub-protocol(s) that the client would like to use, for example
"amqp"or"mqtt". Subprotocols may be selected from the IANA WebSocket Subprotocol Name Registry or may be custom names jointly understood by the client and the server. A single server can implement multiple WebSocket sub-protocols, and handle different types of interactions depending on the specified value. If it is omitted, an empty array is used by default. Ifprotocolsis included, the connection will only be established if the server reports that it has selected one of these sub-protocols.
- : A single string or an array of strings representing the sub-protocol(s) that the client would like to use, for example
signal- : An AbortSignal, which can be used to abort the connection before the handshake has completed (that is, before the WebSocketStream.opened promise resolves). This is primarily intended to help implement connection timeouts. As such, it does nothing after the connection is established.
- : An object that can contain the following properties:
Exceptions
SyntaxErrorDOMException- : Thrown if the URL scheme is not one of
"ws","wss","http", or"https".
- : Thrown if the URL scheme is not one of
Examples
Creating a WebSocketStream
The most basic example takes the URL of a WebSocket server as an argument:
const wss = new WebSocketStream("wss://example.com/wss");
Creating a WebSocketStream with a connection timeout
The following example uses the signal option to implement a timeout if the connection is not established within 5 seconds:
const queueWSS = new WebSocketStream("wss://example.com/queue", {
signal: AbortSignal.timeout(5000),
});
Note that if you're connecting to localhost, it's likely to succeed or fail before the connection attempt times out.
Once the connection is established, signal has no effect: to close a connection that's already established, call the WebSocketStream.close() method. Closing the underlying WritableStream or WritableStreamDefaultWriter also closes the socket.
See Using WebSocketStream to write a client for a complete example with full explanation.
Specifications
Not currently a part of any specification. See https://github.com/whatwg/websockets/pull/48 for standardization progress.
Browser compatibility
See also
- WebSocketStream: integrating streams with the WebSocket API, developer.chrome.com (2020)
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
