1use super::{
16 AuditBackend, AuditEvent, AuditIntegrity, AuditSeverity, LiveFilter, NoRedaction, Provenance,
17 Redactor, Scope,
18};
19#[cfg(feature = "hlc")]
20use super::{EventClock, HlcClock, HlcTimestamp};
21use std::sync::Arc;
22use std::sync::atomic::{AtomicU8, Ordering};
23
24fn level_to_u8(level: AuditSeverity) -> u8 {
26 match level {
27 AuditSeverity::Trace => 0,
28 AuditSeverity::Debug => 1,
29 AuditSeverity::Info => 2,
30 AuditSeverity::Warning => 3,
31 AuditSeverity::Error => 4,
32 AuditSeverity::Critical => 5,
33 }
34}
35
36fn u8_to_level(raw: u8) -> AuditSeverity {
39 match raw {
40 0 => AuditSeverity::Trace,
41 1 => AuditSeverity::Debug,
42 2 => AuditSeverity::Info,
43 3 => AuditSeverity::Warning,
44 4 => AuditSeverity::Error,
45 _ => AuditSeverity::Critical,
46 }
47}
48
49pub struct Logger {
86 backend: Arc<dyn AuditBackend>,
87 integrity: Arc<dyn AuditIntegrity>,
88 min_level: AtomicU8,
89 identity: Provenance,
90 redactor: Arc<dyn Redactor>,
91 filter: Option<LiveFilter>,
92 #[cfg(feature = "hlc")]
93 clock: Option<Arc<HlcClock>>,
94}
95
96impl Logger {
97 #[must_use]
99 pub fn builder(backend: Arc<dyn AuditBackend>) -> LoggerBuilder {
100 LoggerBuilder {
101 backend,
102 integrity: None,
103 min_level: AuditSeverity::Info,
104 identity: Provenance::new(),
105 redactor: None,
106 filter: None,
107 #[cfg(feature = "hlc")]
108 clock: None,
109 }
110 }
111
112 #[must_use]
114 pub fn min_level(&self) -> AuditSeverity {
115 u8_to_level(self.min_level.load(Ordering::Relaxed))
116 }
117
118 pub fn set_min_level(&self, level: AuditSeverity) {
122 self.min_level.store(level_to_u8(level), Ordering::Relaxed);
123 }
124
125 #[must_use]
131 pub fn admits(&self, event: &AuditEvent) -> bool {
132 if event.event_type.is_security_relevant() {
133 return true;
134 }
135 event.severity >= self.threshold_for(event)
136 }
137
138 fn threshold_for(&self, event: &AuditEvent) -> AuditSeverity {
144 let Some(filter) = &self.filter else {
145 return self.min_level();
146 };
147 let Some(module) = event.provenance.module.as_deref() else {
148 return self.min_level();
149 };
150 if filter.is_empty() {
151 return self.min_level();
152 }
153 filter.level_for(module)
154 }
155
156 #[must_use]
158 pub fn filter(&self) -> Option<&LiveFilter> {
159 self.filter.as_ref()
160 }
161
162 #[must_use]
173 pub fn admits_diagnostic(&self, severity: AuditSeverity, module: &str) -> bool {
174 let threshold = match &self.filter {
175 Some(filter) if !filter.is_empty() => filter.level_for(module),
176 _ => self.min_level(),
177 };
178 severity >= threshold
179 }
180
181 #[cfg(feature = "hlc")]
187 fn stamp_hlc(&self, event: &mut AuditEvent) {
188 if event.hlc.is_some() {
189 return; }
191 if let Some(clock) = &self.clock
192 && let Ok(timestamp) = clock.now()
193 {
194 event.hlc = Some(EventClock::from(timestamp));
195 }
196 }
197
198 #[cfg(feature = "hlc")]
236 pub fn observe_hlc(&self, observed: HlcTimestamp) -> Result<HlcTimestamp, crate::HlcError> {
237 match &self.clock {
238 Some(clock) => clock.recv(observed),
239 None => Ok(observed),
240 }
241 }
242
243 #[cfg(feature = "hlc")]
248 #[must_use]
249 pub fn hlc_now(&self) -> Option<HlcTimestamp> {
250 self.clock.as_ref().and_then(|clock| clock.now().ok())
251 }
252
253 pub fn log(&self, event: AuditEvent) {
259 if !self.admits(&event) {
260 return;
261 }
262
263 let mut event = event;
264 if !self.identity.is_empty() {
265 event.provenance = std::mem::take(&mut event.provenance).or_fill_from(&self.identity);
266 }
267 Scope::apply_current(&mut event);
270 #[cfg(feature = "hlc")]
271 self.stamp_hlc(&mut event);
272 self.redactor.redact_event(&mut event);
276 self.integrity.add_integrity(&mut event);
277 self.backend.log_audit(&event);
278 }
279
280 #[track_caller]
282 pub fn diagnostic<S: Into<String>>(&self, level: AuditSeverity, message: S) {
283 self.log(
284 AuditEvent::diagnostic(message)
285 .severity(level)
286 .provenance(Provenance::capture())
287 .build(),
288 );
289 }
290
291 #[track_caller]
293 pub fn trace<S: Into<String>>(&self, message: S) {
294 self.diagnostic(AuditSeverity::Trace, message);
295 }
296
297 #[track_caller]
299 pub fn debug<S: Into<String>>(&self, message: S) {
300 self.diagnostic(AuditSeverity::Debug, message);
301 }
302
303 #[track_caller]
305 pub fn info<S: Into<String>>(&self, message: S) {
306 self.diagnostic(AuditSeverity::Info, message);
307 }
308
309 #[track_caller]
311 pub fn warn<S: Into<String>>(&self, message: S) {
312 self.diagnostic(AuditSeverity::Warning, message);
313 }
314
315 #[track_caller]
317 pub fn error<S: Into<String>>(&self, message: S) {
318 self.diagnostic(AuditSeverity::Error, message);
319 }
320
321 pub fn flush(&self) {
323 self.backend.flush();
324 }
325
326 #[must_use]
328 pub fn identity(&self) -> &Provenance {
329 &self.identity
330 }
331
332 #[must_use]
334 pub fn backend(&self) -> &Arc<dyn AuditBackend> {
335 &self.backend
336 }
337
338 #[must_use]
340 pub fn integrity(&self) -> &Arc<dyn AuditIntegrity> {
341 &self.integrity
342 }
343}
344
345impl std::fmt::Debug for Logger {
346 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
347 f.debug_struct("Logger")
348 .field("min_level", &self.min_level())
349 .finish_non_exhaustive()
350 }
351}
352
353pub struct LoggerBuilder {
355 backend: Arc<dyn AuditBackend>,
356 integrity: Option<Arc<dyn AuditIntegrity>>,
357 min_level: AuditSeverity,
358 identity: Provenance,
359 redactor: Option<Arc<dyn Redactor>>,
360 filter: Option<LiveFilter>,
361 #[cfg(feature = "hlc")]
362 clock: Option<Arc<HlcClock>>,
363}
364
365impl LoggerBuilder {
366 #[must_use]
369 pub fn integrity(mut self, integrity: Arc<dyn AuditIntegrity>) -> Self {
370 self.integrity = Some(integrity);
371 self
372 }
373
374 #[must_use]
377 pub fn min_level(mut self, level: AuditSeverity) -> Self {
378 self.min_level = level;
379 self
380 }
381
382 #[must_use]
388 pub fn identity(mut self, identity: Provenance) -> Self {
389 self.identity = identity;
390 self
391 }
392
393 #[cfg(feature = "hlc")]
400 #[must_use]
401 pub fn clock(mut self, clock: Arc<HlcClock>) -> Self {
402 self.clock = Some(clock);
403 self
404 }
405
406 #[must_use]
410 pub fn redact(mut self, redactor: Arc<dyn Redactor>) -> Self {
411 self.redactor = Some(redactor);
412 self
413 }
414
415 #[must_use]
421 pub fn filter(mut self, filter: LiveFilter) -> Self {
422 self.filter = Some(filter);
423 self
424 }
425
426 #[must_use]
428 pub fn build(self) -> Logger {
429 Logger {
430 backend: self.backend,
431 integrity: self
432 .integrity
433 .unwrap_or_else(|| Arc::new(crate::NoIntegrity)),
434 min_level: AtomicU8::new(level_to_u8(self.min_level)),
435 identity: self.identity,
436 redactor: self.redactor.unwrap_or_else(|| Arc::new(NoRedaction)),
437 filter: self.filter,
438 #[cfg(feature = "hlc")]
439 clock: self.clock,
440 }
441 }
442}
443
444#[cfg(test)]
445mod tests {
446 use super::*;
447 use crate::{AuditEventType, AuditResult, NoopAuditBackend, SequenceIntegrity};
448 use std::sync::Mutex;
449
450 #[derive(Default)]
452 struct CapturingBackend(Mutex<Vec<AuditEvent>>);
453
454 impl CapturingBackend {
455 fn events(&self) -> Vec<AuditEvent> {
456 self.0
457 .lock()
458 .unwrap_or_else(std::sync::PoisonError::into_inner)
459 .clone()
460 }
461 }
462
463 impl AuditBackend for CapturingBackend {
464 fn log_audit(&self, event: &AuditEvent) {
465 self.0
466 .lock()
467 .unwrap_or_else(std::sync::PoisonError::into_inner)
468 .push(event.clone());
469 }
470 }
471
472 fn security_event(severity: AuditSeverity) -> AuditEvent {
473 AuditEvent::builder()
474 .event_type(AuditEventType::AuthenticationAttempt)
475 .result(AuditResult::Success)
476 .severity(severity)
477 .build()
478 }
479
480 fn logger_at(level: AuditSeverity) -> (Logger, Arc<CapturingBackend>) {
481 let backend = Arc::new(CapturingBackend::default());
482 let logger = Logger::builder(backend.clone())
483 .integrity(Arc::new(SequenceIntegrity::new()))
484 .min_level(level)
485 .build();
486 (logger, backend)
487 }
488
489 #[test]
490 fn test_diagnostics_below_the_threshold_are_dropped() {
491 let (logger, backend) = logger_at(AuditSeverity::Warning);
492
493 logger.trace("trace");
494 logger.debug("debug");
495 logger.info("info");
496 logger.warn("warning");
497 logger.error("error");
498
499 let written: Vec<AuditSeverity> = backend.events().iter().map(|e| e.severity).collect();
500 assert_eq!(
501 written,
502 vec![AuditSeverity::Warning, AuditSeverity::Error],
503 "only diagnostics at or above the threshold are written"
504 );
505 }
506
507 #[test]
508 fn test_security_events_ignore_the_threshold() {
509 let (logger, backend) = logger_at(AuditSeverity::Critical);
512
513 logger.log(security_event(AuditSeverity::Trace));
514 logger.log(security_event(AuditSeverity::Info));
515 logger.diagnostic(AuditSeverity::Info, "should be dropped");
516
517 let events = backend.events();
518 assert_eq!(events.len(), 2, "both security events survive");
519 assert!(
520 events.iter().all(|e| e.event_type.is_security_relevant()),
521 "only the diagnostic was filtered"
522 );
523 }
524
525 #[test]
526 fn test_admits_matches_what_log_writes() {
527 let (logger, backend) = logger_at(AuditSeverity::Warning);
528
529 let low = AuditEvent::diagnostic("low")
530 .severity(AuditSeverity::Debug)
531 .build();
532 let high = AuditEvent::diagnostic("high")
533 .severity(AuditSeverity::Error)
534 .build();
535
536 assert!(!logger.admits(&low));
537 assert!(logger.admits(&high));
538
539 logger.log(low);
540 logger.log(high);
541 assert_eq!(backend.events().len(), 1, "admits agreed with log");
542 }
543
544 #[test]
545 fn test_min_level_is_adjustable_at_runtime() {
546 let (logger, backend) = logger_at(AuditSeverity::Error);
547 assert_eq!(logger.min_level(), AuditSeverity::Error);
548
549 logger.info("dropped");
550 logger.set_min_level(AuditSeverity::Debug);
551 logger.info("kept");
552
553 assert_eq!(logger.min_level(), AuditSeverity::Debug);
554 let events = backend.events();
555 assert_eq!(events.len(), 1);
556 assert_eq!(events[0].message.as_deref(), Some("kept"));
557 }
558
559 #[test]
560 fn test_level_round_trips_through_atomic_storage() {
561 for level in [
562 AuditSeverity::Trace,
563 AuditSeverity::Debug,
564 AuditSeverity::Info,
565 AuditSeverity::Warning,
566 AuditSeverity::Error,
567 AuditSeverity::Critical,
568 ] {
569 assert_eq!(u8_to_level(level_to_u8(level)), level);
570 }
571 assert_eq!(u8_to_level(200), AuditSeverity::Critical);
574 }
575
576 #[test]
577 fn test_default_builder_uses_noop_integrity_and_info() {
578 let logger = Logger::builder(Arc::new(NoopAuditBackend)).build();
579 assert_eq!(logger.min_level(), AuditSeverity::Info);
580 logger.debug("dropped by default threshold");
581 }
582
583 #[test]
584 fn test_filtered_events_do_not_consume_a_sequence_number() {
585 let (logger, backend) = logger_at(AuditSeverity::Error);
588
589 logger.debug("dropped");
590 logger.debug("dropped");
591 logger.error("kept");
592
593 let events = backend.events();
594 assert_eq!(events.len(), 1);
595 assert_eq!(
596 events[0]
597 .metadata
598 .get("sequence")
599 .and_then(serde_json::Value::as_u64),
600 Some(0),
601 "the first written event must hold sequence 0, not 2"
602 );
603 }
604
605 #[cfg(feature = "hlc")]
606 mod hlc {
607 use super::*;
608 use crate::{EventClock, HlcClock};
609
610 #[test]
611 fn test_events_are_stamped_when_a_clock_is_configured() {
612 let backend = Arc::new(CapturingBackend::default());
613 let logger = Logger::builder(backend.clone())
614 .clock(Arc::new(HlcClock::new()))
615 .build();
616
617 logger.info("first");
618 logger.info("second");
619
620 let events = backend.events();
621 let first = events[0].hlc.expect("stamped");
622 let second = events[1].hlc.expect("stamped");
623 assert!(
624 first.happened_before(second),
625 "later events carry strictly later timestamps"
626 );
627 }
628
629 #[test]
630 fn test_no_clock_leaves_the_field_absent() {
631 let backend = Arc::new(CapturingBackend::default());
632 let logger = Logger::builder(backend.clone()).build();
633
634 logger.info("unstamped");
635
636 assert_eq!(
637 backend.events()[0].hlc,
638 None,
639 "the field costs nothing until a clock is configured"
640 );
641 }
642
643 #[test]
644 fn test_stamps_are_monotonic_across_threads() {
645 let backend = Arc::new(CapturingBackend::default());
648 let clock = Arc::new(HlcClock::new());
649 let logger = Arc::new(
650 Logger::builder(backend.clone())
651 .clock(clock.clone())
652 .build(),
653 );
654
655 let mut handles = Vec::new();
656 for n in 0..8 {
657 let logger = logger.clone();
658 handles.push(std::thread::spawn(move || {
659 for i in 0..16 {
660 logger.info(format!("thread {n} event {i}"));
661 }
662 }));
663 }
664 for handle in handles {
665 handle.join().expect("worker thread panicked");
666 }
667
668 let mut stamps: Vec<EventClock> = backend
669 .events()
670 .iter()
671 .map(|e| e.hlc.expect("stamped"))
672 .collect();
673 assert_eq!(stamps.len(), 128);
674
675 let before = stamps.len();
676 stamps.sort_unstable();
677 stamps.dedup();
678 assert_eq!(
679 stamps.len(),
680 before,
681 "every event gets a distinct timestamp, so the order is total"
682 );
683 }
684
685 #[test]
686 fn test_an_explicit_timestamp_on_the_event_wins() {
687 let backend = Arc::new(CapturingBackend::default());
688 let logger = Logger::builder(backend.clone())
689 .clock(Arc::new(HlcClock::new()))
690 .build();
691
692 let pinned = EventClock {
693 physical: 1,
694 logical: 2,
695 };
696 logger.log(
697 AuditEvent::diagnostic("preset")
698 .severity(AuditSeverity::Info)
699 .hlc(pinned)
700 .build(),
701 );
702
703 assert_eq!(
704 backend.events()[0].hlc,
705 Some(pinned),
706 "a caller-supplied timestamp is not overwritten"
707 );
708 }
709
710 #[test]
711 fn test_observe_advances_the_clock_past_an_upstream_timestamp() {
712 let backend = Arc::new(CapturingBackend::default());
716 let logger = Logger::builder(backend.clone())
717 .clock(Arc::new(HlcClock::new()))
718 .build();
719
720 let upstream = HlcClock::new().now().expect("system clock is sane");
721 logger.observe_hlc(upstream).expect("observation accepted");
722 logger.info("after the upstream event");
723
724 let stamped = backend.events()[0].hlc.expect("stamped");
725 assert!(
726 EventClock::from(upstream).happened_before(stamped),
727 "local events are ordered after the observed timestamp"
728 );
729 }
730
731 #[test]
732 fn test_observe_without_a_clock_is_inert() {
733 let logger = Logger::builder(Arc::new(NoopAuditBackend)).build();
734 let upstream = HlcClock::new().now().unwrap();
735
736 assert_eq!(
737 logger.observe_hlc(upstream),
738 Ok(upstream),
739 "a logger with no clock has no ordering to advance"
740 );
741 assert_eq!(logger.hlc_now(), None);
742 }
743
744 #[test]
745 fn test_filtered_events_do_not_consume_a_timestamp() {
746 let backend = Arc::new(CapturingBackend::default());
749 let clock = Arc::new(HlcClock::new());
750 let logger = Logger::builder(backend.clone())
751 .clock(clock.clone())
752 .min_level(AuditSeverity::Error)
753 .build();
754
755 logger.info("dropped");
756 let before = clock.last();
757 logger.info("also dropped");
758 assert_eq!(
759 clock.last(),
760 before,
761 "filtered events never reach the clock"
762 );
763
764 logger.error("written");
765 assert!(backend.events()[0].hlc.is_some());
766 }
767 }
768}