The Node.js docs show this pattern without any explanation of why it works: ```javascript const cluster = require("node:cluster"); const http = require("node:http"); const numCPUs = require("node:os").cpus().length; const process = require("node:process"); if (cluster.isPrimary) { console.log(`Primary ${process.pid} is running`); for (let i = 0; i < numCPUs; i++) { cluster.fork(); } cluster.on("exit", (worker, code, signal) => { console.log(`worker ${worker.process.pid} died`); }); } else { http .createServer((req, res) => { res.writeHead(200); res.end("hello world\n"); }) .listen(8000); console.log(`Worker ${process.pid} started`); } ``` Everyone knows that listening on a port twice throws: ```shell man listen listen() will fail if: [EINVAL] socket is already connected. ``` And indeed, without `cluster`: ```javascript const http = require("node:http"); const numCPUs = require("node:os").cpus().length; for (let i = 0; i < numCPUs; i++) { http.Server((req, res) => { ... }).listen(8000); } // Error: listen EADDRINUSE: address already in use :::8000 ``` So how does `cluster` get away with it? Time to read the source. ## Tracing `http.Server.listen` ```javascript // lib/net.js Server.prototype.listen = function (...args) { // ... if (options.host) { lookupAndListen(this, options.port | 0, options.host, backlog, options.exclusive, flags); } else { listenInCluster(this, null, options.port | 0, 4, backlog, undefined, options.exclusive); } }; ``` Both paths end up in `listenInCluster`: ```javascript // lib/net.js function listenInCluster(server, address, port, addressType, backlog, fd, exclusive, flags, options) { exclusive = !!exclusive; if (cluster === undefined) cluster = require("cluster"); if (cluster.isPrimary || exclusive) { // Primary process: actually bind and listen server._listen2(address, port, addressType, backlog, fd, flags); return; } const serverQuery = { address, port, addressType, fd, flags, backlog, ...options }; // Worker: ask the primary for its handle cluster._getServer(server, serverQuery, listenOnPrimaryHandle); function listenOnPrimaryHandle(err, handle) { err = checkBindError(err, port, handle); if (err) { return server.emit("error", exceptionWithHostPort(err, "bind", address, port)); } server._handle = handle; server._listen2(address, port, addressType, backlog, fd, flags); } } ``` Workers don't bind at all — they ask the primary for its handle. But what about processes that aren't using `cluster`? ## Why Non-cluster Code Still Works `cluster.isPrimary` is defined as: > True if the process is a primary. This is determined by `process.env.NODE_UNIQUE_ID`. If `process.env.NODE_UNIQUE_ID` is undefined, then `isPrimary` is `true`. Without `cluster.fork()`, `NODE_UNIQUE_ID` is never set, so every process is considered the primary and calls `server._listen2` directly. That's why consecutive `listen()` calls on different servers in the same process throw `EADDRINUSE` — they each try to actually bind. `cluster.fork()` sets `NODE_UNIQUE_ID` on worker processes: ```javascript // lib/internal/cluster/primary.js cluster.fork = function (env) { cluster.setupPrimary(); const id = ++ids; const workerProcess = createWorkerProcess(id, env); // ... }; function createWorkerProcess(id, env) { const workerEnv = { ...process.env, ...env, NODE_UNIQUE_ID: `${id}` }; return fork(cluster.settings.exec, cluster.settings.args, { env: workerEnv, ... }); } ``` ## How a Worker Gets the Primary's Handle `cluster._getServer` in a worker sends an IPC message: ```javascript // lib/internal/cluster/child.js cluster._getServer = function (obj, options, cb) { const message = { act: "queryServer", ...options }; send(message, (reply, handle) => { if (handle) { shared(reply, { handle, indexesKey, index }, cb); } else { rr(reply, { indexesKey, index }, cb); } }); }; ``` The message travels over the IPC channel to the primary. The primary's `queryServer` handler either finds an existing `RoundRobinHandle` for that address/port or creates one: ```javascript // lib/internal/cluster/primary.js function queryServer(worker, message) { const key = `${message.address}:${message.port}:${message.addressType}:${message.fd}:${message.index}`; let handle = handles.get(key); if (handle === undefined) { if (schedulingPolicy !== SCHED_RR || message.addressType === 'udp4' || message.addressType === 'udp6') { handle = new SharedHandle(key, address, message); } else { handle = new RoundRobinHandle(key, address, message); } handles.set(key, handle); } handle.add(worker, (errno, reply, handle) => { send(worker, { errno, key, ack: message.seq, ...reply }, handle); }); } ``` `RoundRobinHandle` creates the actual TCP server in the primary and intercepts `onconnection`: ```javascript // lib/internal/cluster/round_robin_handle.js function RoundRobinHandle(key, address, { port, fd, flags, backlog }) { this.server = net.createServer(assert.fail); this.server.listen({ port, host: address, ... }); this.server.once("listening", () => { this.handle = this.server._handle; // Replace the connection handler with round-robin distribution this.handle.onconnection = (err, handle) => this.distribute(err, handle); this.server._handle = null; this.server = null; }); } ``` The primary binds once. Workers each receive a **fake handle** via the `rr` function. When `_listen2` is called on that fake handle it sets `onconnection`, but no real OS bind happens — the primary's `RoundRobinHandle.distribute` is what actually delivers connections to workers. ## The Complete Picture 1. Primary binds port 8000 once via `RoundRobinHandle`. 2. Each worker calls `listen(8000)`, which sends `queryServer` over IPC. 3. Primary responds with a fake handle (no OS socket, just a JS object). 4. Worker sets `onconnection` on the fake handle — this is what your `http.createServer` callback ends up attached to. 5. When a connection arrives at port 8000, the primary's round-robin dispatcher picks a free worker and sends the raw socket handle over IPC. The worker's `onconnection` fires and handles the request. Here's the equivalent model in C — one process binds, forks, and shares the listening socket with children via inheritance: ```cpp #include #include #include #include #include #include #include #include #define PORT 4444 int main(){ int sockfd, ret; struct sockaddr_in serverAddr; int newSocket; struct sockaddr_in newAddr; socklen_t addr_size; char buffer[1024]; pid_t childpid; sockfd = socket(AF_INET, SOCK_STREAM, 0); memset(&serverAddr, '\0', sizeof(serverAddr)); serverAddr.sin_family = AF_INET; serverAddr.sin_port = htons(PORT); serverAddr.sin_addr.s_addr = inet_addr("127.0.0.1"); bind(sockfd, (struct sockaddr*)&serverAddr, sizeof(serverAddr)); listen(sockfd, 10); while(1){ newSocket = accept(sockfd, (struct sockaddr*)&newAddr, &addr_size); if((childpid = fork()) == 0){ close(sockfd); while(1){ recv(newSocket, buffer, 1024, 0); if(strcmp(buffer, ":exit") == 0) break; send(newSocket, buffer, strlen(buffer), 0); bzero(buffer, sizeof(buffer)); } } } close(newSocket); return 0; } ```