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( &self, event_type: &str, payload: P, provided_token: Option<String>, executor: W::Executor<'_>, ) -> Result<(), OutboxError>

where 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(callback) — passes the event about to be written to the callback and uses the returned String as the token.
• 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.

Transactional usage

The executor argument is forwarded to the configured OutboxWriter — for sqlx-based backends this is typically &mut *tx borrowed from a held sqlx::Transaction. Threading the transaction through the call is what makes the outbox write atomic with the caller’s business write: both rows commit or roll back together.

Example

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

service.add_event("order.created", payload, None, &mut *tx).await?;