Scaling Node.js with Cluster Module

Node.js runs on a single thread by default. Here's how to utilize all CPU cores with clustering.

Basic Cluster Setup#

import cluster from 'cluster';
import http from 'http';
import os from 'os';

const numCPUs = os.cpus().length;

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

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

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

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

Express with Clustering#

// cluster.ts
import cluster from 'cluster';
import os from 'os';

export function startCluster(workerFn: () => void) {
  const numCPUs = os.cpus().length;

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

    // Fork workers
    for (let i = 0; i < numCPUs; i++) {
      const worker = cluster.fork();
      console.log(`Started worker ${worker.process.pid}`);
    }

    // Handle worker events
    cluster.on('exit', (worker, code, signal) => {
      console.log(`Worker ${worker.process.pid} exited (${signal || code})`);

      // Restart worker unless shutting down
      if (!worker.exitedAfterDisconnect) {
        console.log('Starting replacement worker...');
        cluster.fork();
      }
    });

    cluster.on('online', (worker) => {
      console.log(`Worker ${worker.process.pid} is online`);
    });
  } else {
    workerFn();
  }
}

// app.ts
import express from 'express';
import { startCluster } from './cluster';

function startServer() {
  const app = express();

  app.get('/', (req, res) => {
    res.json({
      message: 'Hello',
      pid: process.pid,
    });
  });

  app.get('/heavy', (req, res) => {
    // Simulate CPU-intensive work
    let sum = 0;
    for (let i = 0; i < 1e8; i++) {
      sum += i;
    }
    res.json({ sum, pid: process.pid });
  });

  app.listen(3000, () => {
    console.log(`Worker ${process.pid} listening on port 3000`);
  });
}

startCluster(startServer);

Graceful Shutdown#

import cluster from 'cluster';
import http from 'http';
import os from 'os';

const numCPUs = os.cpus().length;

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

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

  // Graceful shutdown handler
  async function shutdown(signal: string) {
    console.log(`\n${signal} received. Starting graceful shutdown...`);

    // Stop accepting new connections
    for (const worker of Object.values(cluster.workers || {})) {
      worker?.send('shutdown');
    }

    // Wait for workers to finish
    const timeout = setTimeout(() => {
      console.log('Forcing shutdown after timeout');
      process.exit(1);
    }, 30000);

    cluster.on('exit', () => {
      const remaining = Object.keys(cluster.workers || {}).length;
      if (remaining === 0) {
        clearTimeout(timeout);
        console.log('All workers stopped. Exiting.');
        process.exit(0);
      }
    });
  }

  process.on('SIGTERM', () => shutdown('SIGTERM'));
  process.on('SIGINT', () => shutdown('SIGINT'));

  cluster.on('exit', (worker, code, signal) => {
    if (!worker.exitedAfterDisconnect) {
      console.log(`Worker ${worker.process.pid} crashed. Restarting...`);
      cluster.fork();
    }
  });
} else {
  const server = http.createServer((req, res) => {
    res.writeHead(200);
    res.end(`Worker ${process.pid}\n`);
  });

  server.listen(3000);

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

      server.close(() => {
        console.log(`Worker ${process.pid} closed all connections`);
        process.exit(0);
      });

      // Force close after timeout
      setTimeout(() => {
        console.log(`Worker ${process.pid} forcing close`);
        process.exit(0);
      }, 10000);
    }
  });
}

Zero-Downtime Restart#

import cluster from 'cluster';
import http from 'http';
import os from 'os';

const numCPUs = os.cpus().length;

if (cluster.isPrimary) {
  const workers: Set<cluster.Worker> = new Set();

  function forkWorker() {
    const worker = cluster.fork();
    workers.add(worker);

    worker.on('exit', () => {
      workers.delete(worker);
    });

    return worker;
  }

  // Initial fork
  for (let i = 0; i < numCPUs; i++) {
    forkWorker();
  }

  // Zero-downtime restart
  async function restartWorkers() {
    console.log('Starting zero-downtime restart...');

    const currentWorkers = [...workers];

    for (const worker of currentWorkers) {
      // Fork new worker first
      const newWorker = forkWorker();

      // Wait for new worker to be ready
      await new Promise<void>((resolve) => {
        newWorker.on('listening', () => {
          console.log(`New worker ${newWorker.process.pid} is ready`);

          // Gracefully shutdown old worker
          worker.send('shutdown');
          worker.disconnect();

          // Force kill after timeout
          setTimeout(() => {
            if (!worker.isDead()) {
              worker.kill();
            }
          }, 10000);

          resolve();
        });
      });

      // Small delay between restarts
      await new Promise(r => setTimeout(r, 1000));
    }

    console.log('All workers restarted');
  }

  // Trigger restart on SIGUSR2
  process.on('SIGUSR2', restartWorkers);

  cluster.on('exit', (worker, code, signal) => {
    if (!worker.exitedAfterDisconnect && code !== 0) {
      console.log(`Worker ${worker.process.pid} crashed. Restarting...`);
      forkWorker();
    }
  });
} else {
  // Worker code
  const server = http.createServer((req, res) => {
    res.writeHead(200);
    res.end(`Worker ${process.pid}\n`);
  });

  server.listen(3000, () => {
    console.log(`Worker ${process.pid} listening`);
  });

  process.on('message', (msg) => {
    if (msg === 'shutdown') {
      server.close(() => {
        process.exit(0);
      });
    }
  });
}

Shared State with IPC#

import cluster from 'cluster';
import http from 'http';
import os from 'os';

interface Message {
  type: string;
  data?: any;
}

if (cluster.isPrimary) {
  // Shared state in primary process
  const stats = {
    totalRequests: 0,
    requestsByWorker: {} as Record<number, number>,
  };

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

    worker.on('message', (msg: Message) => {
      if (msg.type === 'request') {
        stats.totalRequests++;
        stats.requestsByWorker[worker.process.pid!] =
          (stats.requestsByWorker[worker.process.pid!] || 0) + 1;
      }

      if (msg.type === 'getStats') {
        worker.send({ type: 'stats', data: stats });
      }
    });
  }

  // Log stats periodically
  setInterval(() => {
    console.log('Stats:', stats);
  }, 5000);
} else {
  const server = http.createServer((req, res) => {
    // Notify primary of request
    process.send?.({ type: 'request' });

    if (req.url === '/stats') {
      process.send?.({ type: 'getStats' });

      const handler = (msg: Message) => {
        if (msg.type === 'stats') {
          res.writeHead(200, { 'Content-Type': 'application/json' });
          res.end(JSON.stringify(msg.data));
          process.off('message', handler);
        }
      };

      process.on('message', handler);
    } else {
      res.writeHead(200);
      res.end(`Worker ${process.pid}\n`);
    }
  });

  server.listen(3000);
}

Sticky Sessions#

import cluster from 'cluster';
import http from 'http';
import net from 'net';
import os from 'os';

const numCPUs = os.cpus().length;

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

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

  // Create proxy server
  const server = net.createServer({ pauseOnConnect: true }, (connection) => {
    // Get client IP for sticky routing
    const remoteAddress = connection.remoteAddress || '';

    // Simple hash to pick worker
    let hash = 0;
    for (let i = 0; i < remoteAddress.length; i++) {
      hash = ((hash << 5) - hash) + remoteAddress.charCodeAt(i);
      hash = hash & hash;
    }

    const workerIndex = Math.abs(hash) % workers.length;
    const worker = workers[workerIndex];

    // Send connection to worker
    worker.send('connection', connection);
  });

  server.listen(3000, () => {
    console.log('Primary listening on port 3000');
  });
} else {
  const server = http.createServer((req, res) => {
    res.writeHead(200);
    res.end(`Handled by worker ${process.pid}\n`);
  });

  // Don't bind to port, receive connections from primary
  server.listen(0, 'localhost');

  process.on('message', (message, connection) => {
    if (message === 'connection') {
      server.emit('connection', connection);
      (connection as net.Socket).resume();
    }
  });
}

PM2 Alternative#

// ecosystem.config.js for PM2
module.exports = {
  apps: [{
    name: 'api',
    script: './dist/server.js',
    instances: 'max',        // Use all CPUs
    exec_mode: 'cluster',
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production',
    },
    // Zero-downtime restart
    wait_ready: true,
    listen_timeout: 10000,
    kill_timeout: 5000,
  }],
};

// In your app, signal ready
process.send?.('ready');

// Handle graceful shutdown
process.on('SIGINT', () => {
  // Close connections, etc.
  process.exit(0);
});

Load Testing#

# Install autocannon
npm install -g autocannon

# Test single instance
node app-single.js &
autocannon -c 100 -d 10 http://localhost:3000

# Test cluster
node app-cluster.js &
autocannon -c 100 -d 10 http://localhost:3000

Best Practices#

Scaling:
✓ Match workers to CPU cores
✓ Implement graceful shutdown
✓ Handle worker crashes
✓ Use zero-downtime restarts

State:
✓ Keep workers stateless
✓ Use external storage (Redis)
✓ IPC for coordination only
✓ Avoid shared mutable state

Monitoring:
✓ Track per-worker metrics
✓ Monitor memory usage
✓ Log worker lifecycle events
✓ Set up health checks

Production:
✓ Consider PM2 or similar
✓ Use process managers
✓ Configure restart limits
✓ Set memory limits

Clustering scales Node.js across all CPU cores. Implement graceful shutdown for production reliability, use IPC sparingly for coordination, and keep workers stateless. For production, consider PM2 or Kubernetes for advanced orchestration. Always test with load to verify scaling benefits.