1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
//! DST-friendly local hot-path cache primitives.
//!
//! [`ClockTtlCache`] is a TTL+LRU cache where every time-dependent decision
//! goes through an injected [`Clock`](axess_clock::Clock) (from
//! `axess-clock`). It exists so axess can offer hot-path caching without
//! falling back to the `Instant::now()` + background-task model used by
//! `moka` and friends, both of which break deterministic-simulation
//! testing because their TTL eviction is invisible to test-mocked time.
//!
//! # Why not use moka directly?
//!
//! - **DST**: moka's TTL is wall-clock only; advancing a `MockClock` does
//! not expire moka entries. Tests covering "entry expires after T" become
//! impossible to write deterministically.
//! - **Background scheduler**: moka spawns its own housekeeping task on a
//! real-time interval. In a test runtime that controls time, this still
//! advances on real wall-clock, leaking non-determinism.
//!
//! `ClockTtlCache` resolves both: TTL is checked on access against
//! `clock.now()`, capacity-bounded eviction happens at insert time (LRU
//! oldest-first), and there are no background tasks.
//!
//! # Compliance posture
//!
//! Caching authentication state (session validity, user identity) is widely
//! flagged by PSD2/FAPI/SCA-style auditors. Caching *authorization input
//! data* (the entity graph that Cedar evaluates against) is not. The
//! decision is recomputed every request against fresh-from-cache entities.
//! When you reach for this primitive, ask which side of that line you're
//! on. The same code shape can be used for either, but the tradeoffs
//! differ. See `axess-core::authz::cache` for the canonical authz use.
//!
//! # Quick start
//!
//! ```rust
//! use axess_cache::ClockTtlCache;
//! use axess_clock::Clock;
//! use axess_clock::testing::MockClock;
//! use chrono::{TimeZone, Utc};
//! use std::num::NonZeroUsize;
//! use std::sync::Arc;
//! use std::time::Duration;
//!
//! let clock = Arc::new(MockClock::at(Utc.with_ymd_and_hms(2026, 1, 1, 0, 0, 0).unwrap()));
//! let cache: ClockTtlCache<&'static str, u32> = ClockTtlCache::new(
//! NonZeroUsize::new(128).unwrap(),
//! Duration::from_secs(60),
//! clock.clone() as Arc<dyn Clock>,
//! );
//!
//! cache.insert("k", 42);
//! assert_eq!(cache.get(&"k"), Some(42));
//!
//! // Advance past the TTL; entry must be gone on next access.
//! clock.advance_secs(61);
//! assert_eq!(cache.get(&"k"), None);
//! ```
//!
//! # Module layout
//!
//! - `stats`: [`CacheStats`] public counter snapshot.
//! - `cache`: [`ClockTtlCache`] core: LRU + TTL + single-flight loader.
pub use ClockTtlCache;
pub use CacheStats;