azums/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![allow(clippy::double_must_use)]
3//! # Azums
4//!
5//! **High-performance job queue & streaming engine for Rust — from embedded to cloud.**
6//!
7//! `azums` delivers enterprise background job processing with ACID guarantees,
8//! row-level FOR UPDATE SKIP LOCKED leasing, dead-letter queues (DLQ), exponential backoff retries,
9//! and time-partitioned storage tables.
10//!
11//! *All backends benchmarked on every commit to main. Zero idle CPU, sub-millisecond wake-up, up to 380k jobs/sec.*
12//! See [Live Benchmark Dashboard](https://blockforge-dev.github.io/azums/).
13//!
14//! ---
15//!
16//! ## Quickstart
17//!
18//! Add `azums` to your `Cargo.toml`:
19//!
20//! ```toml
21//! [dependencies]
22//! azums = "0.2"
23//! tokio = { version = "1", features = ["full"] }
24//! serde = { version = "1", features = ["derive"] }
25//! ```
26//!
27//! Run zero-config background job processing:
28//!
29//! ```rust,no_run
30//! use azums::{quickstart, Job};
31//! use serde::Deserialize;
32//!
33//! #[derive(Deserialize)]
34//! struct GreetPayload {
35//!     name: String,
36//! }
37//!
38//! #[tokio::main]
39//! async fn main() -> anyhow::Result<()> {
40//!     let client = quickstart("memory").await?;
41//!
42//!     client.enqueue(Job::new("greet", serde_json::json!({"name": "World"}))).await?;
43//!
44//!     client.register_handler("greet", |job| async move {
45//!         let payload: GreetPayload = job.payload_typed()?;
46//!         println!("Hello, {}!", payload.name);
47//!         Ok(())
48//!     }).await;
49//!
50//!     client.run_until_empty().await?;
51//!     Ok(())
52//! }
53//! ```
54//!
55//! ---
56//!
57//! ## Storage Backend Compatibility
58//!
59//! `azums` supports four storage backends under a unified [`StorageBackend`] interface:
60//!
61//! | Backend | Connection URL | Feature Flag | Ideal Use Case |
62//! |---|---|---|---|
63//! | **PostgreSQL** | `postgres://user:pass@localhost/db` | `postgres` (default) | Multi-node Kubernetes microservices & production DBs |
64//! | **SQLite** | `sqlite://jobs.db?mode=rwc` | `sqlite` (default) | Single-binary web apps, desktop tools, IoT edge devices |
65//! | **Redis** | `redis://127.0.0.1:6379` | `redis` (default) | Ultra-low latency memory queue & native streams |
66//! | **In-Memory** | `memory` | Core | Fast unit tests, CI test pipelines, zero disk I/O |
67//!
68//! ---
69//!
70//! ## Error Handling
71//!
72//! All queue operations return [`Error`] (aliased as [`QueueError`]):
73//!
74//! - Use [`job.payload_typed::<T>()`](azums_core::Job::payload_typed) to automatically parse JSON payloads into strongly-typed structs.
75//! - Unhandled failures automatically trigger retries up to `job.max_attempts` before moving to the Dead-Letter Queue (`status = "dlq"`).
76//!
77//! ---
78//!
79//! ## Deployment
80//!
81//! - **Single-Binary Service**: Use `azums` inside your Axum, Actix, Poem, or Rocket application binary.
82//! - **Separate Worker Nodes**: Run background workers independently using the [`worker`](https://crates.io/crates/worker) crate or `azumsctl`.
83//! - **Monitoring Dashboard**: The optional web dashboard is available as a separate package (`azums-dashboard`).
84
85pub mod backend;
86pub mod config;
87pub mod db;
88pub mod jobs;
89pub mod quickstart;
90pub mod stream_handle;
91
92// ── Convenience re-exports (stable public API) ──
93
94pub use azums_core::{
95    CallRecord, ConsumerGroupStatus, Error, Event, Job, JobHandler, JobListItem, JobProcessor,
96    JobStatus, MemoryBackend, MockBackend, NewEvent, NewJob, NotificationStream, QueueConfig,
97    QueueError, QueueOrdering, StorageBackend, StreamBackend,
98};
99#[cfg(feature = "postgres")]
100pub use backend::PostgresBackend;
101#[cfg(feature = "redis")]
102pub use backend::RedisBackend;
103#[cfg(feature = "sqlite")]
104pub use backend::{make_sqlite_pool, SqliteBackend};
105pub use config::Config;
106pub use db::{make_pool, run_migrations};
107pub use jobs::attempts::AttemptsRepo;
108pub use jobs::enqueue_guard::{EnqueueGuard, EnqueueGuardConfig};
109pub use jobs::ingest_decisions::IngestDecisionsRepo;
110pub use jobs::maintenance::{MaintenanceRepo, TableMaintenanceInfo};
111pub use jobs::metrics::MetricsRepo;
112pub use jobs::policies::{PoliciesRepo, QueuePolicy};
113pub use jobs::policy_decisions::{PolicyDecisionRow, PolicyDecisionsRepo};
114pub use jobs::repo::JobsRepo;
115pub use jobs::retry::RetryConfig;
116pub use jobs::runner::JobRunner;
117pub use quickstart::{quickstart, Client, QuickstartFlow};
118pub use stream_handle::StreamHandle;
azums/lib.rs

azums/
lib.rs
