Cluster & Worker Threads

// main.js
const { Worker } = require('worker_threads');

const worker = new Worker('./heavy-task.js', {
  workerData: { iterations: 1e8 }
});

worker.on('message', (result) => {
  console.log('Result:', result);
});

worker.on('error', (err) => console.error(err));
worker.on('exit', (code) => console.log('Exited with code:', code));

// heavy-task.js
const { workerData, parentPort } = require('worker_threads');
let sum = 0;
for (let i = 0; i < workerData.iterations; i++) sum += i;
parentPort.postMessage(sum);

Why it matters: CPU-bound operations block the event loop and make the entire Node.js server unresponsive; worker_threads let you offload that work to a parallel thread while the main thread continues serving requests.

Real applications: PDF generation, video transcoding, machine learning inference, large CSV parsing, and SHA-based proof-of-work systems all benefit from running in worker threads.

Common mistakes: Creating a new Worker per request is expensive; use a worker pool (e.g., piscina) to reuse threads and avoid creation overhead under load.

const { spawn, fork } = require('child_process');

// spawn — run any command
const ls = spawn('ls', ['-la']);
ls.stdout.on('data', (data) => console.log(data.toString()));

// fork — run a Node.js script with IPC
const child = fork('./worker.js');
child.send({ task: 'compute' });
child.on('message', (result) => {
  console.log('Worker result:', result);
});

Why it matters: Choosing spawn vs fork vs exec is a frequent interview question; the wrong choice can cause buffering issues, IPC failures, or unnecessary memory overhead.

Real applications: Build pipelines use spawn to stream compiler output; background job processors use fork to run Node.js tasks with IPC result reporting.

Common mistakes: Using exec (or fork) to run long-running commands with large output hits the default 1MB buffer limit and crashes with ERR_BUFFER_OUT_OF_MEMORY; use spawn for streaming output.

// primary.js
const { fork } = require('child_process');
const child = fork('./child.js');

child.send({ type: 'START', data: [1, 2, 3] });

child.on('message', (msg) => {
  console.log('From child:', msg);
});

// child.js
process.on('message', (msg) => {
  if (msg.type === 'START') {
    const result = msg.data.reduce((a, b) => a + b, 0);
    process.send({ type: 'RESULT', value: result });
  }
});

Why it matters: IPC is the backbone of the cluster module and child_process patterns; understanding its serialization model prevents bugs when passing complex data between processes.

Real applications: Cluster primaries use IPC to broadcast configuration updates to workers; job queue systems use child_process IPC to report task completion back to the scheduler.

Common mistakes: Sending functions or class instances via IPC silently drops those properties since structured clone cannot serialize non-serializable values; always serialize to plain objects first.

const cluster = require('cluster');
const os = require('os');

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

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

  // Monitor worker health
  setInterval(() => {
    for (const id in cluster.workers) {
      cluster.workers[id].send('health-check');
    }
  }, 30000);
} else {
  require('./server'); // Each worker runs the server
}

Why it matters: Understanding how Node.js distributes connections across workers is essential for diagnosing uneven load distribution and tuning cluster performance.

Real applications: Production APIs use cluster-based round-robin combined with an Nginx upstream to distribute traffic across server instances and individual worker processes.

Common mistakes: On Windows, Node.js cluster doesn't use round-robin — connections go to whichever worker the OS picks, which can result in uneven distribution; use an external load balancer for consistent behavior.

// main.js
const { Worker } = require('worker_threads');

const shared = new SharedArrayBuffer(4); // 4 bytes
const arr = new Int32Array(shared);
arr[0] = 0;

const worker = new Worker('./worker.js', {
  workerData: { shared }
});

worker.on('exit', () => {
  console.log('Counter:', arr[0]); // Modified by worker
});

// worker.js
const { workerData } = require('worker_threads');
const arr = new Int32Array(workerData.shared);
Atomics.add(arr, 0, 100); // Thread-safe increment

Why it matters: SharedArrayBuffer enables the highest-throughput data sharing between threads, eliminating the serialization overhead of postMessage for large data payloads.

Real applications: WebAssembly audio worklets, real-time video frame processing in Electron, and numerical simulation engines all use SharedArrayBuffer to share large typed arrays between threads.

Common mistakes: Reading or writing SharedArrayBuffer without Atomics operations leads to race conditions; and SharedArrayBuffer requires cross-origin isolation headers (COOP/COEP) in browser environments.

# Start with cluster mode (all CPU cores)
pm2 start app.js -i max

# Common commands
pm2 list                  # List all processes
pm2 logs                  # View logs
pm2 monit                 # Real-time monitoring
pm2 restart app           # Restart app
pm2 reload app            # Zero-downtime reload
pm2 stop app              # Stop app
pm2 delete app            # Remove from PM2

# Ecosystem file (ecosystem.config.js)
module.exports = {
  apps: [{
    name: 'my-app',
    script: 'app.js',
    instances: 'max',
    exec_mode: 'cluster',
    env: { NODE_ENV: 'production' }
  }]
};

Why it matters: PM2 is the de-facto standard process manager for production Node.js deployments; knowing its CLI commands and ecosystem config is expected in senior interviews.

Real applications: VPS and bare-metal Node.js deployments, CI/CD pipelines, and self-hosted APIs all rely on PM2 for process management, auto-restart on crash, and log aggregation.

Common mistakes: Using pm2 restart instead of pm2 reload in production causes a brief downtime since restart kills all workers simultaneously rather than rolling them one at a time.

const { exec, spawn } = require('child_process');

// exec — buffers output, good for small results
exec('ls -la', (error, stdout, stderr) => {
  if (error) throw error;
  console.log(stdout);
});

// spawn — streams output, good for large data or long-running
const child = spawn('find', ['.', '-name', '*.js']);
child.stdout.on('data', (data) => {
  console.log('Found:', data.toString());
});
child.on('close', (code) => {
  console.log('Exited with code:', code);
});

Why it matters: Choosing exec vs spawn affects memory usage, output buffering, and security; using exec with user-controlled input enables shell injection attacks.

Real applications: Git command wrappers in CI tools use exec for short-output commands; log processing pipelines and live build output use spawn to stream data without buffering limits.

Common mistakes: Never pass unsanitized user input to exec() since it runs in a shell — an attacker can inject shell commands; use spawn() with an explicit args array instead, which bypasses the shell entirely.

// Check default pool size
console.log('Default pool size: 4');

// Increase pool size via environment variable
// Set BEFORE requiring any modules
process.env.UV_THREADPOOL_SIZE = 16;

// Or set when starting the process
// UV_THREADPOOL_SIZE=16 node app.js

const crypto = require('crypto');

// Each pbkdf2 call uses a thread pool thread
for (let i = 0; i < 8; i++) {
  crypto.pbkdf2('password', 'salt', 100000, 64, 'sha512', () => {
    console.log(`Hash ${i} complete`);
  });
}

Why it matters: A default libuv thread pool of 4 is a common hidden bottleneck in production apps doing heavy crypto or file I/O; knowing how to tune it can dramatically improve throughput.

Real applications: Password hashing services (bcrypt, pbkdf2), file upload processors, and DNS-heavy proxy services all benefit from a larger libuv thread pool.

Common mistakes: Setting process.env.UV_THREADPOOL_SIZE after requiring crypto or fs has no effect — the pool is initialized at startup; always set it via the environment before launching the process.

// 1. Cluster module — multi-process on one server
const cluster = require('cluster');
if (cluster.isPrimary) {
  for (let i = 0; i < 4; i++) cluster.fork();
}

// 2. PM2 cluster mode
// pm2 start app.js -i max

// 3. Nginx load balancer (nginx.conf)
upstream node_app {
    server 127.0.0.1:3001;
    server 127.0.0.1:3002;
    server 127.0.0.1:3003;
}
server {
    listen 80;
    location / {
        proxy_pass http://node_app;
    }
}

// 4. Docker + orchestration
// docker-compose scale app=4

Why it matters: Horizontal scaling is the primary way to achieve production-grade availability and throughput in Node.js; understanding the trade-offs between cluster, PM2, and container orchestration is essential.

Real applications: SaaS platforms use Kubernetes to auto-scale Node.js pods under traffic spikes; smaller teams use PM2 cluster mode behind Nginx for a simpler multi-core setup.

Common mistakes: Scaling horizontally before making the app stateless causes consistency bugs — one instance updates a user's local in-memory state while another serves subsequent requests that don't see the update.

const { Worker } = require('worker_threads');
const os = require('os');

class WorkerPool {
  constructor(workerScript, poolSize = os.cpus().length) {
    this.workers = [];
    this.queue = [];
    
    for (let i = 0; i < poolSize; i++) {
      this.workers.push({ worker: new Worker(workerScript), busy: false });
    }
  }
  
  runTask(data) {
    return new Promise((resolve, reject) => {
      const available = this.workers.find(w => !w.busy);
      
      if (available) {
        this._execute(available, data, resolve, reject);
      } else {
        this.queue.push({ data, resolve, reject });
      }
    });
  }
  
  _execute(workerInfo, data, resolve, reject) {
    workerInfo.busy = true;
    workerInfo.worker.postMessage(data);
    
    workerInfo.worker.once('message', (result) => {
      workerInfo.busy = false;
      resolve(result);
      
      if (this.queue.length > 0) {
        const next = this.queue.shift();
        this._execute(workerInfo, next.data, next.resolve, next.reject);
      }
    });
    
    workerInfo.worker.once('error', reject);
  }
}

const pool = new WorkerPool('./hash-worker.js', 4);
const result = await pool.runTask({ password: 'secret' });

Why it matters: Without a pool, creating one worker per request under load wastes time on thread initialization and can exhaust memory; a bounded pool keeps resource usage predictable.

Real applications: Image resizing APIs, encryption services, and data-processing microservices all run a worker pool sized to the number of CPU cores to maximize throughput without over-provisioning threads.

Common mistakes: Not handling worker error events in the pool causes unhandled promise rejections; and not properly cleaning up once listeners after each task creates listener leaks.

const cluster = require('cluster');

if (cluster.isPrimary) {
  // Fork workers
  for (let i = 0; i < 4; i++) cluster.fork();
  
  // Graceful shutdown handler
  process.on('SIGTERM', () => {
    console.log('Primary received SIGTERM, shutting down workers...');
    
    for (const id in cluster.workers) {
      cluster.workers[id].send('shutdown');
    }
    
    // Force kill after timeout
    setTimeout(() => {
      console.log('Force killing remaining workers');
      process.exit(1);
    }, 30000);
  });
} else {
  const server = require('./server');
  
  process.on('message', (msg) => {
    if (msg === 'shutdown') {
      console.log('Worker ' + process.pid + ' shutting down...');
      
      // Stop accepting new connections
      server.close(() => {
        console.log('Worker ' + process.pid + ' closed cleanly');
        process.exit(0);
      });
    }
  });
}

Why it matters: Abruptly killing workers during deployment drops active HTTP connections and can corrupt in-progress database transactions; graceful shutdown prevents all of these issues.

Real applications: Container orchestrators (Kubernetes) send SIGTERM before terminating pods; Node.js servers must handle it correctly to avoid 502 errors during rolling deployments.

Common mistakes: Not setting a force-kill timeout means a hung worker with an open database connection keeps the process alive indefinitely, blocking the deployment.

const { Worker, MessageChannel } = require('worker_threads');

// Create two workers that communicate directly
const worker1 = new Worker('./processor.js');
const worker2 = new Worker('./aggregator.js');

// Create a direct channel between them
const { port1, port2 } = new MessageChannel();

// Transfer ports to workers (transfers ownership)
worker1.postMessage({ port: port1 }, [port1]);
worker2.postMessage({ port: port2 }, [port2]);

// processor.js
const { parentPort } = require('worker_threads');
parentPort.once('message', ({ port }) => {
  // Send data directly to aggregator
  port.postMessage({ processed: [1, 2, 3] });
  port.on('message', (msg) => console.log('From aggregator:', msg));
});

// aggregator.js
const { parentPort } = require('worker_threads');
parentPort.once('message', ({ port }) => {
  port.on('message', (data) => {
    const sum = data.processed.reduce((a, b) => a + b, 0);
    port.postMessage({ total: sum });
  });
});

Why it matters: Direct worker-to-worker communication via MessageChannel bypasses the main thread bottleneck in pipeline-style architectures where one worker produces data for another to consume.

Real applications: Video processing pipelines where one worker decodes frames and a second worker applies filters use MessageChannel to stream frame data directly between them.

Common mistakes: Forgetting to include the port in the transferList of postMessage clones it instead of transferring ownership, which throws an error if the port is already detached.

const { Worker } = require('worker_threads');

function createMonitoredWorker(script, data) {
  const worker = new Worker(script, { workerData: data });
  
  const stats = {
    startTime: Date.now(),
    messagesReceived: 0,
    lastHeartbeat: Date.now()
  };
  
  // Track messages
  worker.on('message', (msg) => {
    stats.messagesReceived++;
    if (msg.type === 'heartbeat') {
      stats.lastHeartbeat = Date.now();
    }
  });
  
  // Monitor for errors
  worker.on('error', (err) => {
    console.error('Worker error:', err.message);
    console.error('Stack:', err.stack);
  });
  
  // Track exits
  worker.on('exit', (code) => {
    const runtime = (Date.now() - stats.startTime) / 1000;
    console.log('Exit code:', code, 'Runtime:', runtime + 's');
    if (code !== 0) {
      console.log('Restarting worker...');
      createMonitoredWorker(script, data);
    }
  });
  
  // Detect stalled workers
  setInterval(() => {
    if (Date.now() - stats.lastHeartbeat > 10000) {
      console.log('Worker stalled, terminating...');
      worker.terminate();
    }
  }, 5000);
  
  return worker;
}

Why it matters: Without monitoring, a crashed or stalled worker silently fails to process work while the pool continues to queue tasks that never complete, degrading throughput.

Real applications: Production worker pools for image processing and data transformation services use heartbeat monitoring to auto-restart stalled workers and alert on unusually long task durations.

Common mistakes: Attaching worker.on('message', ...) inside the task execution instead of once at worker creation accumulates duplicate listeners, causing the same message to be handled multiple times.

// Cluster — best for scaling HTTP servers across CPU cores
const cluster = require('cluster');
if (cluster.isPrimary) {
  for (let i = 0; i < 4; i++) cluster.fork();
} else {
  app.listen(3000); // All workers share port 3000
}

// Worker threads — best for CPU-intensive tasks
const { Worker } = require('worker_threads');
app.post('/process-image', async (req, res) => {
  const worker = new Worker('./image-processor.js', {
    workerData: { image: req.body.image }
  });
  worker.on('message', (result) => res.json(result));
});

Why it matters: This is one of the most common Node.js architecture interview questions; candidates are expected to clearly articulate when to use each approach and why.

Real applications: An Express API uses cluster to handle concurrent HTTP requests across cores, while within each worker a thread pool handles CPU-heavy operations like image resize requests.

Common mistakes: Using worker_threads to scale a web server (they don't share ports) instead of cluster; or using cluster to do CPU-heavy work (separate processes waste memory) instead of worker_threads.