Queues That Keep Slow Work Off the Page

Some work is fast: saving a setting, loading a page, updating a title. Some work is slow: sending a newsletter to thousands of people, processing a large import, resizing a batch of images, generating a report or preparing a backup. If slow work runs while a person waits for a page, the page hangs, times out or fails halfway.

Queues solve that. Slow work is placed in a queue, the page responds right away and background workers process the queue. Done well, people get fast pages and honest progress. Done poorly, work disappears into a black box. Here is how we approach it.

Decide what belongs in the queue

We ask a few questions about each piece of work:

1. How long can it take? Anything that can take more than a moment, or that depends on an outside service, is a queue candidate.
2. Does the person need the result right now? A saved setting does; a finished export can arrive a minute later.
3. Could it fail partway? Long work with many steps is safer in a queue, where it can be retried or resumed.
4. Does it touch many records? Bulk work belongs in the background, often in batches.

Sending email, processing media, running imports, building exports and preparing backups all run in queues on our platform.

Show progress honestly

When work moves to the background, people need to know what is happening. Our long-running workflows show their status: queued, in progress, completed or failed. An import shows its progress through each stage. A backup shows when it is being prepared and when it has been verified. A status that never changes is worse than no status, so failed work is closed with a clear state rather than left "in progress" forever.

Fail clearly and allow retry

Background work can fail: an outside service is down, a file is unreadable, a time limit is reached. When that happens, the work is marked as failed, partial results are cleaned up where possible and the person sees a plain explanation with a way to retry. Technical details go to our logs, not to the screen. We follow the same pattern for backups, described in a backup is not a backup until it is verified.

Retries that do not repeat damage

Queues retry failed jobs automatically, which is helpful for temporary problems and dangerous for jobs that are not safe to repeat. Our jobs are designed so a retry does not send an email twice, charge twice or create duplicate records. When an outcome is uncertain, the job stops for review rather than retrying blindly.

Jobs remember whose work they are

Every job records which organization and website it belongs to and restores that context before it runs, so background work never reads or writes the wrong account's data. That pattern is described in detail in background jobs that remember their context.

Not everything should be queued

Sometimes running work immediately is the better choice. When we publish content as part of a release, for example, we save the content immediately so it is visible right away, and leave only the slow extras, like generating extra image sizes, to the queue. Splitting work that way gives people the fast result they need and keeps slow work out of their way.

Workers are watched

Background workers are long-running processes that must be restarted when new code is released and monitored so they do not silently stop. Our releases restart them, our dashboards show their health and a stalled queue is treated as an incident. A queue that nobody is watching is just a place where work goes to be forgotten.

Frequently asked questions

What is a job queue?

A job queue holds tasks to be processed in the background, so pages can respond quickly while slow work like sending email or processing files happens separately.

How do I know if background work finished?

Long-running work on our platform shows its status, such as queued, in progress, completed or failed, with a way to retry failures.

Can a background job run twice?

It can, because queues retry failures. Jobs are designed so that running twice does not send, charge or create anything twice.