Skip to main content

Queues

1. Concept Overview​

Queues in RelayX are used for asynchronous background work.

A queue lets you push a job into the system and have one or more workers process that job later. This is useful when work should not block a request, takes time, or needs retry behavior.

Queues exist to solve one problem:

Run background jobs reliably when failures can happen.

Queues are not meant for real-time fan-out, event broadcasting, or workflows. They are for work that must eventually run, even if workers crash or restart.

2. How to Think About It​

Think of a queue like this:

  • A producer enqueues a job
  • One worker receives the job
  • The worker processes the job
  • The worker acknowledges the job when done

Important mental model points:

  • Only one worker processes a given job at a time
  • Jobs may be delivered more than once
  • A job is considered “done” only after acknowledgement
  • The backend deduplicates jobs, not your code
  • Worker crashes are expected and handled

Queues assume failure. They are built around it.

3. What Happens Step by Step​

This is the lifecycle of a job in a RelayX queue:

  1. A producer enqueues a job into a queue.
  2. The RelayX backend receives and stores the job.
  3. The job is deduplicated by the backend.
  4. The backend delivers the job to an available worker.
  5. The worker starts processing the job.
  6. If the worker acknowledges the job, the job is marked complete.
  7. If the worker crashes or disconnects before acknowledgement, the job is delivered again.
  8. If the acknowledgement timeout expires, the job is delivered again.

This flow is deterministic and does not depend on worker implementation details.

4. Guarantees​

RelayX provides the following guarantees for queues:

  • Jobs are delivered at least once.
  • A job is delivered to only one worker at a time.
  • A job is considered complete only after explicit acknowledgement.
  • Jobs are redelivered if a worker crashes or fails to acknowledge in time.
  • Jobs are deduplicated by the RelayX backend.

Anything not listed here is not guaranteed.

5. Failure Cases​

Worker crashes during processing​

What caused it
The worker process exits or crashes while handling a job.

What RelayX does
The job is marked incomplete and scheduled for redelivery.

What the user will see
Another worker (or the same one after restart) receives the job again.

What the user must handle
Job handlers must be safe to run more than once.

Worker does not acknowledge in time​

What caused it
The worker takes too long or never sends an acknowledgement.

What RelayX does
The acknowledgement timeout expires and the job is redelivered.

What the user will see
The same job is delivered again.

What the user must handle
Workers must acknowledge only after work is actually complete.

Producer crashes after enqueueing​

What caused it
The producer crashes immediately after enqueueing a job.

What RelayX does
If the job reached the backend, it will be processed normally.

What the user will see
A worker receives the job.

What the user must handle
Producers should not assume enqueueing and local state updates are atomic.

6. What This Does Not Do​

Queues do not:

  • Guarantee exactly-once execution
  • Support delayed or scheduled jobs
  • Execute workflows or multi-step pipelines
  • Provide transactional semantics
  • Coordinate multiple jobs together

Queues run jobs. They do not manage business processes.

7. Correct Ways to Use This​

Queues work best when:

  • Jobs are idempotent
  • Work can be retried safely
  • Processing may take time
  • Failure is expected

Good examples include:

  • Sending emails
  • Processing uploads
  • Generating reports
  • Syncing data with external systems

8. Common Mistakes​

Assuming exactly-once execution​

Backend deduplication does not prevent a job handler from running twice.
Crashes and timeouts will cause redelivery.

Acknowledging too early​

Acknowledging before work is complete can cause silent data loss.
Always acknowledge after successful processing.

Using queues as workflows​

Queues do not enforce ordering across jobs.
Retries will break step-by-step assumptions.

9. When This Is the Wrong Tool​

Queues are the wrong choice if you need:

  • Scheduled or delayed execution
  • Exactly-once processing
  • Multi-step workflows
  • Strong transactional guarantees

In those cases, consider:

  • A workflow engine
  • A scheduler
  • Application-level coordination

The Right Mental Model​

If you remember one thing:

A queue job may run more than once, and it is only finished when acknowledged.

Design your job handlers with that assumption, and queues will behave reliably under failure.



Need Help?

Join our Discord server, post your concern & someone from our team will help you out ✌️