How Node really works · Chapter 25 of 34

Cluster

By the end of this chapter you can run several copies of a server on one port, replace one that crashes, and stop them all cleanly. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: The system
  • 5 tasks
  • Node.js
  • In the all labs plan

The first 2 chapters of How Node really works are free. This one comes with the all labs plan.

Why you need this

At the Friday 4 pm rush the order server sits at 100% of one CPU core while the other cores of the machine do nothing, and the kitchen tablet freezes. Kabir wants more copies of the server sharing the work, a new copy whenever one crashes, and a clean stop when the deploy tool shuts the app down.

One Node process runs your JavaScript on one thread, so it uses one core. Starting the same server twice does not help: the second copy cannot listen on a port that is already taken.

Error: listen EADDRINUSE: address already in use :::4000

What you build: 5 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    primary.js: start two workers that share one port

    primary.js is run as node primary.js (the check sets PORT=0, so the first worker gets a free port and the second shares it; the worker code is already written). The primary forks exactly 2 workers, no more, whatever the machine's CPU count says.

    Each time a worker starts listening, the primary prints one line on stdout: listening <workerPid> <port>, with the worker's process id (never the primary's own) and the port it listens on. Both lines show the same port.

  2. Task 2

    primary.js: let both workers take orders

    New connections to the shared port must reach both workers: over 8 requests, each on a fresh connection, both worker process ids answer, and every answer has status 200.

    Keep Node's default round-robin scheduling, and keep both workers serving.

  3. Task 3

    primary.js: replace a worker that crashes

    When a worker dies on its own (a request to /crash makes it exit with code 1), the primary prints restart <deadWorkerPid> on stdout and then forks a replacement. The replacement prints its own listening line, on the same port as before, and from then on requests reach the surviving worker and the replacement.

  4. Task 4

    primary.js: shut the whole cluster down cleanly on SIGTERM

    When the primary receives SIGTERM, it disconnects all the workers (they stop taking connections, finish what they are serving and exit) and then the primary exits with code 0, within 4 seconds. No worker may be restarted during the shutdown: no restart line, no new listening line, and both worker processes are gone afterwards.

  5. Task 5 · interview question

    Interview: bestTool, choose cluster, worker threads or a process manager

    Fill bestTool in exercise.js: for each of its five jobs, write exactly 'cluster', 'worker_threads' or 'process manager'. Keep the five keys as they are.

What you will learn

  • Primary and workers: one file that forks copies of itself, all listening on one port.
  • Round robin: how new connections are shared out.
  • The exit event: noticing a dead worker and starting another.
  • SIGTERM and disconnect: stopping without cutting requests off.

More in The system

Build "Cluster" yourself

Tapri’s order server must never stall at the 4 pm rush. You learn why it would. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of How Node really works are free. This one comes with the all labs plan.