The previous lesson left Nómada Tasks connected and robust, but with a limit that no improvement to fetch can solve: the browser only finds things out when it asks. If Iván drags a task to "under way" from the workshop, Marta's board will keep showing the old state until she refreshes. Asking every five seconds means wasting battery and bandwidth to hear "nothing new" 95 % of the time. What is needed is to reverse the initiative: to let the server speak first. That is a WebSocket, a permanent, bidirectional connection through which messages travel both ways the moment they happen. In this lesson you will compare the four real-time techniques, understand the handshake that turns an HTTP request into a persistent channel, master the browser's WebSocket API, design a small message protocol, solve reconnection and simultaneous-editing conflicts, and write js/data/realtime.js with the BoardChannel class.

1. When request-response is not enough
2. The four real-time techniques
3. The protocol: from handshake to persistent channel
4. The browser's WebSocket API
5. readyState and the life cycle
6. Sending and receiving: send, message and JSON
7. A message protocol for Nómada Tasks
8. Closing properly: close(code, reason)
9. Reconnection with exponential backoff
10. Heartbeat: detecting zombie connections
11. Queuing messages while there is no connection
12. Integrating with the view's CustomEvents
13. Conflicts: two people, one task
14. Security: wss, authentication and validation
15. Nómada Tasks: js/data/realtime.js
16. A minimal test server
17. Common Mistakes and Tips
18. Exercises
19. Conclusion

HTTP is a request and response protocol: the client asks, the server answers, the connection ends. That model is perfect for loading a page or saving a form, and it is structurally incapable of one thing: letting the server speak up on its own initiative.

The cases where that hurts are recognizable:

• A shared board where three people move cards at once.
• A chat, where waiting five seconds for a message to appear is unacceptable.
• A live metrics dashboard, notifications, stock prices, a multiplayer game.
• A collaborative editor, where you see the other person's cursor.

In Nómada Tasks the scenario is concrete: Marta has the board open on the big screen in the room. Iván, from the workshop, marks the task "Carpentry workshop quote" as under way. The right behavior is for the card to move on Marta's screen, on its own, in under a second, without anyone pressing anything.

Before choosing WebSockets it is worth knowing what the alternatives are, because a simpler one is often enough.

Two comparisons worth being clear about:

Polling versus WebSocket, in numbers. Polling every 5 seconds is 720 requests per hour per user. Each one drags along complete HTTP headers (cookies, User-Agent, Accept…): easily 1 KB out and another back even when there is no news. That is over 1 MB an hour per person to say nothing. A WebSocket pays the cost of the handshake once and after that each message is a few bytes of frame header.

SSE versus WebSocket. SSE is underrated. It is plain HTTP —it goes through proxies without trouble—, it reconnects on its own and it is trivial to implement on the server. Its limitation is that the client cannot send on the same channel: for that you use fetch separately.

The decision rule: if you only receive, SSE. If you also send frequently and need low latency both ways, WebSockets. Nómada Tasks is in the second case: Marta and Iván do not just look, they also move cards.

A WebSocket starts life as an HTTP request. That is the key to its design: it reuses port 443 and passes through existing infrastructure.

The points that matter:

• 101 Switching Protocols is the code that authorizes the switch. It is the only 1xx you will see in your life as a frontend developer, and it already appeared in the table in 07-02.
• After the 101 there is no more HTTP. No verbs, no paths, no status codes, no per-message headers. Just data frames in both directions.
• The schemes are ws:// and wss://, analogous to http:// and https://. wss is WebSocket over TLS.
• It is full-duplex: both ends can send at any moment, without taking turns and without one message being the "response" to another. That absence of request-response correlation is the biggest mental shift compared with fetch.
• The connection is stateful. The server keeps an object per connected client, which complicates horizontal scaling: two servers behind a load balancer do not share connections without help (Redis, a message bus…). It is a real cost you need to know about before choosing.

The API is small: one constructor, four events, two methods and a handful of properties.

Three warnings right from the start:

• The constructor connects right away. There is no .connect(). If you register the listeners too late, you can miss the open. Register them on the line right after the constructor, always.
• The error event does not say what happened. It is a security restriction, just like the generic CORS TypeError in 07-02. The useful diagnosis comes in the close that follows it, with its code.
• After an error a close always arrives. Do not put the reconnection logic in the error: it would run twice. Put it in the close.

The beginner's mistake is sending right after creating the socket:

You have to wait for the open, or check the state:

And one detail that gets forgotten: a closed socket does not reopen. CLOSED is terminal. Reconnecting means constructing a new WebSocket, exactly as an aborted AbortController is not reused (07-03).

send() accepts text or binary, but not objects. As in fetch and in localStorage, the serialization is yours to do:

And on receipt, event.data is always text (or binary), never an already-parsed object:

That try/catch is not paranoia: an open channel receives whatever the server sends, and an uncaught parse error breaks the handler and can leave the channel useless.

For binary data, binaryType decides what you get:

In Nómada Tasks everything is JSON: the volume is tiny and readability while debugging is worth far more than a few bytes.

Here lies the difference between a WebSocket that works and one that becomes unmaintainable. HTTP gave you structure for free (verb, path, status). A WebSocket is a pipe of bytes: you define the structure, and it has to be defined before writing any code.

The minimal format that works well:

The project's complete catalog:

Four protocol design rules that are always worth following:

• One type per message, always present. The handler is a switch on type, or an object of functions indexed by type; never a chain of ifs that guesses from the shape of the payload.
• Version the protocol, just as you versioned the localStorage format in 07-01. A v: 1 field in the subscribe will let you change format without breaking old clients.
• The payload must have the same shape as the REST API. That way Task.fromJSON works for both routes, and you do not maintain two models.
• Reuse the names of your CustomEvents. 'task:updated' on the socket and 'task:changed' in the DOM: the translation is one line and the vocabulary is a single one.

Close codes are a standard vocabulary, and knowing how to read them is what turns "it does not work" into a diagnosis:

1006 is the one you will see most: it means "it got cut off and nobody said goodbye" —wifi down, laptop suspended, a proxy that killed the idle connection. It is the signal to reconnect.

The 4000-4999 range is reserved for you, and it is worth using:

Two final details: event.wasClean tells you whether there was a closing handshake; and the reason is limited to 123 bytes, so it is a label, not an explanation.

A WebSocket goes down. The workshop wifi flickers, the phone switches from wifi to mobile data, the laptop suspends, a proxy cuts idle connections after 60 seconds. A serious application assumes the connection will be lost and reconnects on its own.

The technique is the same as in 07-03: exponential backoff with jitter. Reconnecting immediately in a loop is an effective way of taking down your own server when it restarts and a thousand clients come back at once.

The resulting sequence: 500 ms, 1 s, 2 s, 4 s, 8 s, 16 s, 30 s, 30 s… plus the jitter. Fast when it is a flicker, calm when the server is really down.

Two improvements that make the difference:

And a product decision: when you give up, say so. A banner reading "No connection to the board — Retry" with a button is infinitely better than retrying silently forever or pretending everything is fine.

There is a particularly treacherous failure: the connection looks open —readyState is 1— but nothing arrives. It happens when a NAT router or a proxy drops the connection without telling either end. The browser has no way of knowing, and your board sits frozen with no error at all.

The solution is a heartbeat: sending a periodic ping and waiting for a pong. If the pong does not arrive in time, the connection is declared dead and reconnected.

Two notes for context. The WebSocket protocol has native ping/pong frames, but the browser API does not expose them: you cannot send them or listen for them from JavaScript. That is why the heartbeat is implemented in your own message protocol. And the interval matters: a value between 20 and 30 seconds keeps the connection alive against proxies that cut off after a minute, without draining the battery.

Marta marks a task as done just as the socket is reconnecting. Without a queue, that change is silently lost, which is the worst possible outcome.

Four decisions that have to be made consciously:

• A cap on the queue. Without a limit, a long disconnection ends up eating memory. Fifty messages is a reasonable cap; beyond that, drop the oldest.
• Deduplicate per resource. If Marta changes the status of task 6 three times, only the last one matters. A queue that collapses messages with the same type + payload.id avoids sending irrelevant history.
• Persist it or not. An in-memory queue dies on reload. If the changes are valuable, store it in localStorage with the repository from 07-01.
• Return whether it went out or not. The return false lets the view mark the card as "pending sync", which is the honest thing to do (07-03).

Here it slots cleanly into what you have already built. The channel does not know the view: it translates incoming messages into CustomEvents on document, and whoever wants to listen, listens. It is exactly the decoupling from 06-04.

And in the view, without a single line that knows WebSockets exist:

There you can see the value of the three previous lessons together: the key-based reconciliation from 06-06 makes the card update without flickering or losing focus, and the repository from 07-01 keeps the local copy in sync.

That if (message.meta?.sender === this.#sender) return deserves an explanation. The server forwards every change to all clients, including the one that originated it. If you applied your own echo, the card you already moved optimistically would flicker or revert to an intermediate state. Filtering by sender avoids it.

The problem is not technical, it is a product problem, and it appears as soon as there are two people. Marta changes the priority of task 6 to "medium" in the same second in which Iván changes it to "low". What is left?

Last write wins is acceptable when the changes are atomic and infrequent, and it is what most simple applications do. But it loses data without warning, and on a work board that breeds distrust: "I set it to high, who changed it?".

The sane option for Nómada Tasks is optimistic version control, the real-time equivalent of HTTP's ETag / If-Match:

And on the client, a conflict is handled without losing anybody's work:

The golden rule: a conflict detected and shown is always better than a change silently lost. And an important warning: the version is controlled by the server, never by the client. If the client could decide the version, the mechanism would be worthless.

WebSockets have a security profile of their own, and three non-negotiable rules.

Always use wss://. Over ws:// everything travels in the clear: messages, tokens, data. What is more, a page served over HTTPS cannot open a ws:// —the browser blocks it as mixed content— so in production it is not optional.

Authenticate the connection, and be careful how. The WebSocket constructor does not accept headers: you cannot set Authorization: Bearer. The real options:

The cleanest option is usually the third: connect, authenticate with the first message and have the server close with 4001 if a valid credential does not arrive within a few seconds.

ALWAYS validate on the server. This is the most important one and the most ignored. An open WebSocket is a channel through which the client can send whatever it likes, and anybody can open one with a single line from the console. Everything that comes in through the channel is untrusted input, exactly like a form:

• Check authorization on every message, not just at connection time. Iván being allowed to see the board does not mean he may delete Lucía's tasks.
• Validate the shape and the content of every payload. The model's rules R1-R10 are applied on the server, not just in the browser.
• Check the origin in the handshake: the browser sends the Origin header, and the server must reject the ones it does not recognize. WebSockets are not subject to the same-origin policy of CORS, so without this check any website could connect using the user's cookies. That attack has a name: Cross-Site WebSocket Hijacking.
• Limit message size and frequency (rate limiting): a malicious client can try to exhaust the server's memory.
• Never paint content that arrived through the channel with innerHTML. It is another user's input, and the XSS from 06-02 is lying in wait just the same.

And the compliance warning that runs through the whole module: a real-time channel carrying real personal data (names, locations, messages between people) falls within the scope of data protection regulations, with obligations around encryption, minimization and retention. Marta, Iván and Lucía are fictional; your users are not.

All together now, in a class with the same philosophy as the rest of the data/ layer: it does not know the DOM, it does not know the view, it only translates between the server and the application's events.

And its use in the application:

Notice that the class extends EventTarget: that lets it emit its own events ('state') with the same API as any DOM element, without depending on document. It is a very useful pattern for service objects.

To practice you need a server. With Node and the ws library, just enough for the board to work:

And on the client, new BoardChannel('ws://localhost:8080'). Open two tabs with the application, move a card in one and watch it move in the other: that is the moment when you understand what all of this is for.

This server is a teaching toy. It is missing absolutely everything from section 14: authentication, per-message authorization, validation of the rules R1-R10, Origin checking, size and rate limits, and persistence. Do not deploy it.

To test the client without writing a server there are public echo services such as wss://echo.websocket.org or wss://ws.postman-echo.com/raw, which return whatever you send them. They are useful for verifying the connection, the reconnection and the message format, not the board logic.

• Sending before the open. readyState is CONNECTING and send() throws InvalidStateError. Wait for the event or queue it.
• Trying to reopen the same socket. CLOSED is terminal. Reconnecting means constructing a new WebSocket.
• Putting the reconnection in the error handler. After an error a close always arrives; you would reconnect twice. It goes in close.
• Reconnecting without exponential backoff. When the server restarts, a thousand clients in a loop will bring it down again.
• Reconnecting after a 1000 or a 4001. The first was a requested close; the second, a credentials rejection. Insisting fixes neither.
• Not implementing a heartbeat. The zombie connection is the hardest failure to diagnose: everything "works" and nothing arrives.
• Passing objects to send(). They become '[object Object]'. Always JSON.stringify.
• Parsing without try/catch. A corrupt message breaks the handler and can leave the channel useless.
• Applying the echo of your own messages. It causes flicker and visible intermediate states. Filter by meta.sender.
• Using ws:// in production. Everything travels in the clear and the browser blocks it from an HTTPS page.
• Trusting what comes in through the channel. It is user input. Validate on the server, and on the client never paint it with innerHTML.
• Forgetting to close when leaving the page. It leaves connections hanging on the server. Use pagehide.
• Tip: look at the frames in DevTools. Network → WS filter → Messages tab: you will see every message sent and received with its timestamp. It is the main diagnostic tool.
• Tip: always show the connection state. A green/amber/red dot with text costs ten lines and stops the user thinking the application is broken.
• Tip: test by turning the wifi off. It is the only way of knowing whether your reconnection, your queue and your heartbeat really work.
• Tip: if you only receive, consider SSE. It reconnects on its own, goes through proxies and is far less code.

Exercise 1 — Queue with deduplication and persistence. Extend the BoardChannel queue so that: (a) if two messages with the same type and the same payload.id get queued, only the last one is kept; (b) the queue is stored in localStorage under 'nomada:queue:v1' every time it changes, and is restored when the channel is constructed; (c) messages more than an hour old (according to meta.ts) are discarded when flushing, because resending a very old change can trample somebody else's more recent work.

Exercise 2 — Accessible connection indicator. Write connectIndicator(channel, element) that reflects the channel's state (connecting, open, closed, gaveUp) in a DOM element, with readable text, a data-state for the CSS and aria-live="polite" so it is announced. It must also show how many messages are pending in the queue when there is no connection, and offer a "Retry" button only in the gaveUp state that resets the attempts and connects again. Use { signal } so everything can be disconnected in one go.

Exercise 3 — Conflict resolution with versions. Implement applyRemoteChange(board, task, version) that applies a received change only if its version is greater than the one already held, and returns 'applied' | 'ignored' | 'conflict'. It counts as a conflict when the remote version is lower than the local one (our change is newer and the server does not know about it yet). Add sendWithVersion(channel, task) that includes baseVersion and, on an error message with code: 'conflict', shows the user the two options instead of deciding on its own.

Solution 1

Deduplicating by type:id is what stops you resending five status changes for the same card when only the last one matters. And discarding by age is a product decision disguised as code: a change from three hours ago should almost never overwrite the current state, and if it did, it would be the worst kind of data loss.

Solution 2

The signal lets you unmount the whole indicator with a single abort(), exactly as you learned in 07-03. And role="status" with aria-live="polite" makes the state change announce itself without interrupting: losing the connection is relevant information for someone who cannot see the colored dot too.

Solution 3

The essential thing is not the algorithm but the design decision: the code does not choose on the user's behalf. When there is a real conflict, it is shown, with the two versions and two buttons. The 'ignored' case matters just as much: without it, the echo of a change you already applied would cause an unnecessary repaint and, with optimistic UI in the mix, a visible flicker.

The Taller Nómada board is alive now. You know why the request-response model is not enough —the server cannot speak first— and you know the four techniques that solve it, with the criteria for choosing: polling when latency does not matter, long polling when compatibility rules, SSE when you only receive (it reconnects on its own and is far less code) and WebSockets when you need both directions with low latency. You understand the protocol: the HTTP handshake with Upgrade and the 101 Switching Protocols, the ws:// and wss:// schemes, the full-duplex channel where there are no longer verbs or status codes, and the real cost it entails —the server keeps state per connection, and that complicates scaling.

You have mastered the API: the constructor that connects immediately, the four events, readyState with its four values and the rule that CLOSED is terminal —reconnecting means building a new socket—, send() that only accepts text or binary, event.data that never arrives parsed, and close(code, reason) with its vocabulary of codes, from the clean 1000 to the 1006 that screams "reconnect" and the 4000-4999 range that is yours. You have designed a message protocol with type, payload and meta, because a WebSocket is a pipe of bytes and the structure is yours to put in; and you have aligned it with the names of the CustomEvents from 06-04 so there is a single vocabulary.

You know that a real connection drops, and you have the three defenses: reconnection with exponential backoff and jitter, which does not insist after a 1000 or a 4001; a heartbeat ping/pong with a watchdog to catch the zombie connection the browser does not detect; and a message queue with a cap, deduplication and discard-by-age so that a change made offline is not silently lost. You know how to integrate the channel with the view without coupling them —the channel emits CustomEvents, the view listens and reconciles by data-id as in 06-06, the repository from 07-01 keeps the local copy up to date— and to filter out the echo of your own changes by meta.sender so the optimistic UI from 07-03 does not flicker. And you know that conflicts are a product problem: last write wins loses data silently, while optimistic version control detects them and lets the person decide, which is always better.

On security three rules are engraved: wss mandatory, real authentication —remembering that the constructor does not accept headers and that a token in the URL ends up in the logs—, and above all always validate on the server, checking the Origin in the handshake, because WebSockets are not subject to the same-origin policy and without that check any website could connect with your user's credentials.

With js/data/realtime.js and its BoardChannel, Nómada Tasks is a connected, robust and collaborative application. It has one big weakness left, and it is the most everyday one of all: it depends entirely on having a network. If Iván goes down to the screen-printing storeroom, where the wifi does not reach, the application does not start: the HTML, the CSS and the ES modules live on the server, and without a connection the browser has nothing to load. The localStorage copy is there, but nobody can read it because the page does not even open. To cross that boundary something different is needed: a process that lives outside the page, that intercepts network requests before they go out and knows how to answer them from a cache. That is Service Workers and Progressive Web Apps (PWAs), where Nómada Tasks will learn to work offline and to install itself on the device like any other application.