Crate outbox_core 

Transactional outbox primitives shared by every storage and transport adapter in the workspace.

The crate is split into two sides:

• Producer — OutboxService persists new events into the outbox table, applying the configured IdempotencyStrategy and optionally reserving the token through an external IdempotencyStorageProvider.
• Worker — OutboxManager, constructed via OutboxManagerBuilder, drives the processing loop: it waits for notifications, fetches pending rows, publishes each through a Transport, and runs a background garbage collector on the side.

Storage and transport backends live in sibling crates (outbox-postgres, outbox-redis, outbox-kafka). This crate only defines the traits they must satisfy.

Features

• sqlx — derives sqlx::Type / sqlx::FromRow on the domain types so storage adapters can map rows without manual conversion.
• dlq — enables the dead-letter-queue heap (see DlqHeap); the worker then tracks per-event failure counts on every publish attempt.
• metrics — emits outbox.events_total and outbox.publish_duration_seconds via the metrics crate.
• full — turns on sqlx, dlq, and metrics together.

Getting started

Import the common types via the prelude module:

use outbox_core::prelude::*;

Modules

prelude

Curated set of re-exports for typical integrator code.

Structs

DlqEntry

One entry tracked by [DlqHeap]: an event id together with its current aggregated failure count.

Event

A single outbox row representing one domain event to be published.

EventId

Primary key of an outbox row.

EventType

Domain-level event name used by transports for routing (Kafka topic suffix, Redis stream key, etc).

IdempotencyToken

Deduplication token attached to an Event.

NoIdempotency

No-op IdempotencyStorageProvider that accepts every token.

OutboxConfig

Runtime configuration shared by the producer and worker sides.

OutboxManager

Long-running worker that publishes pending outbox events to the broker.

OutboxManagerBuilder

Fluent builder that assembles an OutboxManager.

OutboxService

Producer-side facade for writing outbox events.

Payload

Typed wrapper around the user’s domain event value.

Enums

EventStatus

Lifecycle stage of an outbox Event.

IdempotencyStrategy

How an idempotency token is produced when a new event is written.

OutboxError

Error categories produced by the outbox crate.

Traits

DlqHeap

Tracks per-event publish failure counts for the dead-letter queue.

IdempotencyStorageProvider

Async contract for reserving an idempotency token before an event is written.

OutboxStorage

Worker-side storage contract.

OutboxWriter

Producer-side storage contract.

Transport

Publishes a single Event to an external system.

Type Aliases

IdempotencyDeriver

Shared callback used by IdempotencyStrategy::Custom to derive an idempotency token from the event about to be written.