Queues and background jobs

Play this lesson

Work that can wait

When a Shard Garden season ends, Remy's server emails each player a summary, updates leaderboards and hands out rewards. Doing it while the player waits takes 10 seconds.

A queue holds messages in order. The request adds one, "season ended for garden 7", and answers at once. A worker, a background program, takes messages off the queue and does the slow work.

Three parts

Quick check

Why use a queue for the season-end emails?

  1. The player gets an answer at once, and the slow work happens in the background
  2. Queues make emails arrive faster
  3. Emails cannot be sent without a queue
Show the answer

The player gets an answer at once, and the slow work happens in the background

The queue separates "accept the job" from "do the job", so a slow job never makes a player wait.

At least once

The studio hosts on Cloudflare, whose Queues documentation says messages "are guaranteed to be delivered at least once, and in rare occasions, may be delivered more than once."

At least once is the safe side: a message is never silently lost. The price is that a worker can see the same message twice.

Make a repeat harmless

Cloudflare's advice: give each message a unique ID when it is written, then use that ID as a primary key or an idempotency key, so a second delivery changes nothing.

If delivery keeps failing, Cloudflare retries it, three times by default, then moves it to a dead letter queue where a person can look at it.

Quick check

With at-least-once delivery, a worker may receive the same message twice.

Show the answer

True

Rarely, but it happens. Workers are written so that handling a message twice has the same effect as handling it once.

Bug hunt

rewards-worker.js
async function onMsg(m) {  const { id, seeds } =    m.body;  const p =    await db.get(id);  p.seeds += seeds;  await db.put(id, p);}

Priya sees this reward message delivered twice. What happens?

  1. The player gets the seeds twice, because nothing checks whether the message was already handled
  2. Nothing: queues never deliver twice
  3. The worker crashes
Show the answer

The player gets the seeds twice, because nothing checks whether the message was already handled

The worker should record each message ID it has handled and skip one it has seen before.

One message, many listeners

A queue gives each message to one worker. But some news, like "a wave was cleared", matters to several parts of the game at once.

Bolt says: Next: events and pub/sub.

Fact-checked 12 October 2026