Struct OutboxService 

pub struct OutboxService<W, S, P>
where
    P: Debug + Clone + Serialize + Send + Sync,
{ /* private fields */ }

Producer-side facade for writing outbox events.

The service is generic over:

• W — OutboxWriter implementation (persists the event row)
• S — IdempotencyStorageProvider implementation used to reserve tokens; set to [NoIdempotency] when no external reservation is needed
• P — the user’s domain event payload type (Debug + Clone + Serialize)

Construct with new when events should be written without an external idempotency check, or with with_idempotency to wire a reservation backend.

Implementations

impl<W, P> OutboxService<W, NoIdempotency, P>

where W: OutboxWriter<P> + Send + Sync + 'static, P: Debug + Clone + Serialize + Send + Sync,

pub fn new(writer: Arc<W>, config: Arc<OutboxConfig<P>>) -> Self

Creates a service without any external idempotency reservation.

Tokens are still produced according to config.idempotency_strategy and written alongside the event, so downstream consumers can deduplicate on their side, but no pre-insert uniqueness check is performed here. Use with_idempotency to attach a reservation store (for example Redis) when at-producer deduplication is required.

impl<W, S, P> OutboxService<W, S, P>

where W: OutboxWriter<P> + Send + Sync + 'static, S: IdempotencyStorageProvider + Send + Sync + 'static, P: Debug + Clone + Serialize + Send + Sync,

pub fn with_idempotency( writer: Arc<W>, config: Arc<OutboxConfig<P>>, idempotency_storage: Arc<S>, ) -> Self

Creates a service wired to an external idempotency reservation store.

Before inserting the event, the service calls IdempotencyStorageProvider::try_reserve with the token produced by the configured strategy. If the reservation returns false, the insert is skipped and OutboxError::DuplicateEvent is propagated to the caller.

pub async fn add_event<F>( &self, event_type: &str, payload: P, provided_token: Option<String>, get_event: F, ) -> Result<(), OutboxError>

where F: FnOnce() -> Option<Event<P>>, P: Debug + Clone + Serialize + Send + Sync,

Adds a new event to the outbox storage with idempotency checks.

The token is derived from IdempotencyStrategy on the configured OutboxConfig:

• Provided — uses provided_token as-is (None skips reservation).
• Uuid — generates a fresh UUID v7; provided_token is ignored.
• Custom(fn) — calls get_event and passes the resulting Event to the closure. The get_event callback is only invoked by this branch, so for other strategies callers can safely pass || None.
• None — no token is produced and reservation is skipped.

If an idempotency provider is configured and a token was produced, it will first attempt to reserve the token to prevent duplicate processing.

Errors

Returns OutboxError::DuplicateEvent if the event token has already been used. Returns any OutboxError variant propagated from the reservation call or from the writer’s insert_event.

Panics

Panics if the idempotency strategy is set to Custom, but get_event returns None.

Example

use std::sync::Arc;
use outbox_core::prelude::*;

// Uuid / None strategies — no event context needed.
service.add_event("order.created", payload, None, || None).await?;