Struct Outbox 

pub struct Outbox { /* private fields */ }

An event outbox.

Events are appended and assigned monotonically increasing sequence numbers. The outbox can be drained (consumed) in order for push operations, or peeked without consuming.

By default this is in-memory, but it can be backed by a durable JSON snapshot via Outbox::with_persistence.

Examples

use stateset_sync::{Outbox, SyncEvent};
use serde_json::json;

let mut outbox = Outbox::new(100);
let seq = outbox.append(SyncEvent::new("order.created", "order", "ORD-1", json!({}))).unwrap();
assert_eq!(seq, 1);
assert_eq!(outbox.count(), 1);

Implementations

impl Outbox

pub const fn new(max_capacity: usize) -> Self

Create a new in-memory Outbox with the given maximum capacity.

pub const fn with_default_capacity() -> Self

Create a new Outbox with the default maximum capacity (10,000).

pub fn with_persistence( max_capacity: usize, path: impl AsRef<Path>, ) -> Result<Self, SyncError>

Create a durable outbox persisted to path.

If the snapshot already exists, it is loaded and reused.

Errors

Returns SyncError::Storage if snapshot I/O fails.

pub fn append(&mut self, event: SyncEvent) -> Result<u64, SyncError>

Append an event to the outbox, assigning it the next sequence number.

Returns the assigned sequence number.

Errors

Returns SyncError::OutboxFull if the outbox is at capacity or SyncError::Storage if durable persistence fails.

pub fn drain(&mut self, count: usize) -> Result<Vec<SyncEvent>, SyncError>

Drain up to count events from the front of the outbox (FIFO order).

Drained events are removed from the outbox.

Errors

Returns SyncError::Storage if durable persistence cannot be updated. In that case, the original in-memory ordering is restored.

pub fn peek(&self, count: usize) -> Vec<&SyncEvent>

Peek at up to count events from the front of the outbox without consuming them.

pub fn retain<F>(&mut self, predicate: F)

where F: FnMut(&SyncEvent) -> bool,

Retain only events matching the given predicate.

Preserves FIFO order and does not modify sequence allocation.

pub fn try_retain<F>(&mut self, predicate: F) -> Result<(), SyncError>

where F: FnMut(&SyncEvent) -> bool,

Retain only events matching the given predicate and persist the result.

Errors

Returns SyncError::Storage if durable persistence fails. In that case, the original in-memory ordering is restored.

pub fn count(&self) -> usize

Return the number of events currently in the outbox.

pub fn is_empty(&self) -> bool

Whether the outbox is empty.

pub fn is_full(&self) -> bool

Whether the outbox is at maximum capacity.

pub fn clear(&mut self)

Remove all events from the outbox.

pub const fn max_capacity(&self) -> usize

Return the maximum capacity of the outbox.

pub const fn next_sequence(&self) -> u64

Return the next sequence number that will be assigned.

Trait Implementations

impl Debug for Outbox

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Outbox

fn default() -> Self

Returns the “default value” for a type.