Updating the WebSockets guide

[wbamberg]

This came out of mdn/content#40188, which asks our docs to talk about making WebSocket code bfcache-compatible. This makes sense but I'm not sure noting it in the reference page for WebSocket is the right approach, it feels more like a general usage guideline. Or at least, at a minimum, the usage guides we have for WebSockets should include this guidance.

So my preferred option is to update our usage guides to include this.

The most obvious place to start is Writing WebSocket client applications, but this page is problematic because it claims to be taken from the complete example at https://github.com/mdn/samples-server/tree/master/s/websocket-chat, but that example is very old and not readily runnable.

Another more useful page is Writing a WebSocket server in JavaScript (Deno), which presents a complete minimal client/server application in Deno, and which does run basically out of the box.

So I think what I'd like to do is combine these two pages into a "Using WebSockets" guide, using the Deno example as the basis, but adding bfcache compatibility, and checking the whole thing into dom-examples, so people can run it.

I suppose one drawback is that we wouldn't have a separate "Writing a WebSocket server in JavaScript" page to sit alongside the "Writing a WebSocket server in C#" etc pages we have. I'm not all that keen on these "Writing a WebSocket server in $language" pages for various reasons, but I don't intend to get into that.

[Josh-Cena]

I think we should have a stricter client-server separation: one page for the client, and as many server guides as the number of languages we'd like to cover, and they should be put together for a full client/server interaction. That is to say, Tte Deno page should not implement a client by itself, but should use the client implemented in the first guide (which probably means extracting it into the first guide). I think JS + C# is a good basis; not very sure about the Java one but probably we should too, just in the spirit of "don't remove any information"

[hamishwillee]

Just my two bits ...

@Josh-Cena I disagree, for the reasons that @wbamberg doesn't want to get into:

I'm not all that keen on these "Writing a WebSocket server in $language" pages for various reasons, but I don't intend to get into that.

My take is that the WebSocket responsibilities of a web server are the same for any server, and this is what we want to capture. If we can show that using one language in a way that makes sense, then there isn't any particular need to illustrate the same concepts for other languages - that's a maintenance burden for MDN that doesn't need.
I would be happy to remove all the language specific pages as long as the concepts are retained.

I think a combined topic makes sense, but I don't know if deno is the best language and I haven't looked at the example.
We certainly shouldn't have topics based on defunct examples so a cleanup is needed.

[wbamberg]

If we want a "writing a WebSocket client" page, then it's important to have working code that people can check out and run fairly easily, and that code has to include a server, obviously. And equally obviously, the server has to match up with the client (i.e. serving the correct client-side resources, as well as responding to the WebSocket messages the client is sending). So the easy thing to do is to to have a single directory under dom-examples, which includes the common client code and a server implementation in some language.

And at that point, it's probably better for readers for "writing a WebSocket client" to also talk about the server side, so it can walk through implementing a complete solution, that matches up with the code they can run and inspect. So it becomes "Using Websockets".

There might be more complicated solutions, that include multiple server-sides, and allow readers to choose which server-side tech they want to use for the walkthrough. Apart from figuring out how this would look for users and how we would organize it in dom-examples, it would mean updating the C# and Java examples to match the client. I'm not personally proposing to do this.

Or, and I suppose this might be in line with your suggestion, we could:

• deliver both client and Deno-server together in dom-examples
• keep "writing a WebSocket client" and "writing a WebSocket server in Deno" as separate pages, and in "writing a WebSocket client" tell people they can check out the example from dom-examples if they want to see the client code running.

I'm not really sure this is better though.

I don't know if deno is the best language

I'm suggesting using Deno because having looked at all three "writing a server in $language" pages, the Deno one is by far the simplest, because it has built-in WebSocket support. and because, being JavaScriptish, I am able to understand it. It took me not a lot of time to write a client that's bfcache-compatible and have it working with the Deno server-side.

[Josh-Cena]

A client can be communicating with a 3rd party API, so not everyone writing a client needs to know how the server is implemented. MDN, as primarily a client-side technology documentation, should prioritize client-side use cases. Therefore a separate article purely about using the client-side APIs is imperative.

Your end suggestion, about prioritizing the Deno example and placing it in dom-examples, makes complete sense to me though. The only concern I have is whether we should set up a new repo because Deno will have dependency management and it should look more or less like an actual standalone project.

However I still stand by the point that the other languages' documentation should be kept unless they are out of date and no one is committed to updating them. If they are still functional then readers could be relying on them, and we shouldn't remove valid information. Fundamentally, WebSocket works the same for every server, but the tech stack and the specific library paradigm could be drastically different. This is why we have multiple articles about implementing an HTTP server.

[gilbertococchi]

Thanks everyone for opening this discussion, I am really looking forward to your help to increase developers awareness about the way they've been using WebSocket and the impact it could have on user experience (no BFCache access) if the connection is not handled as expected.

To clarify we are only talking about the aspects related to the JS connection handle from the Browser POV, the aspects I am proposing to increase awareness are:

• close the connection by using pagehide event handler to make the page where WebSocket has been used BFCache eligible.
• [optional but necessary for logic application] restart the WebSocket connection by using pageshow (event.persisted=true) case, otherwise the page will be restored from BFCache and the connection would be closed.

[wbamberg]

I've filed mdn/dom-examples#326 to add a minimal bfcache-friendly example that we can refer to. Would be happy to have your review!

[wbamberg]

Taken care of in mdn/content#40931.