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

TheWebSocketStream API is a modern reimagining of WebSocket client-side JavaScript functionality. It is promise-based, and therefore simpler to work with than the traditionalWebSocket 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). Theexplainer 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: theWebSocket interface and theWebSocketStream interface.

• TheWebSocket 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)
• TheWebSocketStream is an alternative toWebSocket, 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 eitherWebSocket orWebSocketStream.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.

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.

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

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 athttps://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Concepts#backpressure says:

To use backpressure in aReadableStream, we can ask the controller for the chunk size desired by the consumer by querying theReadableStreamDefaultController.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 theWebSocket page.

In terms of how to use it, it is just automatic forWebSocketStream. 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 tohttps://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 callReadableStreamDefaultReader.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.

Why await here?

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

We say a few times that it's preferable to useabort(), 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 codeand reason".

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

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.

also experimental?

OK, makes sense. I've also added it to theWebSocketStream 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.

updated

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.

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.

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

Agreed. I've de-noted it.

fixed - ta!

Good call; updated.

Again I don't think this is a note.

Again, de-noted.

re "sent by the server", same comment as in theclosed 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"

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.

"several useful features" again.

Same change made here.

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 theprotocols option of theWebSocketStream() 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, inprotocols, 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 theprotocols option of theWebSocketStream() 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).

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 theclosed example.

(not necessarily event-driven)

Sounds reasonable. Updated to use your wording.

Thank you, I like this a lot better.