Node.js traps · Chapter 2 of 16
process.nextTick starves I/O
Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: The event loop
- 3 tasks
- Node.js
- Free chapter
Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.
The lesson
By the end of this case
You can tell when a "small steps" loop is still holding the event loop, show it on purpose with a health check and a backlog, fix it with batches that take turns with everyone else, and guard it with a test that counts what ran before the health check.
The ticket
PAR-715: Kiosks froze when Hamlet in Hinglish was cancelled. Assigned to you by Nikhil. Priority: high. Since: the SMS worker moved into the API process.
Datta, in the support channel at 6:12 pm: "We cancelled Saturday's Hamlet in Hinglish at 6:05 and pressed Refund all. For about ten seconds every kiosk at Kala Talkies showed the spinner, and two people at the counter could not pay for tonight's show. After that, all the refund messages went out and everything was fine."
The load balancer's log and the API's own line, from this evening:
18:05:31.140 lb GET /healthz api-2: no answer in 2000 ms (1 of 3)
18:05:35.144 lb api-2 marked down after 3 failed checks, restarting
18:05:41.902 api sms: sent 5000 messages
Nikhil: "In August we moved the SMS worker into the API process to save a server. It sends one message at a time and schedules the next one, so I was sure it could never hold the loop for long. 5,000 refund messages went into the queue at once. Reproduce it, fix it, and make sure it never comes back. You are in sms-queue.js."
The queue that runs before the loop
Case 1 showed that one long callback holds the event loop. Here no callback is long: each one sends a single message. The trap is where the next one goes. Node keeps several queues. Timers, I/O and setImmediate callbacks are handled by the event loop, one phase after another. process.nextTick callbacks are different: Node empties the nextTick queue completely after the current operation, before the loop moves on to anything else. Promise callbacks (microtasks) are emptied at the same point.
So a step that schedules the next step with process.nextTick never lets the queue empty. Here is a reminder list that "prints" one name per tick, with a kiosk request (a setImmediate) waiting:
const names = Array.from({ length: 100_000 }, (_, i) => `seat holder ${i + 1}`);
let printed = 0;
function next() {
if (printed === names.length) return;
printed += 1; // pretend to print names[printed - 1]
process.nextTick(next);
}
setImmediate(() => console.log('kiosk answered after', printed, 'names'));
next();
kiosk answered after 100000 names
A hundred thousand small steps behaved exactly like one huge one.
Taking turns
setImmediate puts the next step behind everything the loop is already waiting for: I/O, timers, other requests. Do a batch, then let the loop take a turn:
function next() {
for (let n = 0; n < 500 && printed < names.length; n++) printed += 1;
if (printed < names.length) setImmediate(next);
}
kiosk answered after 500 names
The batch size is a trade: bigger batches finish the job sooner, smaller ones keep each turn short. And a microtask is not a way out: with queueMicrotask(next) in place of process.nextTick(next), the same script prints kiosk answered after 100000 names.
Making it happen on purpose
No clock is needed. Fill the queue with a backlog, start the drain, and right after it start a health check with setImmediate, which remembers how many messages had gone out when it was answered. Beside the bug the answer is the whole backlog; beside a fix it is one batch. The send you hand the queue is your window into it: it only counts.
A test that would have caught it
The guard does the same and expects at most one batch before the health check. It also checks the other side: in the end every message was sent, once, in order, so a fix that sends fewer, or drops the ones that arrive while draining, fails too.
Your turn
Three tasks, one file each. In repro.js, make the health check wait for the backlog and run it with node repro.js in the case's folder. In sms-queue.js, send in batches of at most 100 and let the loop take a turn between them. In sms-queue.test.js, write the guard: the check runs it beside the original code, the fix and a wrong fix that uses microtasks. Then answer Nikhil's interview question at the bottom of the case, in your own words.
What you build: 3 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
repro.js: make the health check wait for the backlog
Write reproduce() in repro.js. Make a queue with createSmsQueue({ send }) from sms-queue.js, where send only counts the messages it is given, and push 2,000 messages (any { to, text }). Call drain(), and right after it start a health check: a Promise around setImmediate whose callback resolves to how many messages had been sent when it ran. Wait for both and resolve to that number.
The check runs your reproduce() twice: beside the original sms-queue.js it must resolve to 2000 (the health check waited for every message), and beside a fixed sms-queue.js to 100 (it ran after the first batch). Call drain() first, then start the health check, before you wait for either. No real waiting and no setTimeout: reproduce() must finish within 2 seconds.
- Task 2
sms-queue.js: a drain that takes turns with everyone else
Fix drain() in sms-queue.js so it sends in batches of at most 100 messages, and lets the event loop take a turn between batches. Every message must be sent exactly once, in the order it was pushed; messages pushed while the queue drains are sent by the same drain, after the others. When the queue is empty, drain() resolves to how many messages it sent and logs sms: sent <n> messages; an empty queue resolves to 0.
Keep the exports and the log line as they are. The check uses its own messages (750, with 5 more pushed while it drains), counts the turns of the event loop with a setImmediate pinger and fails if more than 100 messages are sent in one turn.
- Task 3
sms-queue.test.js: a test that would have caught it
Write a vitest test file, sms-queue.test.js, that would have caught the freeze before the cancelled show. The check runs your file three times: beside the original sms-queue.js, where at least one test must fail; beside the fixed sms-queue.js, where every test must pass; and beside a wrong fix that swaps process.nextTick for queueMicrotask, where at least one test must fail.
So push 2,000 messages, call drain() and start a health check with setImmediate right after it, and check both sides: when the health check ran, at most 100 messages had been sent; and in the end every message was sent once, in order, and drain() resolved to 2000. Each test must finish within 3 seconds.
What you will learn
- repro.js: make the health check wait for the backlog
- sms-queue.js: a drain that takes turns with everyone else
- sms-queue.test.js: a test that would have caught it
More in The event loop
Build "process.nextTick starves I/O" yourself
Parda's booking backend has run on Node for a year, and Nikhil keeps handing you incidents where Node did exactly what the team told it. Each is a runtime trap interviews love to ask about. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.