cluster Module: Master-Worker Round-Robin IPC Socket Handoffs
- Last updated
- Prerequisites:
- Node.js event loop and HTTP basics
- Understanding of processes and load balancing
- nodejs
- cluster
- master-worker
- ipc
- round-robin
- load-balancing
Read at your depth
The practical view
The cluster module lets you run multiple Node.js processes (workers) sharing the same server port, managed by a master process: const cluster = require('node:cluster'); if (cluster.isPrimary) { cluster.fork(); } else { http.createServer(...).listen(3000); }. Each worker is a full Node process (own event loop, own memory) — so you can use all CPU cores. The primary distributes incoming connections to workers. Workers communicate with the primary via IPC; a worker crash is detected (exit event) and can be re-forked. Cluster is the classic way to scale a Node server across cores without a separate load balancer.
The same idea in other frameworks
N/A — Node.js runtime concern.N/A — Node.js concern.N/A — Node.js concern.N/A — Node.js concern.Legacy vs modern
Single-process server vs clustered multi-process
A single process uses one core; clustering forks workers so the server uses all cores.
http.createServer(handler).listen(3000); // ❌ OLD: one process, one coreif (cluster.isPrimary) {
for (let i = 0; i < os.cpus().length; i++) cluster.fork(); // ✅ NEW
cluster.on('exit', (w) => cluster.fork()); // ✅ NEW: auto-replace
} else {
http.createServer(handler).listen(3000); // ✅ NEW: each worker on same port
}Interview gotchas
Context
This tests the socket-handoff mechanics — interviewers want the fd-passing over IPC and the SCHED_RR vs SCHED_NONE distinction that explains cross-platform behavior.
The mechanical answer
With the default round-robin scheduling (cluster.SCHED_RR, used on Linux), the PRIMARY process binds the port and accepts every incoming connection. It then passes the raw socket (the file descriptor) to the next worker in rotation via IPC — implemented with libuv pipes and sendmsg/SCM_RIGHTS (fd passing over a Unix domain socket). The worker's net server receives the handle and emits a 'connection' event, so the worker handles the request without ever having bound the port itself. This distributes connections evenly. On Windows (and when SCHED_NONE is used), the OS shares the port across workers directly (SO_REUSEPORT semantics), and the kernel does the distribution. The round-robin approach gives Node control over balancing; SCHED_NONE relies on the OS.
Trap
The naive answer is 'each worker binds the same port independently'. In SCHED_RR the master accepts and passes fds; only with SCHED_NONE do workers share via the OS. Another trap: assuming sticky sessions are automatic — round-robin can route a client's successive requests to different workers, so session state must live outside the process (Redis) or use sticky logic. Candidates who describe the fd-passing mechanism show real understanding.
Context
This probes the process-boundary implications — interviewers want the per-isolate memory model and the external-store pattern that clustering requires.
The mechanical answer
Cluster workers are separate processes with separate V8 heaps: in-memory state (module-level variables, caches, in-process sessions, setInterval counters, sockets) is NOT shared. A request handled by worker 1 cannot read state that worker 2 set in memory. The patterns: use an external shared store (Redis, a database) for sessions, caches, and counters; route stateful traffic to the same worker via sticky sessions (checking a cookie/header and forcing the round-robin assignment) if you must keep in-process state; and use the primary as an IPC hub for simple cross-worker messages (process.send / cluster message events). This is the key architectural consequence of process-based scaling: everything shared must be externalized.
Trap
The naive answer is 'cluster shares memory across workers'. Each worker is an isolated process — no shared heap. Another trap: relying on in-memory rate-limit counters or caches to be accurate — they're per-worker, so limits are N× off and caches are duplicated. Candidates who mention the external store and sticky-session patterns show real production experience.