azums/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg, rustdoc_missing_doc_code_examples))]
2#![cfg_attr(docsrs, deny(rustdoc::missing_doc_code_examples))]
3#![allow(clippy::double_must_use)]
4#![deny(missing_docs)]
5//! # Azums
6//!
7//! **The durable execution layer for Rust.**
8//!
9//! `azums` turns ordinary async Rust handlers into recoverable, retryable, observable at-least-once
10//! execution across Memory, SQLite, PostgreSQL, and Redis. It manages persistence, scheduling,
11//! leases, heartbeats, attempts, retries, dead-letter handling, replay, and durable event streams
12//! without requiring a separate message broker.
13//!
14//! *Performance claims are benchmark-derived and reproducible through `azums-perf` and Criterion.*
15//! See [Live Benchmark Dashboard](https://blockforge-dev.github.io/azums/) for current measured results and conditions.
16//!
17//! ---
18//!
19//! ## Quickstart
20//!
21//! Add `azums` to your `Cargo.toml`:
22//!
23//! ```toml
24//! [dependencies]
25//! azums = "1.0"
26//! tokio = { version = "1", features = ["full"] }
27//! serde = { version = "1", features = ["derive"] }
28//! ```
29//!
30//! Run zero-config background job processing:
31//!
32//! ```rust,no_run
33//! use azums::{quickstart, Job};
34//! use serde::Deserialize;
35//!
36//! #[derive(Deserialize)]
37//! struct GreetPayload {
38//!     name: String,
39//! }
40//!
41//! #[tokio::main]
42//! async fn main() -> anyhow::Result<()> {
43//!     let client = quickstart("memory").await?;
44//!
45//!     client.enqueue(Job::new("greet", serde_json::json!({"name": "World"}))).await?;
46//!
47//!     client.register_handler("greet", |job| async move {
48//!         let payload: GreetPayload = job.payload_typed()?;
49//!         println!("Hello, {}!", payload.name);
50//!         Ok(())
51//!     }).await;
52//!
53//!     client.run_until_empty().await?;
54//!     Ok(())
55//! }
56//! ```
57//!
58//! ---
59//!
60//! ## Storage Backend Compatibility
61//!
62//! `azums` supports four storage backends under a unified [`StorageBackend`] interface:
63//!
64//! | Backend | Connection URL | Feature Flag | Ideal Use Case |
65//! |---|---|---|---|
66//! | **PostgreSQL** | `postgres://user:pass@localhost/db` | `postgres` (default) | Multi-node Kubernetes microservices & production DBs |
67//! | **SQLite** | `sqlite://jobs.db?mode=rwc` | `sqlite` (default) | Single-binary web apps, desktop tools, IoT edge devices |
68//! | **Redis** | `redis://127.0.0.1:6379` | `redis` (default) | Ultra-low latency memory queue & native streams |
69//! | **In-Memory** | `memory` | Core | Fast unit tests, CI test pipelines, zero disk I/O |
70//!
71//! ---
72//!
73//! ## Error Handling
74//!
75//! All queue operations return [`Error`] (aliased as [`QueueError`]):
76//!
77//! - Use [`job.payload_typed::<T>()`](azums_core::Job::payload_typed) to automatically parse JSON payloads into strongly-typed structs.
78//! - Unhandled failures automatically trigger retries up to `job.max_attempts` before moving to the Dead-Letter Queue (`status = "dlq"`).
79//!
80//! ---
81//!
82//! ## Deployment
83//!
84//! - **Single-Binary Service**: Use `azums` inside your Axum, Actix, Poem, or Rocket application binary.
85//! - **Separate Worker Nodes**: Run background workers independently using the [`worker`](https://crates.io/crates/worker) crate or `azumsctl`.
86//! - **Monitoring Dashboard**: The optional web dashboard is available as a separate package (`azums-dashboard`).
87
88/// Storage backend adapters and backend-specific constructors.
89pub mod backend;
90/// Environment-driven runtime configuration.
91pub mod config;
92/// PostgreSQL pool and migration helpers.
93pub mod db;
94/// Job repositories, execution policies, attempts, and operational views.
95pub mod jobs;
96/// High-level client, handler registry, and Tokio worker runtime.
97pub mod quickstart;
98/// High-level durable event stream handle.
99pub mod stream_handle;
100
101// Convenience re-exports forming the stable public API.
102
103pub use azums_core::{
104    semantic_contract, BackendCapabilities, BackendSemanticCapabilities, BackpressureCapability,
105    CallRecord, ConsumerGroupCapability, ConsumerGroupStatus, DurabilityCapability, Error, Event,
106    Job, JobExecution, JobHandler, JobLifecycleState, JobListItem, JobProcessor, JobStatus,
107    MemoryBackend, MockBackend, NewEvent, NewJob, NotificationCapability, NotificationStream,
108    OrderingCapability, Queue, QueueConfig, QueueError, QueueOrdering, RetentionCapability,
109    SemanticBehavior, SemanticClassification, SemanticContract, StorageBackend, StreamBackend,
110    TransactionalEnqueueCapability, Worker,
111};
112#[cfg(feature = "postgres")]
113pub use backend::PostgresBackend;
114#[cfg(feature = "redis")]
115pub use backend::RedisBackend;
116#[cfg(feature = "sqlite")]
117pub use backend::{make_sqlite_pool, SqliteBackend};
118pub use config::Config;
119pub use db::{make_pool, run_migrations};
120pub use jobs::attempts::{AttemptsRepo, JobAttempt};
121pub use jobs::enqueue_guard::{EnqueueGuard, EnqueueGuardConfig};
122pub use jobs::ingest_decisions::IngestDecisionsRepo;
123pub use jobs::maintenance::{MaintenanceRepo, TableMaintenanceInfo};
124pub use jobs::metrics::MetricsRepo;
125pub use jobs::policies::{PoliciesRepo, QueuePolicy};
126pub use jobs::policy_decisions::{PolicyDecisionRow, PolicyDecisionsRepo};
127pub use jobs::repo::JobsRepo;
128pub use jobs::retry::RetryConfig;
129pub use jobs::runner::JobRunner;
130pub use quickstart::{quickstart, Client, QuickstartFlow};
131pub use stream_handle::StreamHandle;
azums/lib.rs

azums/
lib.rs
