Struct AuditLogger 

pub struct AuditLogger { /* private fields */ }

The main audit logger, dispatching events to configured sinks.

Thread-safe and designed for high-throughput operation. Sinks can be added at any time, even after wrapping in Arc.

Retention Policy

AuditLogger itself does not enforce a retention policy — it forwards events to sinks and forgets them. Retention is the responsibility of each sink:

• MemorySink: bounded by max_capacity (FIFO eviction).
• WriterSink: appends forever; pair with external log rotation (e.g. logrotate, cloud blob lifecycle rules).
• TracingSink: inherits the tracing subscriber’s retention.

For production deployments, configure a log rotation / archival pipeline and monitor the chronix_audit_events_total counter to ensure events are not silently dropped.

Implementations

impl AuditLogger

pub fn new() -> Self

Create a new audit logger with no sinks.

pub fn with_hmac_key(self, key: Vec<u8>) -> Self

Create an audit logger with an HMAC key.

When set, each event is sealed with HMAC-SHA-256 instead of plain SHA-256. An attacker with database write access cannot recompute the hash chain without possessing the key.

pub fn resume_from(self, last_id: u64, last_hash: Option<String>) -> Self

Continue an existing chain instead of starting a new one.

A restart used to reset the sequence to 1 and the previous hash to None, so every restart began a fresh chain in the same file. A verifier then could not tell a restart from a truncation: both look like an event whose prev_hash is None in the middle of the log. Anchoring on the last event already on disk makes the file one chain across the whole life of the deployment.

pub fn is_keyed(&self) -> bool

Whether the chain is sealed with a key rather than a bare hash.

pub fn add_sink(&self, sink: Box<dyn AuditSink>)

Add a sink. Can be called at any time, including after wrapping in Arc.

pub fn validate_has_durable_sink(&self) -> Result<()>

**** Validate that at least one durable audit sink is configured.

Returns Ok(()) if at least one sink reports is_durable() == true. Returns an error if no durable sinks are present, which means audit events would be lost on process restart — a compliance violation in regulated environments.

Call this at startup after configuring all sinks.

pub fn has_durable_sink(&self) -> bool

Check if at least one durable sink is configured.

pub fn log(&self, event: AuditEvent)

Log an audit event to all sinks.

Assigns a monotonic sequence number, seals the event into the hash chain, and writes it.

Sealing and writing are one step

They were two, with the lock released in between — so two concurrent callers could seal in one order and write in the other, leaving a file in which B precedes A while B.prev_hash names A. That is exactly what verify_hash_chain reports as tampering, and it happened with no write failing and nothing logged: an ordinary pair of simultaneous requests made a tamper-evident trail permanently unverifiable. A trail whose whole purpose is to be checkable cannot have a benign reason to fail its own check, because then no failure of it means anything.

So the chain lock is held across the emission. Audit events are rare relative to requests, and the file sink serialises on its own mutex anyway, so the lock is not a new bottleneck — it is the existing one, now covering the invariant it always should have.

pub fn next_sequence(&self) -> u64

Current sequence number (next ID to be assigned).

pub fn sink_count(&self) -> usize

Number of sinks.

pub fn flush(&self)

Flush all sinks.

pub fn log_strict(&self, event: AuditEvent) -> Result<()>

Strict audit logging — fail-closed mode for regulated environments.

Unlike log, this attempts all sinks even when some fail, and returns a PartialDelivery error if any sink could not emit. This gives the caller full visibility into which sinks succeeded vs failed so it can make an informed decision on whether to abort the protected operation.

pub fn flush_strict(&self) -> Result<()>

Strict flush — tries all sinks, reports partial failures.

Use this together with log_strict for fail-closed audit contexts where all buffered events must be durably persisted before acknowledging the protected operation.

Trait Implementations

impl Default for AuditLogger

fn default() -> Self

Returns the “default value” for a type.