#websockets

Build a Chat App with Node.js and Socket.io ☞ https://morioh.com/p/82f77b634fd7

Switchonyms is not the first of these games I've made. Ever since Diamond Checkers, I've used a 4-character game id as a join mechanism:

With 26 letters and 10 numbers, that's 36 ** 4 possible combinations, all but guaranteeing no overlap between active games.

In my database, or in this case, the local memory's database object, these game ids become parameters that reference the entire game object. In the url, this route becomes a database lookup.

My friend Max told me all the way back with Diamond Checkers that I should stick to letters, to avoid questions about Os and 0s, Is and 1s, etc. - especially with the fancy fonts I find. But I was sure I needed that extra space just in case I got a lot of users...

Listen. ... Okay? Okay, I might have made a mistake. So... for the obvious user experience improvement, I'll go back to my old apps and update them - so enjoy those letters next time you play!

tl;dr: the experience of actual users is more important than the functionality for potential ones; CoColors' 8-character <canvas> ids were even worse; but in general, this Jackbox-esque game id idea is awesome

Esta es una traducción del artículo original publicado en el blog de Mozilla Hacks. Traducción por juliabis. Flash hizo llegar vídeo, animación, sitios interactivos y, sí, anuncios a miles de millones de usuarios durante más de una década, pero ahora se se está marchando. Adobe dejará de soportar Flash para el año 2020. Firefox ya no lo soporta “fuera de la caja”, y Chrome tampoco. ¿Qué es lo…

Oh and there’s a hook for player authentication as well. It is up to the dev how/if they want to authenticate though. I need another day to clean/up test before release.

There is no formal TLS / SSH / WSS support, but it is easily added if desired.

It came out pretty interesting in the end. An instance can transfer a player to another address and transfer some data along with the player. The instances actually speak to each other before the player gets transferred. The instances do this via the same websockets that the players use, they just identify themselves with a password. The source instance generates a transferRequest, and the target instance responds with a transferResponse (or fails under a variety of circumstances). If the transfer is accepted, then the source instance sends a transfer message to the client which goes ahead and connects to the target instance, bearing a code that identifies the client. The target instance recognizes the client upon arrival, and gains access to the data that was initially transferred from the other server. Thus nothing from the client is ever trusted -- its the servers who have a conversation with each other, and they merely give the client a receipt (a reference to the conversation) which does not divulge any details to the client. This follows the security model in nengi of making the servers the authority on the game state.

Transfers are pretty quick, taking slightly longer than the round-trip latency between the machines. Transfers are asynchronous.

This enables some really basic but scalable functionality -- such as having a entrance to a dungeon, building, city, portal, etc. where the end point may reside on another server... be that another physical machine or just another instance running in another thread on the same machine. It also offers a way to secure instances, because the game logic can define and enforce rules about who can enter which instance. Lots of features rely on controlling player access (pvp arenas, party-based instances, games that require membership, etc.)

This is a big one: a real-time, in-person, multiplayer mobile word game. I call it Switchonyms.

There's a lot to talk about, more than I can put in these three posts, so I'm going to focus on the core components that make this project unique. But for those interested: this code is raw nodeJS, with web socket(s) powering the real-time back-and-forth of a fast-paced party game about guessing words. 

Let's say your friends are trying to guess the word on your screen. You can't say it, but you can give clues that hopefully spur someone else to say it... but what if you get stuck? Well, check out this switch <button> (top-right):

This triggers a socket.send() that requests a new word from the server, where I've got a big dictionary of nouns, verbs, and adjectives - for rounds 1, 2, and 3, of course.

Since each list is just a giant array, I can write a function to select a random word out of it:

Then update the global game object (making sure that word isn't already there)...

...and send that word back to the player...

...which updates the view, by both changing what word is visible and setting the style of the switch <button>:

Originally, switching meant swapping words between players - but that just meant someone else was stuck with it! After lots of play-testing, this is much, much better. Code-wise, a similar process happens when a word is successfully guessed... but more on that in part 2!

tl;dr: websockets allow for instant two-way communication between client and server; build helper functions, like chooseRandom(), for things you do often; use arbitrary attributes as CSS selectors

Solid reconnection logic on the backend doesn't matter much if the interface doesn't tell users what's happening while it runs. These are five UX patterns we reach for at 137Foundry whenever we're building a live dashboard or collaborative feature, patterns that keep users oriented during the seconds or minutes a connection is quietly recovering in the background.

1. A visible connection-state indicator

Not a toast that flashes once and disappears, a persistent, small indicator (a dot, a label, a subtle color change) somewhere consistent in the interface that reflects one of three states: connected, reconnecting, disconnected. Users glance at it the same way they glance at a wifi icon on their phone, quickly and without thinking, and it answers the question "can I trust what I'm looking at right now" before they even have to ask it out loud.

The Nielsen Norman Group's writing on system status visibility covers the broader usability principle this pattern is built on, and it applies just as directly to real-time connection state as it does to any other kind of background system status.

2. Timestamping stale data explicitly

If a dashboard stops updating, showing "last updated 2 minutes ago" next to the data is far more honest than showing the data with no context at all. Users can make their own judgment about whether two-minute-old data is fine for their purposes or not, but only if the interface actually tells them the data is old instead of presenting it as fresh.

3. Disabling actions that assume a live connection

If a feature depends on real-time acknowledgment, sending a chat message, submitting a collaborative edit, confirming a trade, disable the affected controls or clearly mark them as queued while disconnected, rather than letting users act into a void and wonder later whether anything actually happened on the other end.

4. A manual retry option after enough automatic attempts fail

Automatic reconnection with backoff is the right default, but after several failed attempts, our threshold is usually five or six, give the user a manual "try again" button instead of leaving them staring at an indefinite spinner with no way to intervene. Sometimes the underlying issue needs a page reload or a network switch on the user's end, and a manual control communicates that possibility instead of implying the app will eventually sort itself out on its own.

5. Optimistic local state with a rollback path

For actions taken while reconnecting, queued messages, in-progress edits, show them in the UI immediately as pending, then reconcile once the connection returns and the server confirms or rejects them. Silently discarding a user's in-progress action because the network hiccuped is one of the fastest ways to lose someone's trust in a product, especially if it happens more than once.

A pattern we almost shipped and pulled back

Early on, we tried a version of the connection-state indicator that auto-hid itself after a few seconds once the connection recovered, on the theory that users didn't need to keep seeing a "reconnected" confirmation once things were back to normal. In practice, users who'd noticed the earlier "reconnecting" state and then glanced away came back to a UI that looked exactly like it had before anything happened, with no way to confirm whether the gap had actually been resolved or whether they were still looking at stale information. We ended up keeping a brief, deliberate "reconnected, you're up to date" confirmation state for a couple of seconds rather than snapping straight back to the normal connected indicator, specifically to close that loop for anyone who'd noticed the disruption in the first place.

Photo by Walls.io on Pexels

The lesson generalized past this one feature: any state your UI shows during a failure needs a matching, equally visible state confirming resolution. An interface that announces trouble loudly and then recovers silently trains users to distrust the "everything's fine" state just as much as the "something's wrong" one, since they have no way to tell the difference between actual recovery and the indicator simply timing out. It's a small detail, but it's the kind of detail that separates a product that feels trustworthy under real-world network conditions from one that only feels trustworthy in a demo on office wifi.

How we decide which patterns a given feature actually needs

Not every real-time feature needs all five patterns at once. A internal analytics dashboard viewed by a handful of employees can probably get away with just the connection-state indicator and stale-data timestamping, since the cost of someone glancing at slightly outdated numbers for a minute is low. A collaborative editing feature or anything involving money or irreversible actions needs the full set, including optimistic state with a real rollback path, because the cost of a silently lost or duplicated action is much higher. We size the UX investment to the actual cost of getting it wrong for that specific feature, rather than applying a single fixed checklist to every real-time surface in a product regardless of stakes.

Where these patterns live in our own process

We keep this list as a literal design review checklist for any new real-time feature, reviewed before the first line of frontend code gets written, not retrofitted after launch once someone notices the UX feels confusing during an outage. Retrofitting is possible but always costs more, both in engineering time and in however much user trust got spent during the period the feature shipped without it.

What we measure to know if the patterns are actually working

We track a simple support-ticket tag for anything mentioning stale data, a frozen dashboard, or a lost action, and watch the rate of that tag over time as we roll these patterns out to a given feature. A dropping rate after we add the connection-state indicator or the optimistic-with-rollback pattern to a specific surface is a much better signal than any amount of internal confidence that the UX is now "handled." User-reported confusion is the ground truth here, not whether our own team finds the reconnecting state adequately communicated.

Making these patterns actually reliable

None of these patterns require the backend to be perfect. They require the frontend to be honest about what the backend currently knows, which is a genuinely different design goal than making the reconnection process invisible. Trying to hide reconnection entirely from the user is usually the wrong instinct: a brief, clearly communicated "reconnecting" state builds more trust than a UI that pretends nothing happened, especially once a user notices the data was stale for longer than the interface admitted.

Material Design's guidance on communicating offline states is worth a look if you want a broader design-system perspective on these same ideas applied outside the specific case of WebSockets, and it lines up closely with the patterns above even though it wasn't written with real-time dashboards specifically in mind.

Every time we at 137Foundry roll out a new backend version for a client's real-time dashboard, we cause the exact failure our own reconnection code is designed to survive. The deploy cycles connections. Every client connected to the instance being replaced gets disconnected within the same few seconds. If our backoff and jitter logic weren't doing their job properly, we'd be reproducing a self-inflicted outage every single release, which is not a great look when the whole point of the feature is reliability.

What actually happens during a rolling deploy

A rolling deploy takes backend instances out of rotation one at a time, drains their connections, and replaces them with new code. From the client's perspective, this looks identical to any other unexpected disconnect: the socket closes, no warning, no context about why. Every client connected to the instance being replaced gets dropped at roughly the same moment, which is a meaningfully different scenario than a single user's connection dropping in isolation.

If every one of those clients used a fixed retry delay, they'd all reconnect in the same instant, hit the next instance in rotation simultaneously, and potentially trigger the exact same cycle again if that instance is also mid-drain from the same deploy. We've seen this happen on other systems before we tightened our own jitter implementation, a self-inflicted retry storm caused entirely by deploy tooling instead of any actual outage in the underlying infrastructure.

The fix we actually ship

Our reconnect logic uses exponential backoff with roughly 25 percent jitter on every attempt, capped around 20 seconds. During a normal deploy, this spreads client reconnection attempts across a multi-second window instead of a single spike, which is the difference between a deploy nobody notices and a deploy that looks like a production incident to whoever's watching the dashboards at the time.

We also stagger our own rolling deploys deliberately, cycling instances with a delay between each one specifically so client reconnection windows don't overlap across multiple instances going down close together. It's a small operational habit that costs us a few extra minutes per deploy and saves us from ever having a routine deploy masquerade as a customer-facing incident.

The part that actually took the longest

The part that took longest to get right wasn't the backoff curve itself, that's a well-understood pattern with plenty of reference implementations. It was making sure our sequence-numbered replay buffer correctly backfilled whatever a client missed during the drain window, so a dashboard reconnecting after our own deploy shows the exact same data it would have shown if the deploy had never happened at all. Getting the replay window wrong in either direction, too short and you drop legitimate updates, too long and you risk replaying stale data as if it were current, took several iterations to tune correctly against our own production traffic patterns.

We also learned the hard way that health checks matter here too. An instance that's draining connections but still reports healthy to the load balancer for a few extra seconds will keep receiving new connection attempts it's about to reject, which just adds more reconnection churn to an already busy moment. Coordinating the drain signal with the load balancer's health check removed a meaningful chunk of unnecessary reconnect attempts during every deploy.

The monitoring change that finally gave us confidence

For a while, we only found out our reconnection handling was working because nobody complained, which isn't a great signal on its own since it's just as consistent with nobody looking. What actually changed things was adding a specific metric: the count of active WebSocket connections per instance, graphed alongside our deploy markers. A healthy deploy shows a smooth, staggered drop and recovery in that graph as instances cycle one at a time. A deploy with a reconnection storm problem shows a sharp cliff followed by a slow, uneven recovery, and you can see it on the graph before a single customer notices anything on their end.

Photo by AMORIE SAM on Pexels

We also added an alert on the specific rate of new connection attempts per second, since a retry storm shows up there first, well before it shows up as a customer complaint. Catching it in that metric during a deploy window, rather than in a support ticket an hour later, is the difference between a two-minute non-event and an actual incident review.

Why this matters beyond our own infrastructure

If you're shipping real-time features and your own deploys are the thing triggering your reconnection storms, you're not doing anything wrong, it's an expected side effect of rolling deploys on any stateful, long-lived connection like a WebSocket. The fix isn't avoiding deploys or freezing your release cadence. It's making sure the reconnection path you built for network failures also holds up cleanly for the failures you cause on purpose as part of normal operations.

The general reference on rolling deployment strategies from the Kubernetes documentation covers the orchestration side of graceful connection draining if you're running on that kind of infrastructure, and it's worth reading even if you're not using Kubernetes directly, since most managed platforms implement some variant of the same drain-then-replace pattern.

What we'd tell a team just starting out

If you're setting this up for the first time, don't try to build the deploy dashboard and the staggered rollout and the jitter tuning all in the same sprint. Ship jitter first, it's the highest leverage, lowest effort change. Add the connection-count metric next, since it gives you visibility into whether the jitter is actually working before you invest further. Staggered rollout timing and a dedicated deploy dashboard are refinements worth adding once you've confirmed the basics are solid, not prerequisites to shipping reconnection logic that works.

A tool we added specifically for this

We eventually wired a small Grafana dashboard specifically for deploy windows, showing active connection count, new-connection rate, and resync-required rate side by side with our deploy markers on the same timeline. Having all three on one screen during a release turned "does this deploy look normal" from a gut-feel judgment into something anyone on the team could check in ten seconds, including someone who wasn't the original author of the reconnection code.

One more habit: deploying during genuinely quiet windows

None of the engineering above removes the value of a boring operational habit: we still schedule our own riskier real-time deploys during lower-traffic windows when we have the choice. Fewer concurrently connected clients means a smaller reconnection wave even in the worst case, and it gives us a bigger margin for error while we're still validating a new release candidate against production traffic. The jitter and staggered rollout handle the technical side of the problem; picking a quieter deploy window is the low-effort, high-value habit that reduces blast radius on top of it.