outbox_core/
lib.rs

1//! Transactional outbox primitives shared by every storage and transport
2//! adapter in the workspace.
3//!
4//! The crate is split into two sides:
5//!
6//! - **Producer** — [`OutboxService`](prelude::OutboxService) persists new
7//!   events into the outbox table, applying the configured
8//!   [`IdempotencyStrategy`](prelude::IdempotencyStrategy) and optionally
9//!   reserving the token through an external
10//!   [`IdempotencyStorageProvider`](prelude::IdempotencyStorageProvider).
11//! - **Worker** — [`OutboxManager`](prelude::OutboxManager), constructed via
12//!   [`OutboxManagerBuilder`](prelude::OutboxManagerBuilder), drives the
13//!   processing loop: it waits for notifications, fetches pending rows,
14//!   publishes each through a [`Transport`](prelude::Transport), and runs a
15//!   background garbage collector on the side.
16//!
17//! Storage and transport backends live in sibling crates (`outbox-postgres`,
18//! `outbox-redis`, `outbox-kafka`). This crate only defines the traits they
19//! must satisfy.
20//!
21//! # Features
22//!
23//! - `sqlx` — derives `sqlx::Type` / `sqlx::FromRow` on the domain types so
24//!   storage adapters can map rows without manual conversion.
25//! - `dlq` — enables the dead-letter-queue heap (see
26//!   [`DlqHeap`](crate::dlq::storage::DlqHeap)); the worker then tracks
27//!   per-event failure counts on every publish attempt.
28//! - `metrics` — emits `outbox.events_total` and
29//!   `outbox.publish_duration_seconds` via the `metrics` crate.
30//! - `full` — turns on `sqlx`, `dlq`, and `metrics` together.
31//!
32//! # Getting started
33//!
34//! Import the common types via the [`prelude`] module:
35//!
36//! ```ignore
37//! use outbox_core::prelude::*;
38//! ```
39
40mod builder;
41mod config;
42mod dlq;
43mod error;
44mod gc;
45mod idempotency;
46mod manager;
47mod model;
48mod object;
49mod processor;
50mod publisher;
51mod service;
52mod storage;
53
54/// Curated set of re-exports for typical integrator code.
55///
56/// Importing `outbox_core::prelude::*` brings in the types you need to build
57/// and run an outbox without having to reach into individual modules. Pulls
58/// in both the public-facing APIs (service, manager, builder, config, errors)
59/// and the traits a storage/transport adapter has to implement.
60pub mod prelude {
61    pub use crate::idempotency::storage::IdempotencyStorageProvider;
62    pub use crate::publisher::Transport;
63    pub use crate::storage::{OutboxStorage, OutboxWriter};
64
65    pub use crate::config::{IdempotencyStrategy, OutboxConfig};
66    pub use crate::manager::OutboxManager;
67    pub use crate::processor::OutboxProcessor;
68    pub use crate::service::OutboxService;
69
70    pub use crate::model::{Event, EventStatus};
71    pub use crate::object::{EventId, EventType, IdempotencyToken, Payload};
72
73    pub use crate::builder::OutboxManagerBuilder;
74    pub use crate::error::OutboxError;
75
76    #[cfg(feature = "dlq")]
77    pub use crate::dlq::model::DlqEntry;
78    #[cfg(feature = "dlq")]
79    pub use crate::dlq::storage::DlqHeap;
80}
outbox_core/lib.rs

outbox_core/
lib.rs
