Editorial review: Document WebSocketStream #35548

chrisdavidmills · 2024-08-22T09:00:58Z

Description

Chrome 124 supports the WebSocketStream API (see the associated ChromeStatus entry).

Note that WebSocketStream is currently supported in Chromium-based browsers, and is not yet part of a standard so I will mark it as non-standard for now. See whatwg/websockets#48 for progress on that.

Motivation

Additional details

Related issues and pull requests

github-actions · 2024-08-22T09:02:29Z

Preview URLs (11 pages)

External URLs (17)

URL: /en-US/docs/Web/API/WebSocketStream
Title: WebSocketStream

https://developer.chrome.com/docs/capabilities/web-apis/websocketstream (1 time) (Note! This may be a new URL 👀)
The WebSocketStream Interface whatwg/websockets#48 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/WebSocketStream/WebSocketStream
Title: WebSocketStream: WebSocketStream() constructor

https://developer.chrome.com/docs/capabilities/web-apis/websocketstream (1 time) (Note! This may be a new URL 👀)
The WebSocketStream Interface whatwg/websockets#48 (1 time) (Note! This may be a new URL 👀)
https://www.iana.org/assignments/websocket/websocket.xml (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/WebSocketStream/closed
Title: WebSocketStream: closed property

https://developer.chrome.com/docs/capabilities/web-apis/websocketstream (1 time) (Note! This may be a new URL 👀)
The WebSocketStream Interface whatwg/websockets#48 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/WebSocketStream/close
Title: WebSocketStream: close() method

https://developer.chrome.com/docs/capabilities/web-apis/websocketstream (1 time) (Note! This may be a new URL 👀)
The WebSocketStream Interface whatwg/websockets#48 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/WebSocketStream/url
Title: WebSocketStream: url property

https://developer.chrome.com/docs/capabilities/web-apis/websocketstream (1 time) (Note! This may be a new URL 👀)
The WebSocketStream Interface whatwg/websockets#48 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/WebSocketStream/opened
Title: WebSocketStream: opened property

https://developer.chrome.com/docs/capabilities/web-apis/websocketstream (1 time) (Note! This may be a new URL 👀)
The WebSocketStream Interface whatwg/websockets#48 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/WebSockets_API
Title: The WebSocket API (WebSockets)

https://channels.readthedocs.io/en/stable/index.html (1 time) (Note! This may be a new URL 👀)
https://github.com/phoenixframework/phoenix_live_view (1 time) (Note! This may be a new URL 👀)
https://hexdocs.pm/phoenix/channels.html (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/CloseEvent/code
Title: CloseEvent: code property

https://www.rfc-editor.org/rfc/rfc6455.html (3 times) (Note! This may be a new URL 👀)

(comment last updated: 2024-09-12 18:12:30)

tomayac

This is in a really good shape. Just some nits.

Maybe ping @ricea for a spec editor review.

files/en-us/web/api/websockets_api/using_websocketstream/index.md

files/en-us/web/api/websocketstream/closed/index.md

files/en-us/web/api/websocketstream/opened/index.md

files/en-us/web/api/websocketstream/url/index.md

files/en-us/web/api/websocketstream/websocketstream/index.md

Co-authored-by: Thomas Steiner <[email protected]>

chrisdavidmills · 2024-08-28T17:42:10Z

Thanks, @tomayac! I accepted all of your suggestions. I also checked and updated a few example snippets to use wss:// and self for feature detection to keep things consistent.

Also, because we need to specify ws:// in the code example for it to work as written, I've added a note into the WebSocketStream guide to draw the reader's attention to this, just in case they use wss:// and get stuck as a result.

I'm going to put this forward for editorial review now, but @ricea, feel free to have a look and make comments if you wish. It should take a little while for someone to pick it up, so there is time.

wbamberg

Here are comments on the non-reference pages.

wbamberg · 2024-09-03T22:33:07Z

files/en-us/web/api/websockets_api/index.md

+### WebSocketStream
+
+The {{domxref("WebSocketStream")}} API is a modern reimagining of WebSocket client-side JavaScript functionality. It is promise-based, and therefore simpler to work with than the traditional {{domxref("WebSocket")}} API in the modern JavaScript scosystem. In addition, it uses the [Streams API](/en-US/docs/Web/API/Streams_API) to handle receiving and sending messages, meaning that socket connections can take advantage of stream [backpressure](/en-US/docs/Web/API/Streams_API/Concepts#backpressure) automatically, regulating the speed of reading or writing to avoid bottlenecks in the application. See [Using WebSocketStream to write a client](/en-US/docs/Web/API/WebSockets_API/Using_WebSocketStream) for more information.


I think this needs more context. We have an intro about what websockets are, then go right into:

The WebSocketStream API is a modern reimagining of WebSocket client-side JavaScript functionality. It is promise-based, and therefore simpler to work with than the traditional WebSocket API ...

...but we haven't even talked about "traditional" WebSocket yet.

Also, "a modern reimagining of WebSocket client-side JavaScript functionality" reads like marketing to me. As a web developer who doesn't know yet about WebSockets, let alone Web Transport, what am I to make of all this?

IIUC there's a major drawback to WebSocketStream: it's nonstandard and only supported in one browser engine. Given that, I'm not sure MDN should recommend it above standard and cross-platform alternatives.

It would be very helpful here to lay out all the considerations, including Web Transport, in a neutral and factual way, to help developers make good choices.

It seems like the main motivation for WebSocketStream over WebSocket is to support backpressure, and I would put that first, before the "promise-based API" motivation (I doubt that would be a strong enough motivation alone for web developers to want to adopt this API). The explainer does a nice job of that actually.

So we might say something roughly like:

In the WebSocket API, there are two alternative ways to create and use web sockets: the WebSocket interface and the WebSocketStream interface.

The WebSocket interface is stable and has good browser and server support. However it doesn't support backpressure (explain what this is and why it is a problem)

The WebSocketStream is an alternative to WebSocket, that's based on the Streams API and therefore does support backpressure. However, it's nonstandard and has poor cross-browser support.

Additionally, the WebTransport API is expected to replace the WebSocket API for many applications, and supports backpressure along with many other features not supported by either WebSocket or WebSocketStream. something something about when and in which circs people should choose WebSocket over WebTransport or vice versa

Good call. In my next commit, I have used your suggested structure as a basis, and filled in the missing details.

wbamberg · 2024-09-03T22:45:54Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+
+{{DefaultAPISidebar("WebSockets API")}}{{non-standard_header}}
+
+The {{domxref("WebSocketStream")}} API is a modern reimagining of WebSocket client-side JavaScript functionality. It is promise-based, and therefore simpler to work with than the traditional {{domxref("WebSocket")}} API in the modern JavaScript scosystem. In addition, it uses the [Streams API](/en-US/docs/Web/API/Streams_API) to handle receiving and sending messages, meaning that socket connections can take advantage of stream [backpressure](/en-US/docs/Web/API/Streams_API/Concepts#backpressure) automatically, regulating the speed of reading or writing to avoid bottlenecks in the application.


This is a copy/paste from the overview page. I'm not sure it's needed here.

The overview page no longer contains this paragraph. I have kept it on this page, but updated it to make it more concise and less marketing-y.

wbamberg · 2024-09-03T22:46:03Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+
+The {{domxref("WebSocketStream")}} API is a modern reimagining of WebSocket client-side JavaScript functionality. It is promise-based, and therefore simpler to work with than the traditional {{domxref("WebSocket")}} API in the modern JavaScript scosystem. In addition, it uses the [Streams API](/en-US/docs/Web/API/Streams_API) to handle receiving and sending messages, meaning that socket connections can take advantage of stream [backpressure](/en-US/docs/Web/API/Streams_API/Concepts#backpressure) automatically, regulating the speed of reading or writing to avoid bottlenecks in the application.
+
+This article explains how to use the {{domxref("WebSocketStream")}} API to create a simple WebSocket client.


Suggested change

This article explains how to use the {{domxref("WebSocketStream")}} API to create a simple WebSocket client.

This article explains how to use the {{domxref("WebSocketStream")}} API to create a WebSocket client.

Argh, the curse of "simple"! Removed in next commit ;-)

wbamberg · 2024-09-03T23:34:43Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+> [!NOTE]
+> Backpressure is an issue with the traditional `WebSocket` API — it has no way to apply backpressure, therefore when messages arrive faster than the application can process them, the application will either fill up the device's memory by buffering those messages, become unresponsive due to 100% CPU usage, or both.


Also, this note seems out of place, especially if you remove or cut down the first para. What would be helpful, IMO, would be something about what (if anything) the developer has to do to take advantage of backpressure support. I think nothing? i.e. if they just don't read, then backpressure is exerted. Is that right though?

The page at https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Concepts#backpressure says:

To use backpressure in a ReadableStream, we can ask the controller for the chunk size desired by the consumer by querying the ReadableStreamDefaultController.desiredSize property on the controller. If it is too low, our ReadableStream can tell its underlying source to stop sending data, and we backpressure along the stream chain.

...which I don't really understand - who is "we" here?

I have removed the note from here, and put a shortened version on the WebSocket page.

In terms of how to use it, it is just automatic for WebSocketStream. I do say "automatically" in the opening paragraph. Do you think I need to be a bit more explicit?

It is somewhat out of scope for this PR to start updating the Streams API docs. We could do that in a separate PR. Maybe file an issue for now?

In terms of how to use it, it is just automatic for WebSocketStream. I do say "automatically" in the opening paragraph. Do you think I need to be a bit more explicit?

Yes, I do. The doc links to https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Concepts#backpressure, which as I say is hard to understand, but does not make it obvious that the developer has to do nothing for backpressure to work.

I think it would be best to spell this out in the bit about "To read data from the socket, you can continuously call ReadableStreamDefaultReader.read() ...", and will leave a suggestion there.

OK, cool. I've also added a little qualifier here in parens - "(no additional action required by the developer)" - which will hopefully help too.

wbamberg · 2024-09-03T23:40:23Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+To write data to the socket, you can use {{domxref("WritableStreamDefaultWriter.write()")}}:
+
+```js
+await writer.write("My message");


Why await here?

I was just including it because write() returns a promise. I guess I don't need it for this trivial line. Removed.

wbamberg · 2024-09-04T02:13:50Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+  wss.close({
+    code: 1000,
+    reason: "That's all folks",


We say a few times that it's preferable to use abort(), maybe better to show that?

We also say that close() is used when providing a custom code and/or reason. In this case we are providing a custom reason, so I think this is OK.

To be pedantic, which I always am, it says "custom code and reason".

OK, all relevant instances now changed to "and/or".

wbamberg · 2024-09-04T02:21:48Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+    <h2>WebSocketStream Test</h2>
+    <p>Sends a ping every five seconds</p>
+    <div id="output"></div>
+    <script>


I think it would be easier to read this if the JS were in an external script.

Possibly so, but this would also make it slightly more annoying for a user to copy and paste and chuck into a file for testing purposes. I think it is better to leave as-is, by this token.

wbamberg · 2024-09-04T02:26:21Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+slug: Web/API/WebSockets_API/Using_WebSocketStream
+page-type: guide
+status:
+  - non-standard


also experimental?

OK, makes sense. I've also added it to the WebSocketStream interface pages.

FWIW this should get added automatically from the BCD. But only in reference pages, not in guide pages.

Ah, OK. I keep forgetting what is automatically added and what isn't.

wbamberg · 2024-09-04T02:30:17Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+
+The main bulk of our code is contained within the `start()` function, which we define and then immediately invoke. We await the {{domxref("WebSocketStream.opened", "opened")}} promise, then after it fulfills write a message to let the reader know the connection is successful and create {{domxref("ReadableStreamDefaultReader")}} and {{domxref("WritableStreamDefaultWriter")}} instances from the returned `readable` and `writable` properties.
+
+Next, we `write()` a `"ping"` value to the socket and communicate that to the user. At this point, the server will respond with a `"pong"` message. We await the `read()` of the read message, communicate it to the user, then write another `"ping"` to the server after a timeout of 5 seconds. This continues the `"ping"`/`"pong"` loop indefinitely.


Suggested change

Next, we `write()` a `"ping"` value to the socket and communicate that to the user. At this point, the server will respond with a `"pong"` message. We await the `read()` of the read message, communicate it to the user, then write another `"ping"` to the server after a timeout of 5 seconds. This continues the `"ping"`/`"pong"` loop indefinitely.

Next, we `write()` a `"ping"` value to the socket and communicate that to the user. At this point, the server will respond with a `"pong"` message. We await the `read()` of the reasponse, communicate it to the user, then write another `"ping"` to the server after a timeout of 5 seconds. This continues the `"ping"`/`"pong"` loop indefinitely.

wbamberg · 2024-09-04T02:31:28Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+> [!NOTE]
+> To get the example working, you'll also need a server component. We wrote our client to work along with the Deno server explained in [Writing a WebSocket server in JavaScript (Deno)](/en-US/docs/Web/API/WebSockets_API/Writing_a_WebSocket_server_in_JavaScript_Deno), but any compatible server will do.
+
+First we grab a reference to a DOM element into which we will write output messages, and define a utility function that writes a message to it:


I'm a bit worried that this duplication of the code will make it hard to maintain. I understand though that just quoting the whole block then talking through it all might be indigestible, so idk what is for the best.

I appreciate that, but I've not got a better solution. Leaving as-is.

wbamberg

Comments for the other pages.

wbamberg · 2024-09-04T03:15:52Z

files/en-us/web/api/websocketstream/websocketstream/index.md

+- `options` {{optional_inline}}
+  - : An object than can contain the following properties:
+    - `protocols` {{optional_inline}}
+      - : An array of strings representing custom protocols to use for the connection.


Should we explain what this option is used for? Also, are there syntactic restrictions on the strings?

Added. Info on allowable names was hard to track down, and I didn't really find anything concrete about syntactic restrictions. I have added some more useful info.

wbamberg · 2024-09-04T03:16:44Z

files/en-us/web/api/websocketstream/websocketstream/index.md

+> [!NOTE]
+> Alternatively, you can use the {{domxref("WebSocketStream.close()")}} method to close a connection, however this is mainly needed if you wish to specify a custom code and reason for the server to report.


Don't think this should be a note. It works fine as a normal paragraph.

Agreed. I've de-noted it.

wbamberg · 2024-09-04T03:17:22Z

files/en-us/web/api/websocketstream/websocketstream/index.md

+- `url`
+  - : A string representing the URL of the WebSocket server you want to connect to with this `WebSocketStream` instance. Allowed URL schemes are `"ws"`, `"wss"`, `"http"`, and `"https"`.
+- `options` {{optional_inline}}
+  - : An object than can contain the following properties:


Suggested change

- : An object than can contain the following properties:

- : An object that can contain the following properties:

fixed - ta!

wbamberg · 2024-09-04T03:17:47Z

files/en-us/web/api/websocketstream/websocketstream/index.md

+## Syntax
+
+```js-nolint
+new WebSocketStream(url, options)


Suggested change

new WebSocketStream(url, options)

new WebSocketStream(url)

new WebSocketStream(url, options)

Good call; updated.

wbamberg · 2024-09-04T03:20:41Z

files/en-us/web/api/websocketstream/close/index.md

+> [!NOTE]
+> 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 reason for the server to report.


Again I don't think this is a note.

Again, de-noted.

wbamberg · 2024-09-04T17:32:19Z

files/en-us/web/api/websocketstream/index.md

+- {{domxref("WebSocketStream.url", "url")}} {{ReadOnlyInline}}
+  - : Returns the URL of the WebSocket server that the `WebSocketStream` instance was created with.
+- {{domxref("WebSocketStream.closed", "closed")}} {{ReadOnlyInline}}
+  - : Returns a {{jsxref("Promise")}} that fulfills with an object once the socket connection is closed. The object contains the closing code and reason sent by the server.


re "sent by the server", same comment as in the closed page, what if the client closes it?

Same answer as above. I'm not sure if this needs an update. I have modified it slightly, to "as sent by the server"

wbamberg · 2024-09-04T17:34:34Z

files/en-us/web/api/websocketstream/index.md

+- {{domxref("WebSocketStream.closed", "closed")}} {{ReadOnlyInline}}
+  - : Returns a {{jsxref("Promise")}} that fulfills with an object once the socket connection is closed. The object contains the closing code and reason sent by the server.
+- {{domxref("WebSocketStream.opened", "opened")}} {{ReadOnlyInline}}
+  - : Returns a {{jsxref("Promise")}} that fulfills with an object once the socket connection is successfully opened. The object contains several useful features, including a {{domxref("ReadableStream")}} and a {{domxref("WritableStream")}} instance for receiving and sending data on the connection.


Suggested change

- : Returns a {{jsxref("Promise")}} that fulfills with an object once the socket connection is successfully opened. The object contains several useful features, including a {{domxref("ReadableStream")}} and a {{domxref("WritableStream")}} instance for receiving and sending data on the connection.

- : Returns a {{jsxref("Promise")}} that fulfills with an object once the socket connection is successfully opened. Among other properties, the object includes a {{domxref("ReadableStream")}} and a {{domxref("WritableStream")}} instance for receiving and sending data on the connection.

Very picky. "several useful features" seems a bit odd. Should it be taken for granted that the properties are useful?

Yup, very picky. You are right too, which is even more annoying ;-)

I have updated the wording to "Among other features, this object contains a...", as the items listed aren't the actual property names, but the values they contain.

wbamberg · 2024-09-04T17:35:58Z

files/en-us/web/api/websocketstream/opened/index.md

+{{APIRef("WebSockets API")}}{{non-standard_header}}
+
+The **`opened`** read-only property of the
+{{domxref("WebSocketStream")}} interface returns a {{jsxref("Promise")}} that fulfills with an object once the socket connection is successfully opened. The object contains several useful features, including a {{domxref("ReadableStream")}} and a {{domxref("WritableStream")}} instance for receiving and sending data on the connection.


"several useful features" again.

Same change made here.

wbamberg · 2024-09-04T17:37:06Z

files/en-us/web/api/websocketstream/opened/index.md

+- `extensions`
+  - : A string representing any extensions applied to the `WebSocketStream`. Such extensions are not currently defined, but may be in the future. Currently returns an empty string.
+- `protocol`
+  - : A string representing any custom protocol used to open the current WebSocket connection, as specified in the [`protocols`](/en-US/docs/Web/API/WebSocketStream/WebSocketStream#protocols) option of the `WebSocketStream()` constructor. Returns an empty string if no custom protocol was used.


I guess this must be one of the ones given in the constructor?

I don't really understand the question. The text clearly says "as specified in the protocols option of the WebSocketStream() constructor".

I've updated the end of the description to "if no custom protocol was set during instantiation", in case it is useful.

I don't think "as specified in..." is very clear. protocols is an array, this is a single item. I'm assuming what happens is that the client passes, in protocols, an array of custom protocols it is prepared to work with, and the server responds with a single protocol from the array. But the docs don't say this, so I have to guess.

Ah, OK, I getcha now. I've done a bit of reading around this, and have updated this description to:

A string representing the sub-protocol used to open the current WebSocket connection (chosen from the options specified in the protocols option of the WebSocketStream() constructor). Returns an empty string if no sub-protocol has been used to open the connection (i.e. no sub-protocol options were included in the constructor call).

wbamberg · 2024-09-04T17:38:38Z

files/en-us/web/api/websocketstream/opened/index.md

+## Examples
+
+```js
+const output = document.querySelector("#output");


As for closed, I think a smaller more focused example would be better.

I've cut it down quite a bit, but not as much as the closed example.

wbamberg · 2024-09-06T15:26:58Z

files/en-us/web/api/websockets_api/index.md

-browser-compat: api.WebSocket
+browser-compat:
+  - api.WebSocket
+  - api.WebSocketStream
 ---

 {{DefaultAPISidebar("WebSockets API")}}

 The **WebSocket API** is an advanced technology that makes it possible to open a two-way interactive communication session between the user's browser and a server. With this API, you can send messages to a server and receive event-driven responses without having to poll the server for a reply.


Suggested change

The **WebSocket API** is an advanced technology that makes it possible to open a two-way interactive communication session between the user's browser and a server. With this API, you can send messages to a server and receive event-driven responses without having to poll the server for a reply.

The **WebSocket API** makes it possible to open a two-way interactive communication session between the user's browser and a server. With this API, you can send messages to a server and receive responses without having to poll the server for a reply.

(not necessarily event-driven)

Sounds reasonable. Updated to use your wording.

wbamberg · 2024-09-06T15:27:39Z

files/en-us/web/api/websockets_api/index.md

+- The `WebSocketStream` is a {{jsxref("Promise")}}-based alternative to `WebSocket`. It uses the [Streams API](/en-US/docs/Web/API/Streams_API) to handle receiving and sending messages, meaning that socket connections can take advantage of stream backpressure automatically, regulating the speed of reading or writing to avoid bottlenecks in the application. However, `WebSocketSteam` is non-standard and currently only supported in one rendering engine.
+
+Additionally, the [WebTransport API](/en-US/docs/Web/API/WebTransport_API) is expected to replace the WebSocket API for many applications. WebTransport is a versatile, low-level API that provides backpressure and many other features not supported by either `WebSocket` or `WebSocketStream`, such as unidirectional streams, out-of-order delivery, and unreliable data transmission via datagrams. WebTransport is more complex to use than WebSockets and its cross-browser support is not as wide, but it enables the implementation of sophisticated solutions. If standard WebSocket connections are a good fit for your use case and you need wide browser compatibility, you should employ the WebSockets API to get up and running quickly. However, if your application requires a non-standard custom solution, then you should use the WebTransport API.
+


Thank you, I like this a lot better.

wbamberg · 2024-09-06T15:33:47Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+> [!NOTE]
+> To get the example working, you'll also need a server component. We wrote our client to work along with the Deno server explained in [Writing a WebSocket server in JavaScript (Deno)](/en-US/docs/Web/API/WebSockets_API/Writing_a_WebSocket_server_in_JavaScript_Deno), but any compatible server will do.
+
+The HTML for the demo is as follows. It includes informational {{htmlelment("h1")}} and {{htmlelment("h1")}} elements, a {{htmlelment("button")}} to close the WebSocket connection that is initially disabled, and a {{htmlelment("div")}} for us to write output messages into.


Suggested change

The HTML for the demo is as follows. It includes informational {{htmlelment("h1")}} and {{htmlelment("h1")}} elements, a {{htmlelment("button")}} to close the WebSocket connection that is initially disabled, and a {{htmlelment("div")}} for us to write output messages into.

The HTML for the demo is as follows. It includes informational {{htmlelement("Heading_Elements", "h2")}} and {{htmlelement("p")}} elements, a {{htmlelement("button")}} to close the WebSocket connection that is initially disabled, and a {{htmlelement("div")}} for us to write output messages into.

(please double check the syntax for the H2)

Oh darn, thanks for the fixes there.

The syntax worked, but I ended up replacing the h2 macro call with a regular link, as for some reason the link was not showing the angle brackets or in code font.

wbamberg · 2024-09-06T16:14:31Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+> [!NOTE]
+> Backpressure is an issue with the traditional `WebSocket` API — it has no way to apply backpressure, therefore when messages arrive faster than the application can process them, the application will either fill up the device's memory by buffering those messages, become unresponsive due to 100% CPU usage, or both.


In terms of how to use it, it is just automatic for WebSocketStream. I do say "automatically" in the opening paragraph. Do you think I need to be a bit more explicit?

Yes, I do. The doc links to https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Concepts#backpressure, which as I say is hard to understand, but does not make it obvious that the developer has to do nothing for backpressure to work.

I think it would be best to spell this out in the bit about "To read data from the socket, you can continuously call ReadableStreamDefaultReader.read() ...", and will leave a suggestion there.

wbamberg · 2024-09-06T16:17:44Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+To read data from the socket, you can continuously call {{domxref("ReadableStreamDefaultReader.read()")}} until the stream has finished, which is indicated by `done` being `true`:
+
+```js
+while (true) {
+  const { value, done } = await reader.read();
+  if (done) {
+    break;
+  }
+
+  // Process value in some way
+}
+```
+


Here I think is where we should spell out the backpressure thing. Perhaps something like:

Suggested change

To read data from the socket, you can continuously call {{domxref("ReadableStreamDefaultReader.read()")}} until the stream has finished, which is indicated by `done` being `true`:

```js

while (true) {

const { value, done } = await reader.read();

if (done) {

break;

}

// Process value in some way

}

```

To read data from the socket, you can continuously call {{domxref("ReadableStreamDefaultReader.read()")}} until the stream has finished, which is indicated by `done` being `true`:

```js

while (true) {

const { value, done } = await reader.read();

if (done) {

break;

}

// Process value in some way

}

```

Note that the client can control the rate at which it receives data by calling `read()` only when it is ready: if data is arriving faster than the client can read it, the underlying Streams API automatically exerts backpressure on the sender.

(assuming that is true!)

I don't think the point when read() is called has anything to do with backpressure. This is not automatic, but a choice made by the developer in the code?

I've read around this subject a bit, and added the following paragraph after the code snippet:

The browser automatically controls the rate at which the client receives and sends data by applying backpressure when needed. If data is arriving faster than the client can read() it, the underlying Streams API exerts backpressure on the server. In addition, write() operations will only proceed if it is safe to do so.

wbamberg · 2024-09-06T16:51:59Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+  const reader = readable.getReader();
+  const writer = writable.getWriter();
+
+  await writer.write("ping");


You don't have to await to make it work: await just ensures that the promise fulfills before it executes the next line.

I mean, usually I see await being used if you want to make your code behave like synchronous code, for instance if it's returning something you need in the next line:

const response = await fetch(url); const data = await response.json();

(or as we are doing with read(), where we need the read value in the next line).

But in this case we're not, so what's functionally the difference between awaiting and not awaiting, except that we're imposing an ordering when we maybe don't need to.

I suppose awaiting means we can report writeToScreen("SENT: ping");, because we know write() didn't reject, although it's not clear whether not rejecting actually means we sent it, as https://developer.mozilla.org/en-US/docs/Web/API/WritableStreamDefaultWriter/write says:

Note that what "success" means is up to the underlying sink; it might indicate that the chunk has been accepted, and not necessarily that it is safely saved to its ultimate destination.

But then if that is the reason, isn't it better to use try/catch so we can report an error?

So it could say:

try { await writer.write("ping"); writeToScreen("SENT: ping"); } catch(e) { writeToScreen(`Error writing to socket: ${e.message}`); }

...and then there's a use for await.

Ah, maybe it's not worth worrying about.

wbamberg · 2024-09-06T16:52:47Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+slug: Web/API/WebSockets_API/Using_WebSocketStream
+page-type: guide
+status:
+  - non-standard


FWIW this should get added automatically from the BCD. But only in reference pages, not in guide pages.

wbamberg · 2024-09-06T17:02:43Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+            reason: "That's all folks",
+          });
+
+          closeBtn.disabled = false;


Good call; updated.

wbamberg · 2024-09-06T17:04:22Z

files/en-us/web/api/websockets_api/using_websocketstream/index.md

+  wss.close({
+    code: 1000,
+    reason: "That's all folks",


To be pedantic, which I always am, it says "custom code and reason".

files/en-us/web/api/websocket/index.md

wbamberg

👍 thanks Chris!

chrisdavidmills · 2024-09-13T07:07:24Z

👍 thanks Chris!

Likewise, thanks so much for the review Will!

Document WebSocketStream

0440e77

chrisdavidmills requested review from a team as code owners August 22, 2024 09:00

chrisdavidmills requested review from wbamberg and pepelsbey and removed request for a team August 22, 2024 09:00

chrisdavidmills marked this pull request as draft August 22, 2024 09:01

github-actions bot added Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed labels Aug 22, 2024

Add WebSocket interface documentation

fb8a621

github-actions bot added size/l [PR only] 501-1000 LoC changed and removed size/m [PR only] 51-500 LoC changed labels Aug 23, 2024

chrisdavidmills marked this pull request as ready for review August 23, 2024 07:19

Merge branch 'main' into websocketstream

54ab5af

tomayac reviewed Aug 28, 2024

View reviewed changes

chrisdavidmills and others added 11 commits August 28, 2024 18:10

Update files/en-us/web/api/websockets_api/using_websocketstream/index.md

3c8f355

Co-authored-by: Thomas Steiner <[email protected]>

Update files/en-us/web/api/websockets_api/using_websocketstream/index.md

6ca71c9

Co-authored-by: Thomas Steiner <[email protected]>

Update files/en-us/web/api/websockets_api/using_websocketstream/index.md

7a55d73

Co-authored-by: Thomas Steiner <[email protected]>

Update files/en-us/web/api/websockets_api/using_websocketstream/index.md

8f60ee6

Co-authored-by: Thomas Steiner <[email protected]>

Update files/en-us/web/api/websockets_api/using_websocketstream/index.md

a979ad4

Co-authored-by: Thomas Steiner <[email protected]>

Update files/en-us/web/api/websockets_api/using_websocketstream/index.md

1016e40

Co-authored-by: Thomas Steiner <[email protected]>

Update files/en-us/web/api/websocketstream/closed/index.md

f2e04e4

Co-authored-by: Thomas Steiner <[email protected]>

Update files/en-us/web/api/websocketstream/opened/index.md

2c01603

Co-authored-by: Thomas Steiner <[email protected]>

Update files/en-us/web/api/websocketstream/url/index.md

76923cc

Co-authored-by: Thomas Steiner <[email protected]>

Update files/en-us/web/api/websocketstream/websocketstream/index.md

71defc9

Co-authored-by: Thomas Steiner <[email protected]>

make protocol usage consistent ascross example snippets

2a82373

chrisdavidmills changed the title ~~Document WebSocketStream~~ Editorial review: Document WebSocketStream Aug 28, 2024

wbamberg reviewed Sep 4, 2024

View reviewed changes

chrisdavidmills added 3 commits September 6, 2024 08:22

Merge branch 'main' into websocketstream

190b3da

Fixes for wbamberg review comments

bbb9b37

Merge branch 'main' into websocketstream

f72d08d

chrisdavidmills requested a review from wbamberg September 6, 2024 14:30

wbamberg reviewed Sep 6, 2024

View reviewed changes

Fixes for 2nd round of wbamberg review

2c2ceed

chrisdavidmills requested a review from wbamberg September 9, 2024 11:47

wbamberg reviewed Sep 12, 2024

View reviewed changes

files/en-us/web/api/websocket/index.md Outdated Show resolved Hide resolved

typo

7bc83c3

wbamberg approved these changes Sep 12, 2024

View reviewed changes

wbamberg merged commit f56df7c into mdn:main Sep 12, 2024
9 checks passed

chrisdavidmills deleted the websocketstream branch September 13, 2024 07:07

		### WebSocketStream

		The {{domxref("WebSocketStream")}} API is a modern reimagining of WebSocket client-side JavaScript functionality. It is promise-based, and therefore simpler to work with than the traditional {{domxref("WebSocket")}} API in the modern JavaScript scosystem. In addition, it uses the [Streams API](/en-US/docs/Web/API/Streams_API) to handle receiving and sending messages, meaning that socket connections can take advantage of stream [backpressure](/en-US/docs/Web/API/Streams_API/Concepts#backpressure) automatically, regulating the speed of reading or writing to avoid bottlenecks in the application. See [Using WebSocketStream to write a client](/en-US/docs/Web/API/WebSockets_API/Using_WebSocketStream) for more information.


		{{DefaultAPISidebar("WebSockets API")}}{{non-standard_header}}

		The {{domxref("WebSocketStream")}} API is a modern reimagining of WebSocket client-side JavaScript functionality. It is promise-based, and therefore simpler to work with than the traditional {{domxref("WebSocket")}} API in the modern JavaScript scosystem. In addition, it uses the [Streams API](/en-US/docs/Web/API/Streams_API) to handle receiving and sending messages, meaning that socket connections can take advantage of stream [backpressure](/en-US/docs/Web/API/Streams_API/Concepts#backpressure) automatically, regulating the speed of reading or writing to avoid bottlenecks in the application.


		The {{domxref("WebSocketStream")}} API is a modern reimagining of WebSocket client-side JavaScript functionality. It is promise-based, and therefore simpler to work with than the traditional {{domxref("WebSocket")}} API in the modern JavaScript scosystem. In addition, it uses the [Streams API](/en-US/docs/Web/API/Streams_API) to handle receiving and sending messages, meaning that socket connections can take advantage of stream [backpressure](/en-US/docs/Web/API/Streams_API/Concepts#backpressure) automatically, regulating the speed of reading or writing to avoid bottlenecks in the application.

		This article explains how to use the {{domxref("WebSocketStream")}} API to create a simple WebSocket client.

		> [!NOTE]
		> Backpressure is an issue with the traditional `WebSocket` API — it has no way to apply backpressure, therefore when messages arrive faster than the application can process them, the application will either fill up the device's memory by buffering those messages, become unresponsive due to 100% CPU usage, or both.


		The main bulk of our code is contained within the `start()` function, which we define and then immediately invoke. We await the {{domxref("WebSocketStream.opened", "opened")}} promise, then after it fulfills write a message to let the reader know the connection is successful and create {{domxref("ReadableStreamDefaultReader")}} and {{domxref("WritableStreamDefaultWriter")}} instances from the returned `readable` and `writable` properties.

		Next, we `write()` a `"ping"` value to the socket and communicate that to the user. At this point, the server will respond with a `"pong"` message. We await the `read()` of the read message, communicate it to the user, then write another `"ping"` to the server after a timeout of 5 seconds. This continues the `"ping"`/`"pong"` loop indefinitely.

		> [!NOTE]
		> Alternatively, you can use the {{domxref("WebSocketStream.close()")}} method to close a connection, however this is mainly needed if you wish to specify a custom code and reason for the server to report.

	- : An object than can contain the following properties:
	- : An object that can contain the following properties:

	new WebSocketStream(url, options)
	new WebSocketStream(url)
	new WebSocketStream(url, options)

		> [!NOTE]
		> 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 reason for the server to report.

	- : Returns a {{jsxref("Promise")}} that fulfills with an object once the socket connection is successfully opened. The object contains several useful features, including a {{domxref("ReadableStream")}} and a {{domxref("WritableStream")}} instance for receiving and sending data on the connection.
	- : Returns a {{jsxref("Promise")}} that fulfills with an object once the socket connection is successfully opened. Among other properties, the object includes a {{domxref("ReadableStream")}} and a {{domxref("WritableStream")}} instance for receiving and sending data on the connection.

	The WebSocket API is an advanced technology that makes it possible to open a two-way interactive communication session between the user's browser and a server. With this API, you can send messages to a server and receive event-driven responses without having to poll the server for a reply.
	The WebSocket API makes it possible to open a two-way interactive communication session between the user's browser and a server. With this API, you can send messages to a server and receive responses without having to poll the server for a reply.

		- The `WebSocketStream` is a {{jsxref("Promise")}}-based alternative to `WebSocket`. It uses the [Streams API](/en-US/docs/Web/API/Streams_API) to handle receiving and sending messages, meaning that socket connections can take advantage of stream backpressure automatically, regulating the speed of reading or writing to avoid bottlenecks in the application. However, `WebSocketSteam` is non-standard and currently only supported in one rendering engine.

		Additionally, the [WebTransport API](/en-US/docs/Web/API/WebTransport_API) is expected to replace the WebSocket API for many applications. WebTransport is a versatile, low-level API that provides backpressure and many other features not supported by either `WebSocket` or `WebSocketStream`, such as unidirectional streams, out-of-order delivery, and unreliable data transmission via datagrams. WebTransport is more complex to use than WebSockets and its cross-browser support is not as wide, but it enables the implementation of sophisticated solutions. If standard WebSocket connections are a good fit for your use case and you need wide browser compatibility, you should employ the WebSockets API to get up and running quickly. However, if your application requires a non-standard custom solution, then you should use the WebTransport API.

	The HTML for the demo is as follows. It includes informational {{htmlelment("h1")}} and {{htmlelment("h1")}} elements, a {{htmlelment("button")}} to close the WebSocket connection that is initially disabled, and a {{htmlelment("div")}} for us to write output messages into.
	The HTML for the demo is as follows. It includes informational {{htmlelement("Heading_Elements", "h2")}} and {{htmlelement("p")}} elements, a {{htmlelement("button")}} to close the WebSocket connection that is initially disabled, and a {{htmlelement("div")}} for us to write output messages into.

Editorial review: Document WebSocketStream #35548

Editorial review: Document WebSocketStream #35548

Conversation

chrisdavidmills commented Aug 22, 2024

Description

Motivation

Additional details

Related issues and pull requests

github-actions bot commented Aug 22, 2024 • edited Loading

tomayac left a comment

Choose a reason for hiding this comment

chrisdavidmills commented Aug 28, 2024

wbamberg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisdavidmills Sep 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wbamberg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wbamberg left a comment

Choose a reason for hiding this comment

github-actions bot commented Aug 22, 2024 •

edited

Loading

chrisdavidmills Sep 6, 2024 •

edited

Loading