Concurrency and races · Chapter 1 of 15

The token refresh race

Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Two requests at once
  • 3 tasks
  • JavaScript
  • 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 a token refresh race from its symptoms, make it happen on purpose by starting requests together, fix it with one shared refresh, and pin it down with a test that fails on the race and passes on the fix.

The ticket

TAP-811: Customers logged out every morning. Assigned to you by Kabir. Priority: high. Since: Monday's release.

Anjali, in the support channel at 9:20 am: "Forty-one messages since Monday, all the same: people open the app in the morning and land on the login screen. Priya in Koramangala logged in three times this week. Nobody changed their password. If they open it again later in the day, it is fine."

The app's session log for Priya at 8:02 am, with the auth server's lines beside it:

08:02:14.310  auth     refresh-7Kq used, new pair issued
08:02:14.312  auth     refresh-7Kq used again: reuse detected, session revoked
08:02:14.315  session  session: refresh failed, logging out (refresh token reused, session revoked)
08:02:14.316  session  session: refresh failed, logging out (refresh token reused, session revoked)

Kabir: "Monday's release did two things. The home screen now loads the menu, your points and your recent orders at the same time. And the auth server started rotating refresh tokens: each one works once. Access tokens live 15 minutes, so the first open of the morning always starts with an expired one. Look at the times on those lines. Reproduce it, fix it, and make sure it never comes back. You are in session.js."

A pass that works once

Rotation makes a refresh token a one-time pass: swap it and you get a new pair, and the old one is spent. If a spent one is ever used again, the server assumes it was stolen and revokes the whole session. That is the right thing for a server to do, and it is what logged Priya out.

Here is the same idea with a gate that takes a one-time pass, and two riders who share one pass:

let pass = 'P1';
const gate = {
  async enter(code) {
    await new Promise((r) => setImmediate(r)); // the network
    if (code !== pass) throw new Error(`pass ${code} already used`);
    pass = `P${Number(code.slice(1)) + 1}`;
    return pass;
  },
};

let myPass = 'P1';
async function goIn(who) {
  console.log(`${who} shows ${myPass}`);
  myPass = await gate.enter(myPass);
  console.log(`${who} is in, next pass ${myPass}`);
}

const results = await Promise.allSettled([goIn('Imran'), goIn('Sunita')]);
console.log(results.map((r) => r.status));
Imran shows P1
Sunita shows P1
Imran is in, next pass P2
[ 'fulfilled', 'rejected' ]

Between one await and the next

Nothing here runs at the same instant: Node runs one thing at a time. The race is in the gap. Each await hands control back, and while Imran waits for the gate, Sunita reads myPass, which nobody has updated yet. Both are between one await and the next, holding the same old value.

Run the two one after the other and the bug disappears:

Imran shows P1
Imran is in, next pass P2
Sunita shows P2
Sunita is in, next pass P3

That is why it never showed up on a laptop: one request at a time, or a token that never expired while you tested. It needs two things to line up: an expired token and requests that start together.

Making it happen on purpose

To reproduce a race, you start the calls together (call them all, then wait with Promise.allSettled, which waits for every one whether it works or fails) against a stand-in that behaves like the real server. auth-server.js is one: it rotates, it detects reuse, and it answers on a later turn of the event loop, like a network.

The check goes further: it holds an answer back to look inside the gap. Promise.withResolvers() gives a promise and the function that settles it; setImmediate lets everything waiting run:

const answer = Promise.withResolvers();
const kitchen = { ready: () => answer.promise };
let served = 0;

async function serve() {
  await kitchen.ready();
  served += 1;
}

const both = Promise.all([serve(), serve()]);
await new Promise((r) => setImmediate(r));
console.log('kitchen still cooking, served:', served);
answer.resolve();
await both;
console.log('kitchen answered, served:', served);
kitchen still cooking, served: 0
kitchen answered, served: 2

A test that would have caught it

A guard test in vitest (it names a test, expect checks a value) makes the race happen before every release: expire the token, start several requests together, then check both sides: the server was asked to refresh exactly once, and every request still got its answer. A test that only counts refreshes passes code that skips the refresh and lets the other requests fail; a test that only checks answers misses the extra refreshes.

Your turn

Three tasks, one file each. In repro.js, log a customer out on purpose with auth-server.js, and run it with node repro.js in the case's folder. In session.js, make every request that needs a refresh share the one already on its way. In session.test.js, write the guard: the check runs it beside the original code, the fix and a wrong fix. Then answer Kabir'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.

  1. Task 1

    repro.js: log a customer out on purpose

    Write reproduce() in repro.js. Make a stand-in server with createAuthServer() from auth-server.js, and a session with createSession(server) from session.js (the server holds the auth, api and tokens createSession needs). Call server.expireAccess(), then start three requests at the same time with session.request (any paths, say '/menu', '/points' and '/orders'), wait until all three have settled, whether they worked or not, and resolve to session.status.

    The check runs your reproduce() twice: beside the original session.js it must resolve to 'logged-out' (the race logged the customer out), and beside a fixed session.js it must resolve to 'signed-in'. Requests made one after another never race, so start all three before waiting for any. No real waiting: the stand-in answers on the next turn of the event loop, and reproduce() must finish within 2 seconds.

  2. Task 2

    session.js: one refresh, shared by every request

    Fix createSession({ auth, api, tokens }) in session.js. When requests get a 401 while a refresh is already on its way, they must not start their own: they wait for that same refresh and then retry with the new access token. So three 401s at once make exactly one call to auth.refresh, and all three requests resolve to their body. When the new access token expires later, the next 401 starts a new refresh with the new refresh token: a finished refresh is never shared with the next expiry.

    When the shared refresh fails, status becomes 'logged-out' and every request waiting for it logs session: refresh failed, logging out (<the error's message>) and rejects with an Error 'please log in again'. Keep that log line, the error messages and status as they are. The check uses its own stand-in, holds the refresh's answer back while it counts the refreshes, and lets the token expire three times.

  3. Task 3

    session.test.js: a test that would have caught it

    Write a vitest test file, session.test.js, that would have caught this race before the release. The check runs your file three times: beside the original session.js, where at least one test must fail; beside the fixed session.js, where every test must pass; and beside a wrong fix where requests that find a refresh running skip it and retry at once with the old token, where at least one test must fail.

    So use the stand-in from auth-server.js, expire the access token, start several requests at once, and check both sides: server.refreshCalls() holds one refresh token, every request resolved to its body, and session.status is 'signed-in'. No real waiting: each test must finish within 3 seconds.

What you will learn

  • repro.js: log a customer out on purpose
  • session.js: one refresh, shared by every request
  • session.test.js: a test that would have caught it

More in Two requests at once

Build The token refresh race yourself

Tapri's backend grew busy, and Kabir keeps handing you incidents that only happen when two things run at once. Each is a race 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.