Crate azums 

Azums

The durable execution layer for Rust.

azums turns ordinary async Rust handlers into recoverable, retryable, observable at-least-once execution across Memory, SQLite, PostgreSQL, and Redis. It manages persistence, scheduling, leases, heartbeats, attempts, retries, dead-letter handling, replay, and durable event streams without requiring a separate message broker.

Performance claims are benchmark-derived and reproducible through azums-perf and Criterion. See Live Benchmark Dashboard for current measured results and conditions.

---

Quickstart

Add azums to your Cargo.toml:

[dependencies]
azums = "1.0"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }

Run zero-config background job processing:

use azums::{quickstart, Job};
use serde::Deserialize;

#[derive(Deserialize)]
struct GreetPayload {
    name: String,
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = quickstart("memory").await?;

    client.enqueue(Job::new("greet", serde_json::json!({"name": "World"}))).await?;

    client.register_handler("greet", |job| async move {
        let payload: GreetPayload = job.payload_typed()?;
        println!("Hello, {}!", payload.name);
        Ok(())
    }).await;

    client.run_until_empty().await?;
    Ok(())
}

---

Storage Backend Compatibility

azums supports four storage backends under a unified StorageBackend interface:

Backend	Connection URL	Feature Flag	Ideal Use Case
PostgreSQL	postgres://user:pass@localhost/db	postgres (default)	Multi-node Kubernetes microservices & production DBs
SQLite	sqlite://jobs.db?mode=rwc	sqlite (default)	Single-binary web apps, desktop tools, IoT edge devices
Redis	redis://127.0.0.1:6379	redis (default)	Ultra-low latency memory queue & native streams
In-Memory	memory	Core	Fast unit tests, CI test pipelines, zero disk I/O

---

Error Handling

All queue operations return Error (aliased as QueueError):

• Use job.payload_typed::<T>() to automatically parse JSON payloads into strongly-typed structs.
• Unhandled failures automatically trigger retries up to job.max_attempts before moving to the Dead-Letter Queue (status = "dlq").

---

Deployment

• Single-Binary Service: Use azums inside your Axum, Actix, Poem, or Rocket application binary.
• Separate Worker Nodes: Run background workers independently using the worker crate or azumsctl.
• Monitoring Dashboard: The optional web dashboard is available as a separate package (azums-dashboard).

Re-exports

pub use backend::PostgresBackend;postgres

pub use backend::make_sqlite_pool;sqlite

pub use backend::SqliteBackend;sqlite

pub use config::Config;

pub use db::make_pool;

pub use db::run_migrations;

pub use jobs::attempts::AttemptsRepo;

pub use jobs::attempts::JobAttempt;

pub use jobs::enqueue_guard::EnqueueGuard;

pub use jobs::enqueue_guard::EnqueueGuardConfig;

pub use jobs::ingest_decisions::IngestDecisionsRepo;

pub use jobs::maintenance::MaintenanceRepo;

pub use jobs::maintenance::TableMaintenanceInfo;

pub use jobs::metrics::MetricsRepo;

pub use jobs::policies::PoliciesRepo;

pub use jobs::policies::QueuePolicy;

pub use jobs::policy_decisions::PolicyDecisionRow;

pub use jobs::policy_decisions::PolicyDecisionsRepo;

pub use jobs::repo::JobsRepo;

pub use jobs::retry::RetryConfig;

pub use jobs::runner::JobRunner;

pub use quickstart::quickstart;

pub use quickstart::Client;

pub use quickstart::QuickstartFlow;

pub use stream_handle::StreamHandle;

Modules

backend

Storage backend adapters and backend-specific constructors.

config

Environment-driven runtime configuration.

db

PostgreSQL pool and migration helpers.

jobs

Job repositories, execution policies, attempts, and operational views. Job queue core: models, repository, retry logic, and execution runner.

quickstart

High-level client, handler registry, and Tokio worker runtime.

stream_handle

High-level durable event stream handle.

Structs

BackendCapabilities

Storage backend feature and guarantee declaration.

BackendSemanticCapabilities

Detailed semantic strength behind the compatibility-preserving feature flags.

ConsumerGroupStatus

Status and offset information for a consumer group registered on a stream log.

Event

Represents an immutable event stored within a durable stream log.

Job

Primary job entity representing a unit of work stored in a storage backend.

JobExecution

Runtime execution claim tying a job, durable attempt, worker, and lease together.

JobListItem

Lightweight job summary model returned when listing jobs in Admin UI or APIs.

MemoryBackend

Thread-safe in-memory implementation of StorageBackend.

MockBackend

Recording mock storage backend wrapper for assertion-driven integration testing.

NewEvent

Input model for publishing a new event into a stream log.

NewJob

Specification for enqueueing a new job into a storage backend.

Queue

Named queue definition plus its execution policy.

QueueConfig

Configuration options for a job queue.

RedisBackendredis

Production-grade Redis implementation of StorageBackend and StreamBackend.

SemanticContract

Machine-readable answer to “what does Azums guarantee for this behavior?”.

Worker

Worker identity used for leases, attempts, and execution ownership.

Enums

BackpressureCapability

Backpressure behavior exposed by a storage backend.

CallRecord

Log record representing a single call executed against a MockBackend.

ConsumerGroupCapability

Coordination provided for consumers sharing one consumer-group name.

DurabilityCapability

Persistence strength provided by a backend.

Error

Primary error enum for azums job queue operations.

JobLifecycleState

Canonical logical job lifecycle state.

JobStatus

Stored job status values.

NotificationCapability

Delivery behavior of backend wake-up notifications.

OrderingCapability

Ordering strength exposed by a storage backend.

QueueOrdering

Per-queue job execution ordering policy.

RetentionCapability

Retention behavior exposed by a backend.

SemanticBehavior

A public Azums behavior whose contract is stable and explicitly classified.

SemanticClassification

Stability class of a documented Azums behavior.

TransactionalEnqueueCapability

Transaction boundary in which enqueue can be atomic with application state.

Traits

JobProcessor

Trait-based job processor interface for structured background workers.

StorageBackend

Async, backend-agnostic storage interface for job queue operations.

StreamBackend

Interface for append-only, replayable event streams with consumer groups and acknowledgments.

Functions

semantic_contract

Returns the canonical product contract for every public semantic behavior.

Type Aliases

JobHandler

Asynchronous job handler closure type alias.

NotificationStream

Type alias for asynchronous notification event streams produced by StorageBackend::subscribe.

QueueError

Type alias for backward compatibility.