Concepts

Core concepts in BullRun and how they map to BullMQ primitives.

Tasks

A task is a named function that processes a payload. Tasks are defined with defineTask() and registered automatically when imported. Each task maps to a BullMQ job name.

Queues

Queues group related tasks and control concurrency. Each queue runs on an isolated Redis namespace. Tasks specify which queue they belong to (default: "default").

Projects

A project is an isolated environment with its own queues, API keys, and Redis instance. You can create separate projects for different apps or teams.

Environments

Each project supports dev, staging, and production environments. API keys are scoped to an environment, and each gets isolated Redis storage.

Schedules

Cron-based recurring tasks. Define a schedule with a cron expression and timezone, and BullRun triggers the task automatically.

Alerts

Rules that fire when conditions are met: high failure rates, deep queues, slow jobs, or stalled workers. Alerts dispatch to Slack, webhooks, or email.

Workers

Workers are processes that execute task handlers. They connect to Redis, listen on queues, and process jobs. Workers report their status (online/offline, memory, uptime) to the BullRun dashboard. You can run multiple workers for horizontal scaling.

Middleware

Reusable functions that wrap task handlers. Built-in middleware includes logging, timeouts, and retry logic. You can create custom middleware for auth, validation, or telemetry.

Job Lifecycle

Jobs go through states: waiting → active → completed/failed. Delayed jobs wait in the delayed state until their delay expires. Stalled jobs are detected when a worker crashes mid-execution. Failed jobs can be retried according to the task's retry policy.

Task Registry

When a worker starts, it imports task files and registers them. The registry maps task names to handler functions. The dashboard's Task Registry page shows all registered tasks across all connected workers.