Understanding Node.js Cluster: Multi‑Process Model, Fork, IPC, and Port Sharing

Building on a previous article that introduced Node.js HTTP handling, this piece dives into the Cluster module to enable a multi‑process model that fully utilizes CPU cores.

It starts with a classic master‑worker code example that uses cluster.fork() to spawn workers equal to the number of CPUs, each listening on the same port while the master distributes incoming connections.

const cluster = require('cluster');
const numCPUs = require('os').cpus().length;
if (cluster.isMaster) {
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }
} else {
  require('http').createServer((req, res) => {
    res.end('hello world');
  }).listen(3333);
}

The article then explains the lifecycle of a worker: creation via child_process.spawn , the role of ChildProcess , and how the master sets up special environment variables ( NODE_CHANNEL_FD and NODE_UNIQUE_ID ) to differentiate worker processes.

It describes the internal steps of cluster.fork :

Calling child_process.spawn to create a ChildProcess object.

Initializing its _handle as a Process object that wraps libuv process functions.

Invoking uv_spawn from libuv to actually launch the worker.

Worker initialization differs from a normal Node.js process because the master passes NODE_CHANNEL_FD (always 3) to establish an IPC channel using a socketpair.

IPC implementation details are explored, showing how a full‑duplex UNIX domain socket created by socketpair(AF_UNIX, SOCK_STREAM, 0, sv) enables message passing and file‑descriptor transfer between master and workers.

int socketpair(int domain, int type, int protocol, int sv[2]);

The master creates a Pipe object with ipc:true , configures libuv’s uv_process_options_t to include the pipe in the child’s stdio, and then opens a bidirectional socket for communication.

When a worker calls server.listen , the call is intercepted; instead of binding the port directly, the worker sends a {"act":"queryServer"} message to the master. The master creates a RoundRobinHandle that actually binds the port and distributes incoming connections to workers via messages like {"act":"newconn"} . Workers acknowledge with {"ack":msg.seq, "accepted":true} .

Code examples for a custom master‑slave IPC demo are provided:

// 1-master.js
const { spawn } = require('child_process');
let child = spawn(process.execPath, ['1-slave.js'], { stdio: [0,1,2,'ipc'] });
child.on('message', data => {
  console.log('received in master:');
  console.log(data);
});
child.send({ msg: 'msg from master' });

// 1-slave.js
process.on('message', data => {
  console.log('received in slave:');
  console.log(data);
});
process.send({ msg: 'message from slave' });

The article also outlines the libuv read flow ( uv_read_start ) and the class hierarchy involved in stream handling, illustrating how the IPC channel ultimately delivers messages and, when needed, file descriptors.

int uv_read_start(uv_stream_t* stream, uv_alloc_cb alloc_cb, uv_read_cb read_cb);

Finally, it mentions a C implementation of a master‑slave HTTP server on GitHub and shows the expected output when accessing http://localhost:3333 , confirming that multiple workers can share the same port without conflict.

Readers are encouraged to explore further topics such as production‑grade process management for Node.js.