skip to content

After a Node.js WebSocket chat server moves to one cluster worker per core, why do users get logged out and miss room messages, and what fixes it?

level: seniorimportance: must knowfreq 62%

answer

  1. N processes, N heaps
  2. no routing logic in Node
  3. a socket stays on its worker
  4. shared store, relay via primary

basics

~20 s

Each cluster worker is a separate process with its own memory, and Node routes connections without regard to who holds what. Sessions, room lists and counters split N ways; move sessions to a shared store and relay broadcasts between workers.

solid answer

~40 s

Cluster workers are separate processes, so an in-memory session `Map`, room list or rate-limit counter exists once per worker. The docs say Node provides no routing logic: round-robin hands each new connection to the next ready worker, so a user who logged in on worker 2 is unknown when their next connection lands on worker 5. A WebSocket stays on the worker that accepted it, so a broadcast loop reaches only that worker's sockets. The fix is to keep per-user state out of process memory, in a shared store or a signed token, and to relay room messages between workers, for example through the primary with `process.send()` and `worker.send()`. Per-worker caches stay acceptable only where staleness and N-fold memory are tolerable.

code

javascript · 31 lines
javascript
import cluster from 'node:cluster';
import process from 'node:process';

if (cluster.isPrimary) {
  for (let i = 0; i < 3; i++) cluster.fork();

  // Relay a chat message from one worker to every other worker.
  cluster.on('message', (sender, msg) => {
    if (msg?.type !== 'chat') return;
    for (const worker of Object.values(cluster.workers)) {
      if (worker !== sender) worker.send(msg);
    }
  });

  setTimeout(() => cluster.disconnect(), 1000);
} else {
  const id = cluster.worker.id;
  // Stand-in for writing to the WebSocket clients this worker holds.
  const deliverLocally = (msg) =>
    console.log(`worker ${id} delivers "${msg.text}" from worker ${msg.from}`);

  process.on('message', (msg) => {
    if (msg?.type === 'chat') deliverLocally(msg);
  });

  if (id === 1) {
    const msg = { type: 'chat', from: id, text: 'hello room' };
    deliverLocally(msg); // clients connected to this worker
    process.send(msg); // clients connected to the other workers
  }
}

go deeper

for a junior

Recall that each cluster worker has its own memory, so a variable set in one worker is not visible in another.

for a middle

Explain how round-robin connection handoff plus per-process memory produces random logouts and partial room broadcasts.

for a senior

Inventory process-local state before adding workers, sort it into shared, per-worker or dropped, and test with several workers.

for a principal

Judge where shared state should live and what it costs, knowing a per-host relay will not carry the design past one machine.

## The scenario A chat server runs as one Node process. It keeps login sessions in a `Map`, keeps each room's member list in memory, and broadcasts a message by looping over the WebSocket connections in that room. It works. Then the team adds the cluster module and forks one worker per core. Overnight, users are logged out at random, some people in a room stop seeing messages, and a rate limit stops limiting. Nothing in the code changed. What changed is that there are now **N processes**, and each has its own memory. ## Why each symptom appears **Each worker is a separate process with its own V8 heap.** A module-level `Map` is created once per worker, so there are N independent copies. The Node docs warn about this directly: Node.js does not provide routing logic, so an application should not rely too heavily on in-memory data objects for things like sessions and login. - **Random logouts.** The login request arrived on one connection, which the primary handed to, say, worker 2, so worker 2's `Map` holds the session. The next page load opens a new connection, round-robin hands it to worker 5, and worker 5 has never heard of that session. - **Missed room messages.** A WebSocket connection stays on the worker that accepted it for its entire life. Room membership in memory therefore only lists the sockets *that worker* holds. A broadcast loop in worker 3 reaches worker 3's clients and nobody else. - **Rate limits too loose.** An in-memory counter allowing 100 requests a minute becomes 100 per worker, so a client spreading connections across eight workers gets roughly 800. - **Caches that disagree.** An in-memory cache invalidated after a write is invalidated only in the worker that handled the write; the others keep serving the stale value. Memory use is multiplied by N as well. - **Lost state on restart.** Anything held in a worker's memory disappears when that worker crashes or is retired, and its clients reconnect to some other worker. ## Fixes, by kind of state | State | Fix under cluster | |---|---| | Login sessions | a shared external store, or a signed token the client carries | | Rate-limit counters | a shared counter store, or accept a per-worker limit deliberately | | Room membership and broadcast | relay messages between workers, or use a shared pub/sub channel | | Caches | tolerate per-worker staleness, or broadcast invalidations, or share a cache | 1. **Move durable, per-user state out of the process.** Sessions belong in a shared store every worker can read, or in a signed token, so it does not matter which worker serves a request. This also survives worker restarts. 2. **Relay broadcasts through the primary on a single host.** The primary can receive a chat message from one worker with `cluster.on('message', (worker, message) => ...)` and forward it with `worker.send()` to every other worker in `cluster.workers`; each worker then writes it to its own local sockets. The code example shows this. 3. **Know what the relay costs.** Each IPC message is serialized (JSON by default, or the structured-clone-based `'advanced'` mode set with `cluster.setupPrimary({ serialization: 'advanced' })`) and copied once per hop, and every broadcast passes through the primary's single event loop. 4. **Keep the relay to one host.** It connects workers on the same machine only. Fanning messages out across several machines is a separate problem, covered with WebSocket scaling. ## Why "make it sticky" is not a cluster setting A common first idea is to send each user back to the worker that holds their state. Node's cluster has no option for that: under the default round-robin policy the primary picks the next ready worker for each connection, and under `SCHED_NONE` the operating system picks. A load balancer in front of the host can pin a client to a host, but not to a worker inside it. A primary can own its own server and pass each accepted socket to a worker it chooses with `worker.send(message, socket)`, but then you are writing and maintaining the routing yourself, and the state is still lost when that worker dies. ## Checklist when moving to cluster - List every module-level `Map`, array or object that outlives a request. - Decide for each whether it must be shared, may be per-worker, or can be dropped. - Test with at least two workers locally; a single-worker cluster hides all of the above.

  • Why not make the load balancer in front of the host sticky?
    A front load balancer can pin a client to a host, but inside the host Node's cluster still hands each new connection to the next ready worker, and the docs state Node provides no routing logic. Pinning to a worker means a primary that accepts sockets itself and passes each to a chosen worker with `worker.send(message, socket)`, which you maintain, and state is still lost when that worker dies.
  • Is a per-worker in-memory cache ever acceptable under cluster?
    Yes, for data that is cheap to recompute and tolerates staleness, such as parsed configuration or rarely changing lookups. Budget for N copies of the memory, and accept that an invalidation made in one worker does not reach the others unless you broadcast it. Anything that must be consistent per user belongs in shared storage.
  • What does relaying broadcasts through the primary cost?
    Every message is serialized, JSON by default, sent to the primary, and serialized again for each other worker, so large or frequent messages cost CPU and copies. All relay traffic funnels through the primary's single event loop, and the relay only connects workers on one machine.

  • The cluster primary routes each user back to the worker holding their session.
  • Workers share module-level variables, so an in-memory session Map still works.
  • A broadcast from one worker reaches every WebSocket client on the host.
  • An in-memory rate limiter keeps the same limit with N workers.
  • Relaying through the primary also fans messages out across machines.