Node.js Cluster Module: Scaling Applications with Workers

1. Introduction

The Cluster module allows developers to run multiple Node.js processes that share server ports. This improves performance and resource utilization by leveraging multiple CPU cores.

2. How It Works

• Workers are created using child_process.fork().
• Communication between primary and workers happens via IPC.
• Two distribution methods:
  • Round-robin (default): Primary accepts connections and distributes them across workers.
  • Direct accept: Primary creates the socket and passes it to workers, which accept connections directly.

3. Basic Example

const cluster = require('node:cluster');
const http = require('node:http');
const numCPUs = require('node:os').availableParallelism();

if (cluster.isPrimary) {
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }
} else {
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end('hello world\\n');
  }).listen(8000);
}

4. Worker Class

• Each worker is represented by a Worker object extending EventEmitter.
• Key events:
  • 'disconnect': IPC channel disconnected.
  • 'error': Worker error.
  • 'exit': Worker terminated.
  • 'listening': Worker is ready to accept requests.
  • 'message': Message received from worker.
  • 'online': Worker is running after fork.

5. Worker Management

• worker.disconnect(): Disconnect worker gracefully.
• worker.exitedAfterDisconnect: Distinguish voluntary vs accidental exit.
• worker.isConnected() / worker.isDead(): Check worker status.
• worker.kill(): Terminate worker immediately.

6. Cluster Settings

• cluster.settings: Includes execArgv, exec, args, cwd, serialization, silent, stdio, uid, gid, inspectPort, windowsHide.
• cluster.setupPrimary(): Configure default fork behavior.
• cluster.schedulingPolicy: Choose between round-robin or OS scheduling.

7. Important Notes

• Node.js does not provide routing logic; sessions should not rely on in-memory data.
• Workers can be killed or respawned without affecting others.
• Managing the number of workers is the application’s responsibility.

Conclusion

The Cluster module is a powerful tool for scaling Node.js applications. By distributing workloads across multiple processes and leveraging IPC communication, developers can build scalable and efficient systems. Proper worker management and design are essential for success.