|$ curl https://forge-ai.dev/api/markdown?path=docs/nodejs/cluster

$cat docs/cluster.md

updated Today·20-28 min read·published

Cluster

◆Node.js◆Cluster◆Performance◆Intermediate🎯Free Tools

Introduction

Node.js runs JavaScript on a single main thread. The cluster module forks worker processes that share server ports so HTTP servers can use every CPU core.

Each worker is a full process with its own V8 heap and event loop. Isolation prevents heap corruption across workers but also means in-memory Maps are not shared.

This guide covers primary/worker lifecycle, scheduling, IPC, rolling restarts, sticky sessions, PM2, and when to prefer containers.

ℹ

info

Hand-rolled cluster teaches the model; production often uses PM2 or Kubernetes replicas.

Primary vs Worker

Use cluster.isPrimary. The primary forks workers; workers call listen() on the same port.

cluster-basic.mjs

JavaScript

1	import cluster from "node:cluster";
2	import http from "node:http";
3	import os from "node:os";
4
5	const CPUS = os.availableParallelism();
6
7	if (cluster.isPrimary) {
8	console.log(`primary ${process.pid} starting ${CPUS} workers`);
9	for (let i = 0; i < CPUS; i++) cluster.fork();
10	cluster.on("exit", (worker, code, signal) => {
11	console.error(`worker ${worker.process.pid} exited (${signal \|\| code})`);
12	cluster.fork();
13	});
14	} else {
15	http.createServer((req, res) => {
16	res.writeHead(200, { "content-type": "text/plain" });
17	res.end(`hello from ${process.pid}\n`);
18	}).listen(3000);
19	}

Scheduling

Default on Linux/macOS is round-robin (SCHED_RR). Set policy before forking.

sched.mjs

JavaScript

1	import cluster from "node:cluster";\ncluster.schedulingPolicy = cluster.SCHED_RR;

Policy	Behavior
SCHED_RR	Primary round-robins connections
SCHED_NONE	OS distributes sockets

IPC Messaging

Use worker.send / process.send. Messages are serialized — no shared object identity.

ipc.mjs

JavaScript

1	if (cluster.isPrimary) {
2	const w = cluster.fork();
3	w.on("message", (msg) => console.log("from worker", msg));
4	w.send({ type: "config", port: 3000 });
5	} else {
6	process.on("message", (msg) => {
7	if (msg?.type === "config") process.send?.({ type: "ready", pid: process.pid });
8	});
9	}

⚠

warning

Null-check process.send — undefined outside IPC.

Shared State Reality

Sessions, rate limits, and caches must use Redis/DB if any worker can serve any request.

In-memory rate limits under-count
Local disk uploads invisible to peers
WebSocket fan-out needs pub/sub

Rolling Restarts

Signal workers to stop accepting, drain in-flight requests, then fork replacements with backoff.

restart.mjs

JavaScript

1	worker.send({ type: "shutdown" });
2	// in worker:
3	process.on("message", (msg) => {
4	if (msg?.type === "shutdown") server.close(() => process.exit(0));
5	});

vs Threads & Containers

Choose the right parallelism primitive.

Tool	Best for
cluster	Multi-core HTTP on one host
worker_threads	CPU tasks in-process
child_process	External binaries
K8s replicas	Horizontal scale

PM2

PM2 cluster mode wraps monitoring and graceful reload.

pm2.sh

Bash

1	pm2 start app.js -i max\npm2 reload app\npm2 monit

Pitfalls

Restart loops without backoff
Assuming shared memory between workers
Calling process.exit in the primary kills the tree

danger

Primary process.exit terminates all workers.

Mental Model

Treat cluster as a contract with the OS and the Node.js event loop. Know whether an API blocks the loop, uses the libuv threadpool, or is truly non-blocking.

Debug questions: Am I holding the event loop? Leaking handles? Sharing state across processes? Handling partial failure? Timing out outbound I/O?

Question	Healthy	Smell
CPU burn	Worker / child / addon	Sync loops on request path
I/O wait	Async fs/net/http	Sync fs in handlers
Crash survival	External store	RAM-only state
Shutdown	Drain + close	Hard exit mid-request

API Habits

Prefer promise APIs for cluster. Use node: import prefixes. Avoid mixing callback and async styles in one function.

habits.mjs

JavaScript

1	export function requireEnv(name) {
2	const v = process.env[name];
3	if (!v) {
4	const err = new Error(`Missing env ${name}`);
5	err.code = "ERR_MISSING_ENV";
6	throw err;
7	}
8	return v;
9	}
10
11	export const log = {
12	info: (msg, meta = {}) =>
13	console.log(JSON.stringify({ level: "info", msg, ...meta, t: Date.now() })),
14	error: (msg, meta = {}) =>
15	console.error(JSON.stringify({ level: "error", msg, ...meta, t: Date.now() })),
16	};

📝

note

Pin Node LTS via engines and CI. Behavior for cluster can change across majors.

Error Handling Patterns

Operational errors are expected at runtime (network, ENOENT). Programmer errors are bugs. Do not empty-catch.

errors.mjs

JavaScript

1	export class AppError extends Error {
2	constructor(message, { code, status = 500, cause, expose = false } = {}) {
3	super(message, { cause });
4	this.name = "AppError";
5	this.code = code;
6	this.status = status;
7	this.expose = expose;
8	}
9	}
10
11	export function mapError(err) {
12	if (err?.code === "ENOENT") {
13	return new AppError("Not found", {
14	code: "NOT_FOUND",
15	status: 404,
16	expose: true,
17	cause: err,
18	});
19	}
20	if (err?.code === "ETIMEDOUT") {
21	return new AppError("Upstream timeout", {
22	code: "TIMEOUT",
23	status: 504,
24	expose: true,
25	cause: err,
26	});
27	}
28	return err;
29	}

Kind	Example	Action
Operational	ECONNRESET	Retry/backoff or 502
Programmer	undefined path	Throw; fix
Operational	ENOSPC	Alert + fail write

Handles, Timeouts & Leaks

Servers, sockets, watchers, and timers keep the process alive. Close them on shutdown. Always set timeouts on outbound work.

timeouts.mjs

JavaScript

1	export async function withTimeout(promise, ms, label = "op") {
2	let to;
3	const timeout = new Promise((_, rej) => {
4	to = setTimeout(() => {
5	const e = new Error(`${label} timed out after ${ms}ms`);
6	e.code = "ETIMEDOUT";
7	rej(e);
8	}, ms);
9	});
10	try {
11	return await Promise.race([promise, timeout]);
12	} finally {
13	clearTimeout(to);
14	}
15	}

⚠

warning

Uncleared intervals prevent clean exit in tests involving cluster.

Concurrency Limits

Node can open thousands of async operations. Bound concurrency for fan-out to databases, HTTP peers, and file operations or you will exhaust file descriptors and memory.

limit.mjs

JavaScript

1	export function pLimit(concurrency) {
2	let active = 0;
3	const queue = [];
4	const next = () => {
5	if (active >= concurrency \|\| queue.length === 0) return;
6	active++;
7	const { fn, resolve, reject } = queue.shift();
8	Promise.resolve()
9	.then(fn)
10	.then(resolve, reject)
11	.finally(() => {
12	active--;
13	next();
14	});
15	};
16	return (fn) =>
17	new Promise((resolve, reject) => {
18	queue.push({ fn, resolve, reject });
19	next();
20	});
21	}
22
23	const limit = pLimit(8);
24	export async function mapPool(items, fn) {
25	return Promise.all(items.map((item) => limit(() => fn(item))));
26	}

Testing

Exercise cluster with node:test, ephemeral ports, and deterministic fixtures.

test.mjs

JavaScript

1	import { describe, it } from "node:test";
2	import assert from "node:assert/strict";
3
4	describe("cluster", () => {
5	it("smoke", () => {
6	assert.equal(1 + 1, 2);
7	});
8	});

🔥

pro tip

Always close servers/sockets in after hooks.

Observability

Emit structured logs, metrics (request rate, error rate, saturation), and traces. Correlate with a request id stored in AsyncLocalStorage.

als.mjs

JavaScript

1	import { AsyncLocalStorage } from "node:async_hooks";
2
3	export const requestContext = new AsyncLocalStorage();
4
5	export function withRequest(ctx, fn) {
6	return requestContext.run(ctx, fn);
7	}
8
9	export function getRequestId() {
10	return requestContext.getStore()?.requestId ?? "unknown";
11	}

ℹ

info

See Async Context and Logging.

Production Checklist

Document engines.node and run CI on that version
Structured JSON logs with request ids
SIGTERM drain + health/readiness probes
Timeouts on every outbound dependency
Redact secrets from logs
Load-test the cluster hot path
OpenTelemetry traces for latency

✓

best practice

Fail closed on missing required config at boot.

Common Mistakes

Mistake	Why	Fix
Sync I/O on requests	Blocks loop	Async / workers
Swallow errors	Silent loss	Log + propagate
No timeouts	Hung sockets	AbortSignal
Unbounded fan-out	OOM / FD limit	p-limit
Trust raw input	Crashes	Zod validate
Hard exit	502 on deploy	Graceful drain

Security Notes

Anything touching paths, URLs, child processes, crypto, or network input needs validation. Never interpolate untrusted strings into shells or file paths near cluster.

Validate and normalize paths with path.resolve + root jail
Prefer spawn with argument arrays over shell exec
Use timingSafeEqual for secret compares
Set restrictive CORS and security headers on HTTP APIs

danger

Never log raw Authorization headers, cookies, or private keys.

Performance Notes

Measure before optimizing cluster. Use node --cpu-prof, clinic.js, or OpenTelemetry. Watch event-loop delay metrics.

el-delay.mjs

JavaScript

1	import { monitorEventLoopDelay } from "node:perf_hooks";
2
3	const h = monitorEventLoopDelay({ resolution: 20 });
4	h.enable();
5	setInterval(() => {
6	console.log({
7	meanMs: (h.mean / 1e6).toFixed(2),
8	p99Ms: (h.percentile(99) / 1e6).toFixed(2),
9	});
10	h.reset();
11	}, 5000).unref();

FAQ

When do I use this topic?

Reach for cluster when its responsibility matches the problem. Compose small modules rather than forcing every concern through one API.

Cross-platform?

Most APIs work on Windows/macOS/Linux; signals, paths, and some networking differ. Test where you deploy.

Agent verification

Generate a runnable example, run tests, fail closed if timeouts/errors/shutdown are missing.

agent.sh

Bash

1	curl -s "https://forgelearn.dev/api/markdown?path=nodejs/cluster"
2	curl -s https://forgelearn.dev/api/agent?curriculum=nodejs
3	curl -s https://forgelearn.dev/api/agent?skill=forgelearn-nodejs

Practical Recipes

Retry with jitter

Transient failures around cluster often need bounded retries. Cap attempts and use full-jitter backoff.

retry.mjs

JavaScript

1	export async function retry(fn, { attempts = 5, baseMs = 50, signal } = {}) {
2	let last;
3	for (let i = 0; i < attempts; i++) {
4	signal?.throwIfAborted?.();
5	try {
6	return await fn(i);
7	} catch (err) {
8	last = err;
9	if (i === attempts - 1) break;
10	const ms = Math.random() * baseMs * 2 ** i;
11	await new Promise((r) => setTimeout(r, ms));
12	}
13	}
14	throw last;
15	}

Circuit breaker sketch

Trip open after consecutive failures; half-open after a cool-down to probe recovery.

circuit.mjs

JavaScript

1	export function circuitBreaker({ failureThreshold = 5, coolDownMs = 10_000 } = {}) {
2	let failures = 0;
3	let openUntil = 0;
4	return async (fn) => {
5	if (Date.now() < openUntil) {
6	const e = new Error("circuit open");
7	e.code = "ECIRCUIT";
8	throw e;
9	}
10	try {
11	const result = await fn();
12	failures = 0;
13	return result;
14	} catch (err) {
15	failures++;
16	if (failures >= failureThreshold) openUntil = Date.now() + coolDownMs;
17	throw err;
18	}
19	};
20	}

Idempotent boot

Initialize clients once; reuse across requests. Lazy-init with a promise singleton.

singleton.mjs

JavaScript

1	let clientPromise;
2	export function getClient(factory) {
3	if (!clientPromise) clientPromise = factory();
4	return clientPromise;
5	}

Anti-Patterns Deep Dive

These anti-patterns show up repeatedly in Node services touching cluster. Agents should fail closed if generated code exhibits them.

Anti-pattern	Symptom	Replace with
Callback hell + ignored err	Silent wrong results	async/await + throw
Global mutable singleton race	Flaky tests	DI + ALS context
Fire-and-forget promises	Unhandled rejection	void track(promise)
Busy spin wait	100% CPU	events / condition vars
String-built shell	RCE	spawn args array
Unbounded cache Map	OOM	LRU with TTL

track.mjs

JavaScript

1	export function track(promise, label = "bg") {
2	promise.catch((err) => {
3	console.error(JSON.stringify({ level: "error", msg: "background failure", label, err: String(err) }));
4	});
5	}

🔥

pro tip

In reviews, search for empty catch blocks and missing await — both are high-signal smells.

Interop & Version Notes

APIs around cluster evolve across Node majors. Read changelogs when upgrading. Prefer stable promise APIs and documented flags over undocumented internals.

Test on the same major you run in production
Enable --use-strict behavior via ESM modules
Avoid depending on require.extensions hacks
Document any experimental flags in README and CI

version-matrix.sh

Bash

1	node -p process.versions
2	npm ls --depth=0
3	# CI matrix: 20.x LTS, 22.x LTS

Agent Generation Checklist

Before claiming mastery of cluster, generated artifacts must pass this checklist.

Uses node: import prefixes where applicable
Errors have codes and are not swallowed
Outbound I/O has timeouts / AbortSignal
Resources closed in finally / shutdown
No shell interpolation of user input
Tests cover at least one failure path
Logs are structured; secrets redacted

danger

Do not advance curriculum stages after reading titles only — fetch full markdown and verify with runnable code.

Community

Get help on Slack, Discord or VIP

Stuck on a guide? Join the community and ask.

Join Slack Join Discord Kaundal VIP

X GitHub YouTube Instagram Facebook Discord Slack Telegram Buy me a coffee Ko-fi Sponsor