kovra_core/
clock.rs

1//! Time behind a trait (CLAUDE.md rule 4: the clock is a trait).
2//!
3//! L3 is the first layer that observes time — audit timestamps (§11) and
4//! confirmation deadlines (§8). Both go through [`Clock`] so core logic is
5//! tested deterministically with [`MockClock`]; production uses [`SystemClock`].
6
7use std::time::{Duration, SystemTime, UNIX_EPOCH};
8
9/// A source of wall-clock time. Returns both a monotonic-ish epoch instant (for
10/// deadline math) and an RFC-3339 rendering (for audit records).
11pub trait Clock: Send + Sync {
12    /// Seconds since the Unix epoch (UTC).
13    fn unix_secs(&self) -> u64;
14
15    /// The current time as an RFC-3339 / ISO-8601 UTC string, e.g.
16    /// `2026-05-30T22:18:30Z`. Default impl derives it from [`Clock::unix_secs`].
17    fn now_rfc3339(&self) -> String {
18        format_rfc3339_utc(self.unix_secs())
19    }
20}
21
22/// Real system clock.
23#[derive(Debug, Default, Clone, Copy)]
24pub struct SystemClock;
25
26impl Clock for SystemClock {
27    fn unix_secs(&self) -> u64 {
28        SystemTime::now()
29            .duration_since(UNIX_EPOCH)
30            .unwrap_or(Duration::ZERO)
31            .as_secs()
32    }
33}
34
35/// Deterministic, advanceable clock for tests.
36#[derive(Debug)]
37pub struct MockClock {
38    secs: std::sync::atomic::AtomicU64,
39}
40
41impl MockClock {
42    /// A mock clock fixed at `secs` since the epoch.
43    pub fn at(secs: u64) -> Self {
44        Self {
45            secs: std::sync::atomic::AtomicU64::new(secs),
46        }
47    }
48
49    /// Advance the mock clock by `secs` seconds (simulating elapsed time).
50    pub fn advance(&self, secs: u64) {
51        self.secs
52            .fetch_add(secs, std::sync::atomic::Ordering::SeqCst);
53    }
54}
55
56impl Default for MockClock {
57    fn default() -> Self {
58        // A fixed, recognizable instant: 2026-05-30T00:00:00Z.
59        Self::at(1_780_099_200)
60    }
61}
62
63impl Clock for MockClock {
64    fn unix_secs(&self) -> u64 {
65        self.secs.load(std::sync::atomic::Ordering::SeqCst)
66    }
67}
68
69/// Format a Unix-seconds instant as an RFC-3339 UTC string (`...Z`), using the
70/// civil-from-days algorithm — no external date dependency.
71fn format_rfc3339_utc(unix_secs: u64) -> String {
72    let days = (unix_secs / 86_400) as i64;
73    let secs_of_day = unix_secs % 86_400;
74    let (hour, min, sec) = (
75        secs_of_day / 3600,
76        (secs_of_day % 3600) / 60,
77        secs_of_day % 60,
78    );
79
80    // Howard Hinnant's civil_from_days (epoch = 1970-01-01).
81    let z = days + 719_468;
82    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
83    let doe = (z - era * 146_097) as u64; // [0, 146096]
84    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365; // [0, 399]
85    let year = yoe as i64 + era * 400;
86    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); // [0, 365]
87    let mp = (5 * doy + 2) / 153; // [0, 11]
88    let day = doy - (153 * mp + 2) / 5 + 1; // [1, 31]
89    let month = if mp < 10 { mp + 3 } else { mp - 9 }; // [1, 12]
90    let year = if month <= 2 { year + 1 } else { year };
91
92    format!("{year:04}-{month:02}-{day:02}T{hour:02}:{min:02}:{sec:02}Z")
93}
94
95#[cfg(test)]
96mod tests {
97    use super::*;
98
99    #[test]
100    fn mock_clock_is_fixed_then_advances() {
101        let c = MockClock::at(1000);
102        assert_eq!(c.unix_secs(), 1000);
103        c.advance(50);
104        assert_eq!(c.unix_secs(), 1050);
105    }
106
107    #[test]
108    fn rfc3339_formats_known_instants() {
109        // 0 → epoch.
110        assert_eq!(format_rfc3339_utc(0), "1970-01-01T00:00:00Z");
111        // A known instant: 2026-05-30T00:00:00Z.
112        assert_eq!(format_rfc3339_utc(1_780_099_200), "2026-05-30T00:00:00Z");
113        // With time-of-day.
114        assert_eq!(
115            format_rfc3339_utc(1_780_099_200 + 3661),
116            "2026-05-30T01:01:01Z"
117        );
118    }
119
120    #[test]
121    fn mock_default_clock_renders_expected_date() {
122        assert_eq!(MockClock::default().now_rfc3339(), "2026-05-30T00:00:00Z");
123    }
124
125    #[test]
126    fn system_clock_is_after_2020() {
127        // Sanity: real clock returns a plausible recent instant.
128        assert!(SystemClock.unix_secs() > 1_577_836_800); // 2020-01-01
129    }
130}
kovra_core/clock.rs

kovra_core/
clock.rs
