Struct AuditWriter 

pub struct AuditWriter { /* private fields */ }

Caller-owned audit writer. Construction starts no workers, timers, or database operations.

Queued admission acknowledges memory only. Mandatory audit should use the DB store in the business transaction, or explicitly await flush and map failures at the product boundary. A failed or interrupted write remains available through unconfirmed; never replay an unknown commit without reconciling it first. Stop/join this writer before closing the database.

Implementations

impl AuditWriter

pub fn new(db: DatabaseConnection) -> Self

Uses default bounds and a bounded direct-overflow lane.

pub fn with_config( db: DatabaseConnection, config: AuditLogBufferConfig, overflow: OverflowPolicy, events: Option<Sender<BufferedWriterEvent>>, ) -> Self

Configures overflow and optional bounded event delivery. Observer code is never invoked by this writer; a slow, panicking, or absent event consumer cannot block persistence.

pub async fn start(&self) -> Result<(), BufferedWriterState>

Starts the owned worker exactly once; normally called by the runtime component.

Errors

Returns the current state when already started, draining, or stopped.

pub async fn record( &self, request: AuditLogCreate, ) -> Result<RecordAdmission, RecordError<AuditLogCreate, DbError>>

Admits an audit record. Queued acknowledges memory only; DirectPersisted acknowledges just this overflow record. A cancelled direct waiter does not revoke accepted admission.

Errors

Rejected records are returned. Direct failures retain the accepted record in this writer.

pub fn begin_drain(&self)

Atomically closes admission while keeping accepted records available for drain. Call after all product producers and the server-shutdown audit hook have finished.

pub async fn flush( &self, deadline: Instant, ) -> Result<(), BufferFlushError<DbError>>

Awaits persistence of records accepted before this future’s first poll, without closing admission. Batch and direct writes are acknowledged separately; later records and their failures do not extend this scope. An expired deadline schedules no new forced write, while an already acknowledged scope succeeds immediately, even with an expired deadline. Failed records stay in memory; cancelling this future leaves persistence owned by the worker.

Errors

Returns lifecycle, original classified persistence, or deadline errors.

pub async fn stop(&self, deadline: Instant) -> BufferStopReport<DbError>

Closes admission, attempts drain, then cancels and joins the worker before returning. Inspect remaining counts/failures before deciding product exit behavior. Repeated and concurrent calls are safe; database handles must remain open until this completes.

pub fn retry_failed(&self)

Explicitly resumes only retry-safe failures; unknown commits and permanent failures stay blocked. Does not restart a stopped writer or silently replay retained records.

pub fn snapshot(&self) -> BufferedWriterSnapshot<DbError>

Returns per-instance state, acknowledgment counters, and original classified failures.

pub fn unconfirmed(&self) -> Vec<AuditLogCreate>

Copies unacknowledged records for product-controlled reconciliation. Stop the writer first for a stable recovery snapshot; these records must not be assumed absent from DB.