use super::{
AuditBackend, AuditEvent, AuditIntegrity, AuditSeverity, LiveFilter, NoRedaction, Provenance,
Redactor, Scope,
};
#[cfg(feature = "hlc")]
use super::{EventClock, HlcClock, HlcTimestamp};
use std::sync::Arc;
use std::sync::atomic::{AtomicU8, Ordering};
fn level_to_u8(level: AuditSeverity) -> u8 {
match level {
AuditSeverity::Trace => 0,
AuditSeverity::Debug => 1,
AuditSeverity::Info => 2,
AuditSeverity::Warning => 3,
AuditSeverity::Error => 4,
AuditSeverity::Critical => 5,
}
}
fn u8_to_level(raw: u8) -> AuditSeverity {
match raw {
0 => AuditSeverity::Trace,
1 => AuditSeverity::Debug,
2 => AuditSeverity::Info,
3 => AuditSeverity::Warning,
4 => AuditSeverity::Error,
_ => AuditSeverity::Critical,
}
}
pub struct Logger {
backend: Arc<dyn AuditBackend>,
integrity: Arc<dyn AuditIntegrity>,
min_level: AtomicU8,
identity: Provenance,
redactor: Arc<dyn Redactor>,
filter: Option<LiveFilter>,
#[cfg(feature = "hlc")]
clock: Option<Arc<HlcClock>>,
}
impl Logger {
#[must_use]
pub fn builder(backend: Arc<dyn AuditBackend>) -> LoggerBuilder {
LoggerBuilder {
backend,
integrity: None,
min_level: AuditSeverity::Info,
identity: Provenance::new(),
redactor: None,
filter: None,
#[cfg(feature = "hlc")]
clock: None,
}
}
#[must_use]
pub fn min_level(&self) -> AuditSeverity {
u8_to_level(self.min_level.load(Ordering::Relaxed))
}
pub fn set_min_level(&self, level: AuditSeverity) {
self.min_level.store(level_to_u8(level), Ordering::Relaxed);
}
#[must_use]
pub fn admits(&self, event: &AuditEvent) -> bool {
if event.event_type.is_security_relevant() {
return true;
}
event.severity >= self.threshold_for(event)
}
fn threshold_for(&self, event: &AuditEvent) -> AuditSeverity {
let Some(filter) = &self.filter else {
return self.min_level();
};
let Some(module) = event.provenance.module.as_deref() else {
return self.min_level();
};
if filter.is_empty() {
return self.min_level();
}
filter.level_for(module)
}
#[must_use]
pub fn filter(&self) -> Option<&LiveFilter> {
self.filter.as_ref()
}
#[must_use]
pub fn admits_diagnostic(&self, severity: AuditSeverity, module: &str) -> bool {
let threshold = match &self.filter {
Some(filter) if !filter.is_empty() => filter.level_for(module),
_ => self.min_level(),
};
severity >= threshold
}
#[cfg(feature = "hlc")]
fn stamp_hlc(&self, event: &mut AuditEvent) {
if event.hlc.is_some() {
return; }
if let Some(clock) = &self.clock
&& let Ok(timestamp) = clock.now()
{
event.hlc = Some(EventClock::from(timestamp));
}
}
#[cfg(feature = "hlc")]
pub fn observe_hlc(&self, observed: HlcTimestamp) -> Result<HlcTimestamp, crate::HlcError> {
match &self.clock {
Some(clock) => clock.recv(observed),
None => Ok(observed),
}
}
#[cfg(feature = "hlc")]
#[must_use]
pub fn hlc_now(&self) -> Option<HlcTimestamp> {
self.clock.as_ref().and_then(|clock| clock.now().ok())
}
pub fn log(&self, event: AuditEvent) {
if !self.admits(&event) {
return;
}
let mut event = event;
if !self.identity.is_empty() {
event.provenance = std::mem::take(&mut event.provenance).or_fill_from(&self.identity);
}
Scope::apply_current(&mut event);
#[cfg(feature = "hlc")]
self.stamp_hlc(&mut event);
self.redactor.redact_event(&mut event);
self.integrity.add_integrity(&mut event);
self.backend.log_audit(&event);
}
#[track_caller]
pub fn diagnostic<S: Into<String>>(&self, level: AuditSeverity, message: S) {
self.log(
AuditEvent::diagnostic(message)
.severity(level)
.provenance(Provenance::capture())
.build(),
);
}
#[track_caller]
pub fn trace<S: Into<String>>(&self, message: S) {
self.diagnostic(AuditSeverity::Trace, message);
}
#[track_caller]
pub fn debug<S: Into<String>>(&self, message: S) {
self.diagnostic(AuditSeverity::Debug, message);
}
#[track_caller]
pub fn info<S: Into<String>>(&self, message: S) {
self.diagnostic(AuditSeverity::Info, message);
}
#[track_caller]
pub fn warn<S: Into<String>>(&self, message: S) {
self.diagnostic(AuditSeverity::Warning, message);
}
#[track_caller]
pub fn error<S: Into<String>>(&self, message: S) {
self.diagnostic(AuditSeverity::Error, message);
}
pub fn flush(&self) {
self.backend.flush();
}
#[must_use]
pub fn identity(&self) -> &Provenance {
&self.identity
}
#[must_use]
pub fn backend(&self) -> &Arc<dyn AuditBackend> {
&self.backend
}
#[must_use]
pub fn integrity(&self) -> &Arc<dyn AuditIntegrity> {
&self.integrity
}
}
impl std::fmt::Debug for Logger {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Logger")
.field("min_level", &self.min_level())
.finish_non_exhaustive()
}
}
pub struct LoggerBuilder {
backend: Arc<dyn AuditBackend>,
integrity: Option<Arc<dyn AuditIntegrity>>,
min_level: AuditSeverity,
identity: Provenance,
redactor: Option<Arc<dyn Redactor>>,
filter: Option<LiveFilter>,
#[cfg(feature = "hlc")]
clock: Option<Arc<HlcClock>>,
}
impl LoggerBuilder {
#[must_use]
pub fn integrity(mut self, integrity: Arc<dyn AuditIntegrity>) -> Self {
self.integrity = Some(integrity);
self
}
#[must_use]
pub fn min_level(mut self, level: AuditSeverity) -> Self {
self.min_level = level;
self
}
#[must_use]
pub fn identity(mut self, identity: Provenance) -> Self {
self.identity = identity;
self
}
#[cfg(feature = "hlc")]
#[must_use]
pub fn clock(mut self, clock: Arc<HlcClock>) -> Self {
self.clock = Some(clock);
self
}
#[must_use]
pub fn redact(mut self, redactor: Arc<dyn Redactor>) -> Self {
self.redactor = Some(redactor);
self
}
#[must_use]
pub fn filter(mut self, filter: LiveFilter) -> Self {
self.filter = Some(filter);
self
}
#[must_use]
pub fn build(self) -> Logger {
Logger {
backend: self.backend,
integrity: self
.integrity
.unwrap_or_else(|| Arc::new(crate::NoIntegrity)),
min_level: AtomicU8::new(level_to_u8(self.min_level)),
identity: self.identity,
redactor: self.redactor.unwrap_or_else(|| Arc::new(NoRedaction)),
filter: self.filter,
#[cfg(feature = "hlc")]
clock: self.clock,
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::{AuditEventType, AuditResult, NoopAuditBackend, SequenceIntegrity};
use std::sync::Mutex;
#[derive(Default)]
struct CapturingBackend(Mutex<Vec<AuditEvent>>);
impl CapturingBackend {
fn events(&self) -> Vec<AuditEvent> {
self.0
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.clone()
}
}
impl AuditBackend for CapturingBackend {
fn log_audit(&self, event: &AuditEvent) {
self.0
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.push(event.clone());
}
}
fn security_event(severity: AuditSeverity) -> AuditEvent {
AuditEvent::builder()
.event_type(AuditEventType::AuthenticationAttempt)
.result(AuditResult::Success)
.severity(severity)
.build()
}
fn logger_at(level: AuditSeverity) -> (Logger, Arc<CapturingBackend>) {
let backend = Arc::new(CapturingBackend::default());
let logger = Logger::builder(backend.clone())
.integrity(Arc::new(SequenceIntegrity::new()))
.min_level(level)
.build();
(logger, backend)
}
#[test]
fn test_diagnostics_below_the_threshold_are_dropped() {
let (logger, backend) = logger_at(AuditSeverity::Warning);
logger.trace("trace");
logger.debug("debug");
logger.info("info");
logger.warn("warning");
logger.error("error");
let written: Vec<AuditSeverity> = backend.events().iter().map(|e| e.severity).collect();
assert_eq!(
written,
vec![AuditSeverity::Warning, AuditSeverity::Error],
"only diagnostics at or above the threshold are written"
);
}
#[test]
fn test_security_events_ignore_the_threshold() {
let (logger, backend) = logger_at(AuditSeverity::Critical);
logger.log(security_event(AuditSeverity::Trace));
logger.log(security_event(AuditSeverity::Info));
logger.diagnostic(AuditSeverity::Info, "should be dropped");
let events = backend.events();
assert_eq!(events.len(), 2, "both security events survive");
assert!(
events.iter().all(|e| e.event_type.is_security_relevant()),
"only the diagnostic was filtered"
);
}
#[test]
fn test_admits_matches_what_log_writes() {
let (logger, backend) = logger_at(AuditSeverity::Warning);
let low = AuditEvent::diagnostic("low")
.severity(AuditSeverity::Debug)
.build();
let high = AuditEvent::diagnostic("high")
.severity(AuditSeverity::Error)
.build();
assert!(!logger.admits(&low));
assert!(logger.admits(&high));
logger.log(low);
logger.log(high);
assert_eq!(backend.events().len(), 1, "admits agreed with log");
}
#[test]
fn test_min_level_is_adjustable_at_runtime() {
let (logger, backend) = logger_at(AuditSeverity::Error);
assert_eq!(logger.min_level(), AuditSeverity::Error);
logger.info("dropped");
logger.set_min_level(AuditSeverity::Debug);
logger.info("kept");
assert_eq!(logger.min_level(), AuditSeverity::Debug);
let events = backend.events();
assert_eq!(events.len(), 1);
assert_eq!(events[0].message.as_deref(), Some("kept"));
}
#[test]
fn test_level_round_trips_through_atomic_storage() {
for level in [
AuditSeverity::Trace,
AuditSeverity::Debug,
AuditSeverity::Info,
AuditSeverity::Warning,
AuditSeverity::Error,
AuditSeverity::Critical,
] {
assert_eq!(u8_to_level(level_to_u8(level)), level);
}
assert_eq!(u8_to_level(200), AuditSeverity::Critical);
}
#[test]
fn test_default_builder_uses_noop_integrity_and_info() {
let logger = Logger::builder(Arc::new(NoopAuditBackend)).build();
assert_eq!(logger.min_level(), AuditSeverity::Info);
logger.debug("dropped by default threshold");
}
#[test]
fn test_filtered_events_do_not_consume_a_sequence_number() {
let (logger, backend) = logger_at(AuditSeverity::Error);
logger.debug("dropped");
logger.debug("dropped");
logger.error("kept");
let events = backend.events();
assert_eq!(events.len(), 1);
assert_eq!(
events[0]
.metadata
.get("sequence")
.and_then(serde_json::Value::as_u64),
Some(0),
"the first written event must hold sequence 0, not 2"
);
}
#[cfg(feature = "hlc")]
mod hlc {
use super::*;
use crate::{EventClock, HlcClock};
#[test]
fn test_events_are_stamped_when_a_clock_is_configured() {
let backend = Arc::new(CapturingBackend::default());
let logger = Logger::builder(backend.clone())
.clock(Arc::new(HlcClock::new()))
.build();
logger.info("first");
logger.info("second");
let events = backend.events();
let first = events[0].hlc.expect("stamped");
let second = events[1].hlc.expect("stamped");
assert!(
first.happened_before(second),
"later events carry strictly later timestamps"
);
}
#[test]
fn test_no_clock_leaves_the_field_absent() {
let backend = Arc::new(CapturingBackend::default());
let logger = Logger::builder(backend.clone()).build();
logger.info("unstamped");
assert_eq!(
backend.events()[0].hlc,
None,
"the field costs nothing until a clock is configured"
);
}
#[test]
fn test_stamps_are_monotonic_across_threads() {
let backend = Arc::new(CapturingBackend::default());
let clock = Arc::new(HlcClock::new());
let logger = Arc::new(
Logger::builder(backend.clone())
.clock(clock.clone())
.build(),
);
let mut handles = Vec::new();
for n in 0..8 {
let logger = logger.clone();
handles.push(std::thread::spawn(move || {
for i in 0..16 {
logger.info(format!("thread {n} event {i}"));
}
}));
}
for handle in handles {
handle.join().expect("worker thread panicked");
}
let mut stamps: Vec<EventClock> = backend
.events()
.iter()
.map(|e| e.hlc.expect("stamped"))
.collect();
assert_eq!(stamps.len(), 128);
let before = stamps.len();
stamps.sort_unstable();
stamps.dedup();
assert_eq!(
stamps.len(),
before,
"every event gets a distinct timestamp, so the order is total"
);
}
#[test]
fn test_an_explicit_timestamp_on_the_event_wins() {
let backend = Arc::new(CapturingBackend::default());
let logger = Logger::builder(backend.clone())
.clock(Arc::new(HlcClock::new()))
.build();
let pinned = EventClock {
physical: 1,
logical: 2,
};
logger.log(
AuditEvent::diagnostic("preset")
.severity(AuditSeverity::Info)
.hlc(pinned)
.build(),
);
assert_eq!(
backend.events()[0].hlc,
Some(pinned),
"a caller-supplied timestamp is not overwritten"
);
}
#[test]
fn test_observe_advances_the_clock_past_an_upstream_timestamp() {
let backend = Arc::new(CapturingBackend::default());
let logger = Logger::builder(backend.clone())
.clock(Arc::new(HlcClock::new()))
.build();
let upstream = HlcClock::new().now().expect("system clock is sane");
logger.observe_hlc(upstream).expect("observation accepted");
logger.info("after the upstream event");
let stamped = backend.events()[0].hlc.expect("stamped");
assert!(
EventClock::from(upstream).happened_before(stamped),
"local events are ordered after the observed timestamp"
);
}
#[test]
fn test_observe_without_a_clock_is_inert() {
let logger = Logger::builder(Arc::new(NoopAuditBackend)).build();
let upstream = HlcClock::new().now().unwrap();
assert_eq!(
logger.observe_hlc(upstream),
Ok(upstream),
"a logger with no clock has no ordering to advance"
);
assert_eq!(logger.hlc_now(), None);
}
#[test]
fn test_filtered_events_do_not_consume_a_timestamp() {
let backend = Arc::new(CapturingBackend::default());
let clock = Arc::new(HlcClock::new());
let logger = Logger::builder(backend.clone())
.clock(clock.clone())
.min_level(AuditSeverity::Error)
.build();
logger.info("dropped");
let before = clock.last();
logger.info("also dropped");
assert_eq!(
clock.last(),
before,
"filtered events never reach the clock"
);
logger.error("written");
assert!(backend.events()[0].hlc.is_some());
}
}
}