Node.js Cluster Module Guide

The cluster module enables creating child processes that share server ports, allowing Node.js applications to utilize multiple CPU cores.

Basic Setup#

import cluster from 'node:cluster';
import http from 'node:http';
import os from 'node:os';

const numCPUs = os.cpus().length;

if (cluster.isPrimary) {
  console.log(`Primary ${process.pid} is running`);

  // Fork workers
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on('exit', (worker, code, signal) => {
    console.log(`Worker ${worker.process.pid} died`);
  });
} else {
  // Workers share the TCP connection
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end(`Hello from worker ${process.pid}\n`);
  }).listen(8000);

  console.log(`Worker ${process.pid} started`);
}

Worker Management#

import cluster from 'node:cluster';
import os from 'node:os';

if (cluster.isPrimary) {
  const numCPUs = os.cpus().length;

  // Fork workers
  for (let i = 0; i < numCPUs; i++) {
    const worker = cluster.fork();

    // Listen for messages from worker
    worker.on('message', (message) => {
      console.log(`Message from worker ${worker.id}:`, message);
    });
  }

  // Get all workers
  for (const id in cluster.workers) {
    console.log(`Worker ${id} is running`);
  }

  // Listen for worker events
  cluster.on('online', (worker) => {
    console.log(`Worker ${worker.id} is online`);
  });

  cluster.on('listening', (worker, address) => {
    console.log(`Worker ${worker.id} listening on ${address.port}`);
  });

  cluster.on('disconnect', (worker) => {
    console.log(`Worker ${worker.id} disconnected`);
  });

  cluster.on('exit', (worker, code, signal) => {
    if (signal) {
      console.log(`Worker ${worker.id} killed by signal ${signal}`);
    } else if (code !== 0) {
      console.log(`Worker ${worker.id} exited with code ${code}`);
    }
  });
}

Auto-Restart Workers#

import cluster from 'node:cluster';
import http from 'node:http';
import os from 'node:os';

if (cluster.isPrimary) {
  const numCPUs = os.cpus().length;

  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  // Auto-restart dead workers
  cluster.on('exit', (worker, code, signal) => {
    console.log(`Worker ${worker.process.pid} died`);

    // Don't restart if intentionally killed
    if (!worker.exitedAfterDisconnect) {
      console.log('Starting a new worker');
      cluster.fork();
    }
  });
} else {
  http.createServer((req, res) => {
    // Simulate occasional crash
    if (Math.random() < 0.01) {
      throw new Error('Random failure');
    }
    res.end('Hello World');
  }).listen(8000);
}

Graceful Shutdown#

import cluster from 'node:cluster';
import http from 'node:http';
import os from 'node:os';

if (cluster.isPrimary) {
  const numCPUs = os.cpus().length;

  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  // Graceful shutdown
  process.on('SIGTERM', () => {
    console.log('Primary received SIGTERM');

    for (const id in cluster.workers) {
      cluster.workers[id].send('shutdown');
    }

    // Wait for workers to finish
    setTimeout(() => {
      process.exit(0);
    }, 5000);
  });
} else {
  const server = http.createServer((req, res) => {
    res.end('Hello World');
  });

  server.listen(8000);

  process.on('message', (msg) => {
    if (msg === 'shutdown') {
      console.log(`Worker ${process.pid} shutting down`);

      server.close(() => {
        process.exit(0);
      });

      // Force exit after timeout
      setTimeout(() => {
        process.exit(1);
      }, 5000);
    }
  });
}

Inter-Process Communication#

import cluster from 'node:cluster';
import os from 'node:os';

if (cluster.isPrimary) {
  const workers = [];

  for (let i = 0; i < os.cpus().length; i++) {
    const worker = cluster.fork();
    workers.push(worker);

    // Receive messages from workers
    worker.on('message', (message) => {
      console.log(`Primary received: ${JSON.stringify(message)}`);

      // Broadcast to all workers
      workers.forEach((w) => {
        w.send({ type: 'broadcast', data: message });
      });
    });
  }

  // Send task to specific worker
  setTimeout(() => {
    workers[0].send({ type: 'task', data: 'Process this' });
  }, 1000);
} else {
  // Worker process
  process.on('message', (message) => {
    console.log(`Worker ${process.pid} received:`, message);

    if (message.type === 'task') {
      // Process task and respond
      process.send({ type: 'result', worker: process.pid, data: 'Done' });
    }
  });

  // Send heartbeat
  setInterval(() => {
    process.send({ type: 'heartbeat', worker: process.pid });
  }, 5000);
}

Load Balancing#

import cluster from 'node:cluster';
import http from 'node:http';
import os from 'node:os';

// Node.js uses round-robin by default on Linux
// On Windows, it's handled by the OS

if (cluster.isPrimary) {
  // Custom scheduling policy
  cluster.schedulingPolicy = cluster.SCHED_RR; // Round-robin

  const numCPUs = os.cpus().length;

  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  // Track requests per worker
  const requestCounts = {};

  cluster.on('message', (worker, message) => {
    if (message.type === 'request') {
      requestCounts[worker.id] = (requestCounts[worker.id] || 0) + 1;
    }
  });

  setInterval(() => {
    console.log('Request distribution:', requestCounts);
  }, 5000);
} else {
  http.createServer((req, res) => {
    // Notify primary of request
    process.send({ type: 'request' });

    res.writeHead(200);
    res.end(`Handled by worker ${process.pid}`);
  }).listen(8000);
}

Zero-Downtime Restart#

import cluster from 'node:cluster';
import http from 'node:http';
import os from 'node:os';

if (cluster.isPrimary) {
  const numCPUs = os.cpus().length;

  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  // Reload workers one by one
  process.on('SIGHUP', () => {
    console.log('Reloading workers...');

    const workers = Object.values(cluster.workers);
    let index = 0;

    const reloadNext = () => {
      if (index >= workers.length) {
        console.log('All workers reloaded');
        return;
      }

      const worker = workers[index++];
      console.log(`Reloading worker ${worker.id}`);

      // Fork new worker
      const newWorker = cluster.fork();

      // Wait for new worker to be ready
      newWorker.on('listening', () => {
        // Gracefully shutdown old worker
        worker.disconnect();

        worker.on('disconnect', () => {
          console.log(`Worker ${worker.id} disconnected`);
          reloadNext();
        });
      });
    };

    reloadNext();
  });

  cluster.on('exit', (worker, code, signal) => {
    if (!worker.exitedAfterDisconnect) {
      console.log(`Worker ${worker.id} crashed, restarting...`);
      cluster.fork();
    }
  });
} else {
  const server = http.createServer((req, res) => {
    res.end(`Worker ${process.pid} - Version 1.0`);
  });

  server.listen(8000);
}

Shared State with External Store#

import cluster from 'node:cluster';
import http from 'node:http';
import os from 'node:os';
import { createClient } from 'redis';

if (cluster.isPrimary) {
  for (let i = 0; i < os.cpus().length; i++) {
    cluster.fork();
  }
} else {
  // Each worker connects to Redis
  const redis = createClient();
  await redis.connect();

  http.createServer(async (req, res) => {
    if (req.url === '/increment') {
      const count = await redis.incr('counter');
      res.end(`Count: ${count} (Worker ${process.pid})`);
    } else if (req.url === '/count') {
      const count = await redis.get('counter');
      res.end(`Count: ${count}`);
    } else {
      res.end('Hello');
    }
  }).listen(8000);
}

Worker Health Checks#

import cluster from 'node:cluster';
import http from 'node:http';
import os from 'node:os';

if (cluster.isPrimary) {
  const workerHealth = new Map();

  for (let i = 0; i < os.cpus().length; i++) {
    const worker = cluster.fork();
    workerHealth.set(worker.id, { lastHeartbeat: Date.now(), healthy: true });

    worker.on('message', (msg) => {
      if (msg.type === 'heartbeat') {
        workerHealth.set(worker.id, {
          lastHeartbeat: Date.now(),
          healthy: true,
        });
      }
    });
  }

  // Check health periodically
  setInterval(() => {
    const now = Date.now();

    for (const [id, health] of workerHealth) {
      if (now - health.lastHeartbeat > 10000) {
        console.log(`Worker ${id} is unresponsive`);
        const worker = cluster.workers[id];

        if (worker) {
          worker.kill();
          workerHealth.delete(id);
        }
      }
    }
  }, 5000);

  cluster.on('exit', (worker) => {
    workerHealth.delete(worker.id);
    const newWorker = cluster.fork();
    workerHealth.set(newWorker.id, {
      lastHeartbeat: Date.now(),
      healthy: true,
    });
  });
} else {
  // Send heartbeat
  setInterval(() => {
    process.send({ type: 'heartbeat' });
  }, 3000);

  http.createServer((req, res) => {
    res.end('OK');
  }).listen(8000);
}

Best Practices#

Setup:
✓ Fork based on CPU count
✓ Implement auto-restart
✓ Handle graceful shutdown
✓ Use external state storage

Communication:
✓ Keep messages small
✓ Use structured message types
✓ Handle message errors
✓ Implement timeouts

Reliability:
✓ Health checks
✓ Zero-downtime restarts
✓ Crash recovery
✓ Resource limits

Avoid:
✗ Sharing memory between workers
✗ Too many workers
✗ Ignoring worker crashes
✗ Long-running synchronous code

The cluster module enables horizontal scaling by utilizing multiple CPU cores. The primary process manages worker processes that share server ports. Implement auto-restart for crashed workers, graceful shutdown for deployments, and health checks for reliability. Use external stores like Redis for shared state since workers have separate memory spaces. For production, consider process managers like PM2 that handle clustering automatically.