How does Node's cluster module distribute incoming TCP connections across workers, and why is round-robin the default everywhere except Windows?
answer
- who accepts the connection
- SCHED_RR vs SCHED_NONE
- the kernel spreads it unevenly
- per connection, not per request
- NODE_CLUSTER_SCHED_POLICY, frozen at first fork
basics
~20 sUnder the default cluster.SCHED_RR, the primary accepts each connection and hands it to the next ready worker over IPC. Under SCHED_NONE, workers accept from one shared socket, which the docs say balances badly; Windows uses it because round-robin performs poorly with IOCP.
solid answer
~40 sNode's cluster has two policies. With `cluster.SCHED_RR`, the default except on Windows, the primary listens on the port, accepts each connection and passes its handle to a worker over IPC, waiting for that worker's acknowledgement before giving it another. With `cluster.SCHED_NONE`, the primary shares the listening socket and workers accept directly; the docs report this skews badly, with over 70% of connections landing in two of eight processes. Windows defaults to `SCHED_NONE` because round-robin performs poorly with IOCP. You set the policy with `cluster.schedulingPolicy` or `NODE_CLUSTER_SCHED_POLICY` (`'rr'` or `'none'`) before the first fork. Either way the unit is a connection: keep-alive requests and WebSockets stay on the worker that received them.
go deeper
Remember that by default the primary accepts connections and hands them to workers one after another, except on Windows.
Explain SCHED_RR versus SCHED_NONE, why OS-level accepting skews, and that the policy is frozen at the first fork.
Show the consequences: balance is per connection, so keep-alive and WebSockets pin load, and a blocked primary stalls every new connection.
Weigh the primary as a shared accept path and single point of failure against the even spread it buys for a host's workers.
## The problem: one port, many processes With the cluster module, every worker calls `server.listen(port)` on the same port, yet each is a separate process. Something has to decide which process gets each new TCP connection. Node offers **two scheduling policies**, exposed as constants on the module: - `cluster.SCHED_RR`: **round-robin by the primary**. The primary process listens on the port, accepts every new connection itself, and passes the connection's handle to a worker over the IPC channel. - `cluster.SCHED_NONE`: **leave it to the operating system**. The primary creates the listening socket and sends it to the workers, and the workers accept connections from it directly. `SCHED_RR` is the default on every platform except Windows, where the default is `SCHED_NONE`. | | `SCHED_RR` (default except Windows) | `SCHED_NONE` (Windows default) | |---|---|---| | Who accepts a connection | the primary | a worker, directly | | How it reaches a worker | handle sent over IPC | worker already holds the socket | | Balance | even across ready workers | decided by the OS scheduler, often skewed | | Extra hop | one IPC handoff per connection | none | | Primary in the accept path | yes | no | ## Why not let the operating system do it? In theory, workers accepting directly from one shared socket should be fastest, since there is no handoff. The Node docs say that in practice **distribution tends to be very unbalanced** because of operating system scheduler vagaries, and record loads where over 70% of all connections ended up in two processes out of eight. A worker whose event loop happens to wake first keeps winning connections, so one core runs hot while others idle. Round-robin trades a small IPC cost per connection for even spread. Windows stays on `SCHED_NONE` because, as the docs and the source comment put it, round-robin does not perform well there given how IOCP (Windows' completion-port I/O model) is wired up; the docs say Windows will switch once libuv can distribute IOCP handles without a large performance hit. ## How round-robin avoids flooding a worker The round-robin is not strictly blind. Reading the Node 24 source (`lib/internal/cluster/round_robin_handle.js`), the primary keeps a queue of **ready** workers. When it hands a connection to a worker it waits for that worker's acknowledgement before treating it as ready again. A worker whose event loop is blocked cannot acknowledge, so new connections queue in the primary for the other workers rather than piling onto the stuck one. A worker can also refuse: if its server is at `server.maxConnections`, Node routes the connection to another worker by default (set `server.dropMaxConnection` to close it instead). ## What is balanced, and what is not Round-robin balances **connections, not requests**. That has consequences: 1. An HTTP keep-alive connection stays with the worker that received it, so every request on it is handled there. 2. A WebSocket stays on its worker for its whole life, so a few busy long-lived sockets can skew load no matter how fair the handoff was. 3. UDP is exempt: `dgram` sockets in a cluster always use the shared-handle approach, since there is no connection to hand off. 4. The primary is on the accept path of every connection, so a primary that blocks its own event loop stalls new connections for all workers. ## Choosing the policy The policy can be set in code with `cluster.schedulingPolicy = cluster.SCHED_NONE` or through the `NODE_CLUSTER_SCHED_POLICY` environment variable, whose valid values are `'rr'` and `'none'`. It is a **global setting, effectively frozen** once the first worker is forked or `cluster.setupPrimary()` is called, whichever comes first, so it cannot be changed to rebalance a running cluster. ## listen() quirks inside a worker Because `listen()` in a worker is delegated to the primary, the docs list three differences from a normal process: - `server.listen({ fd: 7 })` listens on file descriptor 7 **of the primary**, not the worker's. - `server.listen(handle)` with an explicit handle bypasses the primary and uses that handle. - `server.listen(0)` gives every worker **the same** randomly chosen port; derive a port from `cluster.worker.id` if each needs its own. Passing `exclusive: true` to `server.listen()` opts a worker out of handle sharing altogether, so a second worker trying the same port gets an error. That is for a port only one worker should own, not a load-balancing knob.
- Why can one worker still run hot under round-robin scheduling?Round-robin spreads connections, not requests or CPU cost. A keep-alive connection carrying many requests, or a long-lived WebSocket with heavy traffic, stays on the worker that accepted it. A handful of such connections can load one worker far more than its neighbours even though each received the same number of connections.
- What does server.listen(0) do inside a cluster worker?Normally it binds a random free port. In a cluster the primary picks the random port once and every worker that calls `listen(0)` receives that same port, so the port is random the first time and predictable after that. If each worker needs a distinct port, compute it from `cluster.worker.id`.
- How do you switch the policy, and when can you no longer change it?Set `cluster.schedulingPolicy` to `cluster.SCHED_RR` or `cluster.SCHED_NONE` in the primary, or start Node with `NODE_CLUSTER_SCHED_POLICY` set to `'rr'` or `'none'`. The setting is global and is frozen as soon as the first worker is forked or `cluster.setupPrimary()` is called, so a running cluster cannot be rebalanced by changing it.
A restaurant host seats each arriving party at the next free waiter's section, and a waiter gets another party only after nodding that the last one is seated. Once seated, a party orders every course from that same waiter, just as every request on a keep-alive connection stays with one worker.
- The OS spreads connections evenly, so cluster round-robin adds nothing.
- Round-robin sends each HTTP request, not each connection, to the next worker.
- The primary proxies request bytes to workers instead of passing the socket handle.
- cluster.schedulingPolicy can be changed later to rebalance running workers.
- UDP sockets in a cluster are round-robined like TCP connections.