diff --git a/files/en-us/web/api/websockets_api/using_websocketstream/index.md b/files/en-us/web/api/websockets_api/using_websocketstream/index.md index a3d8a435b9d4bf3..8558de6dac1241f 100644 --- a/files/en-us/web/api/websockets_api/using_websocketstream/index.md +++ b/files/en-us/web/api/websockets_api/using_websocketstream/index.md @@ -28,13 +28,13 @@ To create a WebSocket client, you first need to create a new `WebSocketStream` i const wss = new WebSocketStream("wss://example.com/wss"); ``` -It can also take an options object containing custom protocols and/or an {{domxref("AbortSignal")}} (see [Closing the connection](#closing_the_connection)): +It can also take an `options` object containing custom protocols and/or an {{domxref("AbortSignal")}}. The `AbortSignal` can be used to abort the connection attempt before the [handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) has completed (that is, before the {{domxref("WebSocketStream.opened", "opened")}} promise resolves). It is typically used to implement a connection timeout. For example, the following code will time out if the handshake takes more than 5 seconds to complete: ```js const controller = new AbortController(); const queueWSS = new WebSocketStream("wss://example.com/queue", { protocols: ["amqp", "mqtt"], - signal: controller.signal, + signal: AbortSignal.timeout(5000), }); ``` @@ -76,26 +76,7 @@ The browser automatically controls the rate at which the client receives and sen ## Closing the connection -With `WebSocketStream`, the information previously available via the `WebSocket` {{domxref("WebSocket.close_event", "close")}} and {{domxref("WebSocket.error_event", "error")}} events is now available via the {{domxref("WebSocketStream.closed", "closed")}} property — this returns a promise that fulfills with an object containing the closing code (see the full list of [`CloseEvent` status codes](/en-US/docs/Web/API/CloseEvent/code#value)) and reason indicating why the server closed the connection: - -```js -const { code, reason } = await wss.closed; -``` - -As mentioned earlier, the WebSocket connection can be closed using an {{domxref("AbortController")}}. The necessary {{domxref("AbortSignal")}} is passed to the `WebSocketStream` constructor during creation, and {{domxref("AbortController.abort()")}} can then be called when required: - -```js -const controller = new AbortController(); -const wss = new WebSocketStream("wss://example.com/wss", { - signal: controller.signal, -}); - -// some time later - -controller.abort(); -``` - -Alternatively you can use the {{domxref("WebSocketStream.close()")}} method to close a connection. This is mainly used if you wish to specify a custom code and/or reason: +To close a connection, call the {{domxref("WebSocketStream.close()")}} method, optionally passing a [closing code](/en-US/docs/Web/API/CloseEvent/code#value) and reason: ```js wss.close({ @@ -107,6 +88,14 @@ wss.close({ > [!NOTE] > Depending on the server setup and status code you use, the server may choose to ignore a custom code in favor of a valid code that is correct for the closing reason. +Closing the underlying {{domxref("WritableStream")}} or {{domxref("WritableStreamDefaultWriter")}} also closes the connection. + +To handle connection closure, wait for the {{domxref("WebSocketStream.closed", "closed")}} promise to resolve: + +```js +const { closeCode, reason } = await wss.closed; +``` + ## A complete sample client To demonstrate basic usage of `WebSocketStream`, we've created a sample client. You can see the [full listing](#full_listing) at the bottom of the article, and follow along with the explanation below. diff --git a/files/en-us/web/api/websocketstream/close/index.md b/files/en-us/web/api/websocketstream/close/index.md index 534fc07939a49d4..392fab2cf22ed46 100644 --- a/files/en-us/web/api/websocketstream/close/index.md +++ b/files/en-us/web/api/websocketstream/close/index.md @@ -13,8 +13,6 @@ browser-compat: api.WebSocketStream.close The **`close()`** method of the {{domxref("WebSocketStream")}} interface closes the WebSocket connection. The method optionally accepts an object containing a custom code and/or reason indicating why the connection was closed. -An alternative mechanism for closing a `WebSocketStream` is to specify an {{domxref("AbortSignal")}} in the [`signal`](/en-US/docs/Web/API/WebSocketStream/WebSocketStream#signal) option of the constructor upon creation. The associated {{domxref("AbortController")}} can then be used to close the WebSocket connection. This is generally the preferred mechanism. However, `close()` can be used if you wish to specify a custom code and/or reason. - ## Syntax ```js-nolint diff --git a/files/en-us/web/api/websocketstream/websocketstream/index.md b/files/en-us/web/api/websocketstream/websocketstream/index.md index 7ad496a21560ad5..60b570e893587a3 100644 --- a/files/en-us/web/api/websocketstream/websocketstream/index.md +++ b/files/en-us/web/api/websocketstream/websocketstream/index.md @@ -31,7 +31,6 @@ new WebSocketStream(url, options) - `signal` {{optional_inline}} - : An {{domxref("AbortSignal")}}, which can be used to abort the connection before the [handshake](/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#the_websocket_handshake) has completed (that is, before the {{domxref("WebSocketStream.opened", "opened")}} promise resolves). This is primarily intended to help implement connection timeouts. As such, it does nothing after the connection is established. - ### Exceptions - `SyntaxError` {{domxref("DOMException")}} @@ -39,36 +38,36 @@ new WebSocketStream(url, options) ## Examples +### Creating a `WebSocketStream` + The most basic example takes the URL of a WebSocket server as an argument: ```js const wss = new WebSocketStream("wss://example.com/wss"); ``` -A more advanced example could also include an options object containing custom protocols and/or an {{domxref("AbortSignal")}}. The following example will time out if the connection is not established within 5 seconds: +### 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: ```js const queueWSS = new WebSocketStream("wss://example.com/queue", { - protocols: ["amqp", "mqtt"], signal: AbortSignal.timeout(5000), }); ``` -If you're connecting to localhost, it's likely to succeed or fail almost instantly, so this will have no effect. +Note that if you're connecting to localhost, it's likely to succeed or fail before the connection attempt times out. -You can use the {{domxref("WebSocketStream.close()")}} method to close a connection. - -`WritableStream.close()` and `WritableStreamDefaultWriter.close()` from the `writable` of the fulfilled `opened` `Promise` also closes the connection. +Once the connection is established, `signal` has no effect: to close a connection that's already established, call the {{domxref("WebSocketStream.close()")}} method. Closing the underlying {{domxref("WritableStream")}} or {{domxref("WritableStreamDefaultWriter")}} also closes the socket. See [Using WebSocketStream to write a client](/en-US/docs/Web/API/WebSockets_API/Using_WebSocketStream) 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. +Not currently a part of any specification. See https://github.com/whatwg/websockets/pull/48 for standardization progress. [WebSocketStream API design](https://docs.google.com/document/d/1La1ehXw76HP6n1uUeks-WJGFgAnpX2tCjKts7QFJ57Y/edit?pli=1&tab=t.0). - ## Browser compatibility {{Compat}}