Struct Spool 

pub struct Spool { /* private fields */ }

Append-only durable spool file.

The byte cap and the running total are raw MaxSpoolBytes and SpoolBytes newtypes. The spool adds and compares both of them exactly, which an f64-backed [ByteSize] cannot promise. The quantity stays the boundary type: Spool::open takes one and Spool::size returns one.

Implementations

impl Spool

pub fn resume_point(&self) -> Result<Option<(u64, [u8; 32])>, AuditError>

The (next_seq, head) from the last chained record in the spool.

A chained record is a record that is not a checkpoint. Returns None if the spool has no chained record.

Errors

Returns an error if the spool file cannot be opened or read.

impl Spool

pub fn open(dir: &Path, max_size: ByteSize) -> Result<Self, AuditError>

Open the spool and recover its existing contents.

This function creates the directory and the file if they do not exist.

Errors

Returns an error if the spool directory cannot be created. Returns an error if the spool file cannot be opened, read, or truncated.

pub fn open_with_sync_every( dir: &Path, max_size: ByteSize, sync_every: NonZeroU64, ) -> Result<Self, AuditError>

Open the spool with an explicit append-to-fsync cadence.

A cadence of N syncs after every N successful appends. Appends before that boundary are visible after a process crash but are not promised to survive power loss until Self::sync succeeds.

Errors

Returns an error if the spool directory cannot be created. Returns an error if the spool file cannot be opened, read, synced, or truncated.

pub fn is_empty(&self) -> bool

pub fn count(&self) -> RecordCount

pub fn size(&self) -> ByteSize

How many bytes the spool currently holds.

pub fn recovered_torn_tail(&self) -> bool

Whether Spool::open found a torn tail frame and cut it off.

A crash partway through an append leaves a frame whose length prefix promises more bytes than follow it. open heals that, and this reports whether it had to – healing a spool that was intact would mean discarding good bytes, so the two cases are worth telling apart.

pub fn append(&mut self, record: &AuditRecord) -> Result<bool, AuditError>

Append a record to the spool.

Returns Ok(false) if the record would make the spool exceed the configured cap.

Errors

Returns an error if the seek, write, rollback, or configured sync on the spool file fails.

pub fn sync(&mut self) -> Result<(), AuditError>

Force all appended records to stable storage.

Callers using a sync cadence greater than one use this before reporting a durable acknowledgement.

Errors

Returns an error if the spool file cannot be synced.

pub fn read_all(&self) -> Result<Vec<AuditRecord>, AuditError>

Read every record from the start of the spool, in order.

Errors

Returns an error if the spool file cannot be opened or read.

pub fn truncate(&mut self) -> Result<(), AuditError>

Clear the spool.

Errors

Returns an error if the spool file cannot be truncated, or if the seek or sync that follows fails.

Trait Implementations

impl Debug for Spool

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

Formats the value using the given formatter.