asyncq
Type-safe background jobs for Rust. Define once with #[derive(Job)], run anywhere.
[]
= "0.1"
= "0.1" # or asyncq-postgres
= { = "1", = ["derive"] }
Why asyncq?
Most Rust job queues copy the Tower/Service pattern — you write boilerplate for every job type. asyncq takes a different approach: derive macros with compile-time validation.
// asyncq — define your job, implement perform, done
Compare to apalis (Tower-based):
// apalis — define job, define service, define layer, wire builder
async
new
.layer
.layer
.source
.build_fn
asyncq moves configuration to the type level — retries, timeouts, and queue names are part of the job definition, not runtime wiring. Typos become compile errors.
Quick start
use ;
use RedisBackend;
use ;
async
Features
State injection
Pass app state once at startup. Access via ctx.state::<T>() — same pattern as axum.
let pool = new;
let queue = new.with_state;
Scheduling
queue.enqueue.await?; // now
queue.enqueue_in.await?; // 1 hour
queue.enqueue_at.await?; // tomorrow
Cron scheduling
Run jobs on a recurring schedule:
use Scheduler;
;
let scheduler = new
. // every day at 9am
.; // every Sunday at midnight
// Run alongside your worker
select!
Cron format: second minute hour day-of-month month day-of-week
Error handling
Backoff is exponential: 30s × 2^attempt, capped at 1 hour.
Job attributes
Worker options
new
.
.
.concurrency // concurrent jobs
.queues // priority order
.stuck_timeout // requeue stuck jobs
.run
.await;
Graceful shutdown
worker.run_graceful.await;
Dead-letter queue
let dead = queue.dead_jobs.await?;
queue.retry_dead.await?; // retry one
queue.retry_all_dead.await?; // retry all
Queue stats
let stats = queue.stats.await?;
println!;
Backends
| Crate | Use case |
|---|---|
asyncq-redis |
Production Redis backend |
asyncq-postgres |
PostgreSQL with transactional outbox |
asyncq-axum |
Admin REST API + Prometheus metrics |
PostgreSQL + transactional outbox
Enqueue jobs in the same transaction as your business logic — if the transaction rolls back, so does the job.
use PostgresBackend;
let backend = new.await?;
backend.migrate.await?; // creates asyncq_jobs table
let mut tx = pool.begin.await?;
query.execute.await?;
backend.enqueue_in_tx.await?;
tx.commit.await?; // job visible only after commit
Admin API (asyncq-axum)
use admin;
let app = new.nest;
| Endpoint | Description |
|---|---|
GET /queues/:name |
Stats |
GET /queues/:name/dlq |
Dead jobs (paginated) |
POST /queues/:name/dlq/retry-all |
Retry all dead |
DELETE /queues/:name/dlq/:id |
Retry one |
GET /metrics |
Prometheus format |
Testing
Use InMemoryBackend — no Redis required:
async
run_once() processes all pending jobs and returns — no Ctrl-C needed.
Roadmap
- Cron scheduling —
Scheduler::register::<Job>("0 0 9 * * *") - Unique jobs — deduplicate by payload hash
- Middleware — before/after hooks
- Rate limiting — per-queue throttling
- Job chains —
JobA.then(JobB).then(JobC)
License
MIT OR Apache-2.0