Rate Limiting & Concurrency Control for Bun Job Queues

guide · rate limiting

Rate limits and concurrency, under control.

Cap jobs per time window or concurrent active jobs per queue to protect downstream services. Works from the CLI, over TCP, and in embedded mode.

Rate Limit

Limit jobs per second (token bucket, refilled continuously):

# CLI
bunqueue rate-limit set emails 100  # 100 jobs/second
bunqueue rate-limit clear emails

The server-side rate limit window is fixed at 1 second. No rate limit is set by default (unlimited).

Concurrency Limit

Limit concurrent active jobs:

# CLI
bunqueue concurrency set emails 5  # Max 5 concurrent
bunqueue concurrency clear emails

Embedded Mode

In embedded mode you can call queue.setGlobalRateLimit(max) / queue.setGlobalConcurrency(n) directly, use a per-worker limiter, or control throughput with worker concurrency:

const queue = new Queue('emails', { embedded: true });

// Control processing rate with worker concurrency
const worker = new Worker('emails', processor, {
  embedded: true,
  concurrency: 5, // Max 5 parallel jobs
});

For custom time-based rate limiting beyond the built-in options, you can also implement it in your processor:

import { Ratelimit } from '@upstash/ratelimit'; // or similar

const ratelimit = new Ratelimit({ ... });

const worker = new Worker('emails', async (job) => {
  await ratelimit.limit('email-send'); // External rate limiter
  await sendEmail(job.data);
}, { embedded: true });