# Oxana
[](https://github.com/pragmaplatform/oxana/actions)
[](https://crates.io/crates/oxana)
[](https://docs.rs/oxana/latest)
Oxana is a Redis-backed job processing library for Rust. It powers the background job infrastructure behind [Player.gg](https://player.gg) and [Firstlook.gg](https://firstlook.gg), serving hundreds of studios and millions of players.
Oxana focuses on simplicity and depth over breadth - one backend, done well.
<p align="center">
<picture>
<img alt="Oxana Web Dashboard" src="https://raw.githubusercontent.com/pragmaplatform/oxana/refs/heads/main/web.png">
</picture>
</p>
## Key Features
- **Isolated Queues** - separate queues with independent concurrency and configuration
- **Retries** - automatic retry with configurable backoff
- **Scheduled Jobs** - run jobs at specific times or after delays
- **Cron Jobs** - periodic jobs using cron expressions
- **Dynamic Queues** - create and manage queues at runtime
- **Throttling** - rate-limit job processing per queue
- **Unique Jobs** - deduplicate jobs so only one instance runs at a time
- **Resumable Jobs** - resume from where a job left off on retry
- **Resilient Jobs** - survive worker crashes and restarts
- **Graceful Shutdown** - clean shutdown with in-progress job handling
- **Web Dashboard** - built-in UI for monitoring jobs, queues, metrics, and cron - pure Rust, no JS toolchain
- **Prometheus Metrics** - export queue and job metrics for monitoring
- **Well Tested** - comprehensive integration test suite
## Quick Start
```bash
cargo add oxana@2.0.0-rc.0
```
```rust
use oxana::Storage;
use serde::{Serialize, Deserialize};
#[derive(oxana::Registry)]
struct ComponentRegistry(oxana::ComponentRegistry<MyContext, MyError>);
#[derive(Debug, thiserror::Error)]
enum MyError {}
#[derive(Debug, Clone)]
struct MyContext {}
#[derive(Debug, Serialize, Deserialize, oxana::Job)]
struct MyJob {
data: String,
}
#[derive(oxana::Worker)]
struct MyWorker;
impl MyWorker {
async fn process(&self, job: MyJob, _ctx: &oxana::JobContext) -> Result<(), MyError> {
println!("Processing: {}", job.data);
Ok(())
}
}
#[derive(Serialize, oxana::Queue)]
#[oxana(key = "my_queue", concurrency = 2)]
struct MyQueue;
#[tokio::main]
async fn main() -> Result<(), oxana::OxanaError> {
let ctx = oxana::ContextValue::new(MyContext {});
let storage = Storage::builder().build_from_env()?;
let config = ComponentRegistry::build_config(&storage)
.with_graceful_shutdown(tokio::signal::ctrl_c());
storage.enqueue(MyQueue, MyJob { data: "hello".into() }).await?;
oxana::run(config, ctx).await?;
Ok(())
}
```
For more detailed usage examples, check out the [examples directory](https://github.com/pragmaplatform/oxana/tree/main/oxana/examples).
## Web Dashboard
The `oxana-web` crate provides a built-in dashboard for monitoring jobs, queues, worker metrics, and cron schedules. It integrates as a nested axum router.
```rust
use oxana_web::OxanaWebState;
let config = ComponentRegistry::build_config(&storage)
.with_graceful_shutdown(tokio::signal::ctrl_c());
let oxana_router = oxana_web::router(OxanaWebState::new(
config.storage.clone(),
config.catalog(),
"/oxana".to_string(),
));
let app = your_app_router().nest("/oxana", oxana_router);
```
The dashboard exposes these pages:
- `/` - Overview with job stats
- `/busy` - Currently processing jobs
- `/queues` - All queues with stats
- `/queues/{queue_key}` - Jobs in a specific queue
- `/jobs/{job_id}` - Details for a specific job
- `/metrics` - Worker execution metrics
- `/metrics/job?worker=...` - Metrics for a specific worker
- `/cron` - Cron job schedules
- `/on-demand` - Manually enqueue registered on-demand jobs
- `/scheduled` - Scheduled jobs
- `/retries` - Jobs pending retry
- `/dead` - Dead letter queue
It also provides management actions for wiping queues and deleting individual jobs.
## Core Concepts
### Jobs and Workers
Jobs carry the data that gets enqueued and define enqueue-time metadata. Workers define the processing logic for jobs. Use the `#[derive(oxana::Job)]` and `#[derive(oxana::Worker)]` macros or implement the traits manually.
| `Job` attributes (enqueue-time) | `Worker` attributes (execution-time) |
| --- | --- |
| `#[oxana(worker = MyWorker)]` - override inferred `FooJob` -> `FooWorker` binding | `#[oxana(job = MyJob)]` - override inferred `FooWorker` -> `FooJob` binding |
| `#[oxana(unique_id = "worker_{id}")]` - define unique job identifiers | `#[oxana(context = MyContext)]` - set worker context type |
| `#[oxana(on_conflict = Skip)]` - handle unique job conflicts (Skip or Replace) | `#[oxana(error = MyError)]` - set worker error type |
| `#[oxana(resurrect = false)]` - disable crash resurrection for this job type | `#[oxana(registry = MyRegistry)]` - choose component registry |
| `#[oxana(throttle_cost = 2)]` - set per-job throttle cost | `#[oxana(max_retries = 3)]` - set maximum retry attempts |
| `#[oxana(on_demand)]` - expose the job in the web dashboard for manual enqueueing | `#[oxana(retry_delay = 5)]` - set retry delay in seconds |
| | `#[oxana(cron(schedule = "*/5 * * * * *", queue = MyQueue))]` - schedule periodic jobs |
| | `#[oxana(batch_size = 100, batch_timeout_ms = 500)]` - process jobs in batches |
For job hooks, `Self::...` resolves to the job type. For worker hooks, `Self::...` resolves to the worker type.
On-demand argument templates infer editable placeholders from field types. Numeric primitives and common numeric ID newtypes named `*Id` or `*ID` are prefilled with `0`.
Batch workers use all-or-nothing result semantics: if `process_batch` returns `Ok(())`, every job in the batch is marked successful; if it returns an error or panics, every job in that batch follows the normal retry or failure path. Batch handlers should therefore be idempotent, or should only commit external side effects after the whole batch is ready to succeed.
### Queues
Queues are the channels through which jobs flow. Use the `#[derive(oxana::Queue)]` macro or implement the `Queue` trait manually.
Queues can be:
- **Static**: Defined at compile time with a fixed key
- **Dynamic**: Created at runtime with each instance being a separate queue (requires struct fields)
Queue attributes:
- `#[oxana(key = "my_queue")]` - Set static queue key
- `#[oxana(prefix = "dynamic")]` - Set prefix for dynamic queues
- `#[oxana(concurrency = 2)]` - Set concurrency limit
- `#[oxana(throttle(window_ms = 2000, limit = 5))]` - Configure throttling
### Component Registry
The component registry automatically discovers and registers all workers and queues in your application. Use `#[derive(oxana::Registry)]` to create a registry and `ComponentRegistry::build_config()` to build the configuration.
### Storage
`Storage` provides the interface for job persistence - enqueueing, scheduling, state management, and queue monitoring.
Build it with `Storage::builder().build_from_env()` which reads the `REDIS_URL` environment variable.
Set `REDIS_STATS_URL` to store counters and metrics in a separate Redis instance; when it is not set, stats use `REDIS_URL`.
### Context
The context provides shared state and utilities to workers. It can include:
- Database connections
- Configuration
- Shared resources
- Job state (for resumable jobs)
### Configuration
Configuration is done through the `Config` builder, which allows you to:
- Automatically register queues and workers via the component registry
- Set up graceful shutdown
- Configure exit conditions
### Error Handling
Oxana uses a custom `OxanaError` type that covers all library error cases. Workers can define their own error type that implements `std::error::Error`.
### Prometheus Metrics
Enable the `prometheus` feature to expose metrics:
```rust
let metrics = storage.metrics().await?;
let output = metrics.encode_to_string()?;
// Serve `output` on your metrics endpoint
```
## Comparison with Similar Libraries
| Feature | Oxana | [Apalis](https://crates.io/crates/apalis) | [rusty-sidekiq](https://crates.io/crates/rusty-sidekiq) | [Fang](https://crates.io/crates/fang) |
|---|---|---|---|---|
| Backend | Redis | Redis, Postgres, `SQLite`, `MySQL`, AMQP, NATS | Redis | Postgres, `SQLite`, `MySQL` |
| Retries | Yes | Yes (tower layer) | Yes | Yes |
| Scheduled Jobs | Yes | Yes | Yes | Yes |
| Cron | Yes | Yes | Yes | Yes |
| Unique Jobs | Yes | No | Yes | Yes |
| Throttling | Yes | No | No | No |
| Dynamic Queues | Yes | No | No | No |
| Resumable Jobs | Yes | No | No | No |
| Graceful Shutdown | Yes | Yes | Partial | No |
| Web UI | Yes | Yes (apalis-board) | No (uses Ruby Sidekiq UI) | No |
| License | MIT | MIT | MIT | MIT |
**Oxana** focuses on depth with a single Redis backend rather than breadth across multiple backends. It is the only Rust job library offering resumable jobs and combines unique jobs, throttling, and a built-in web dashboard in one package.
**Apalis** offers the most backend options and integrates with the tower middleware ecosystem, making it highly extensible. It suits projects that need backend flexibility or already use tower layers. However, its breadth of abstraction can come at the cost of reliability and debuggability in production.
**rusty-sidekiq** is wire-compatible with Ruby Sidekiq, making it ideal for teams migrating from or coexisting with Ruby services. It can share queues with Ruby Sidekiq workers and use the existing Sidekiq web UI.
**Fang** is SQL-database-backed (no Redis dependency) with both async and threaded execution modes. A good fit for projects that prefer Postgres/SQLite over Redis.