Struct PgOutboxWorkerBuilder 

pub struct PgOutboxWorkerBuilder { /* private fields */ }

Fluent builder for an OutboxWorker backed by PgOutboxStore.

Pool sizing and acquire timeout

The worker and every concurrent publisher draw connections from the same pool. To avoid indefinite blocking under pressure, configure an acquire timeout on the PgPool before passing it here:

use sqlx::postgres::PgPoolOptions;
use std::time::Duration;

let pool = PgPoolOptions::new()
    // 1 connection for the claim cycle + 1 per concurrent publisher + 2 headroom
    .max_connections(batch_size + num_publishers + 2)
    // surface PoolTimeout instead of blocking indefinitely
    .acquire_timeout(Duration::from_secs(5))
    .connect("postgres://...")
    .await?;

let worker = PgOutboxWorkerBuilder::new(pool)
    .batch_size(batch_size)
    .build()?;

When acquire_timeout expires, OutboxStore::acquire returns OutboxError::PoolTimeout instead of hanging. The worker logs the error and retries after OutboxWorkerConfig::poll_interval.

Implementations

impl PgOutboxWorkerBuilder

pub fn new(pool: PgPool) -> Self

Start a new builder for the given pool.

pub fn table_name(self, name: impl Into<String>) -> Self

Override the outbox table name (default "audit_outbox").

pub fn dead_letter_table(self, name: impl Into<String>) -> Self

Enable dead-letter persistence for poison messages.

Envelopes that exhaust their retry budget are atomically moved to dlq_table (INSERT + DELETE in the same transaction). When not set, exhausted envelopes are logged via tracing::error! but not moved.

pub fn register_handler<E, H>(self, handler: H) -> Self

where E: Event, H: Handler<E>,

Register a typed handler for the event type E.

Registering twice for the same event type silently replaces the previous handler.

pub fn shared_handler<E, H>(self, handler: Arc<H>) -> Self

where E: Event, H: Handler<E>,

Register a handler already shared behind an Arc.

pub fn poll_interval(self, d: Duration) -> Self

Override the poll interval (default 100 ms).

pub fn batch_size(self, n: usize) -> Self

Override the batch size per poll (default 10).

pub fn max_attempts(self, n: u32) -> Self

Override the maximum number of attempts per envelope (default 5).

pub fn retry_base_delay(self, d: Duration) -> Self

Override the base delay for exponential backoff (default 1 s).

The actual delay before attempt n is min(retry_max_delay, base × 2^n), optionally jittered. See OutboxWorkerConfig::retry_base_delay.

pub fn retry_max_delay(self, d: Duration) -> Self

Override the maximum backoff delay (default 5 min).

Caps retry_base_delay × 2^n regardless of the attempt count.

pub fn jitter(self, enabled: bool) -> Self

Enable or disable full jitter on the backoff delay (default true).

When true the worker draws a uniform random value in [0, computed_delay] instead of using the deterministic exponential.

pub fn dispatch_timeout(self, d: Duration) -> Self

Override the per-envelope handler deadline and soft-lease unit (default 30 s).

Each handler invocation is wrapped in a hard tokio timeout of this duration; the batch lease is sized as batch_size x dispatch_timeout internally. Set it to the worst-case duration of a single handler.

pub fn build(self) -> Result<OutboxWorker<PgOutboxStore>, OutboxError>

Consume the builder and produce an OutboxWorker ready to spawn.

Errors

Returns OutboxError::Internal if the configured table_name is not a valid identifier.