pub struct TtlCache<K, V> { /* private fields */ }Expand description
Generic per-entry-TTL cache with lazy version-tagged eviction and a capacity bound. See the module docs for the design.
§Examples
use std::time::Duration;
use hyprstream_util::{InsertIfAbsentNoEvictResult, TtlCache};
let cache: TtlCache<String, u32> = TtlCache::new(16, 8);
cache.insert("session-1".to_owned(), 42, Duration::from_secs(60));
assert_eq!(cache.get("session-1"), Some(42));
// `insert_if_absent_no_evict` is the replay-barrier primitive: while the
// entry is live, re-inserting the same key is reported as a duplicate, and
// a full barrier reports exhaustion instead of evicting live replay state
// (unlike `insert_if_absent`, which may evict to admit the new key).
assert_eq!(
cache.insert_if_absent_no_evict("session-1".to_owned(), 7, Duration::from_secs(60)),
InsertIfAbsentNoEvictResult::Duplicate,
);
// At capacity, a new key is refused rather than displacing a live entry.
let barrier: TtlCache<String, u32> = TtlCache::new(1, 8);
assert_eq!(
barrier.insert_if_absent_no_evict("jti-a".to_owned(), 1, Duration::from_secs(60)),
InsertIfAbsentNoEvictResult::Inserted,
);
assert_eq!(
barrier.insert_if_absent_no_evict("jti-b".to_owned(), 2, Duration::from_secs(60)),
InsertIfAbsentNoEvictResult::Full,
);
assert_eq!(barrier.get("jti-a"), Some(1), "live replay state preserved");Implementations§
Source§impl<K, V> TtlCache<K, V>
impl<K, V> TtlCache<K, V>
Sourcepub fn new(max_entries: usize, reap_budget: usize) -> Self
pub fn new(max_entries: usize, reap_budget: usize) -> Self
Create a cache bounded to max_entries, reaping at most
reap_budget expired heap nodes per access.
Sourcepub fn insert(&self, key: K, value: V, ttl: Duration)
pub fn insert(&self, key: K, value: V, ttl: Duration)
Insert (or replace) key with value, expiring after ttl.
Re-inserting an existing key refreshes it: a new version is
assigned and the prior heap node becomes stale (reaped lazily).
If the cache is at capacity and key is new, the next-to-expire
entry is evicted first.
Sourcepub fn insert_if_absent(&self, key: K, value: V, ttl: Duration) -> bool
pub fn insert_if_absent(&self, key: K, value: V, ttl: Duration) -> bool
Atomically insert key only if no live (unexpired) entry exists
for it, returning true if the key was newly inserted.
Returns false when a live entry already exists — i.e. this key
is a duplicate/replay within its validity window. The check and
the insert happen under a single lock, so concurrent callers for
the same key cannot both observe “absent” (the race that a
get-then-insert sequence would open). Expired entries are
reaped inline first, so an expired entry does not block insertion.
This is the primitive for replay/dedup caches (e.g. DPoP jti
replay prevention, RFC 9449 §11.1): a caller proceeds only when
this returns true, and rejects on false.
Sourcepub fn insert_if_absent_no_evict(
&self,
key: K,
value: V,
ttl: Duration,
) -> InsertIfAbsentNoEvictResult
pub fn insert_if_absent_no_evict( &self, key: K, value: V, ttl: Duration, ) -> InsertIfAbsentNoEvictResult
Atomically insert key only if it is absent and capacity is available.
Unlike Self::insert_if_absent, this variant never evicts a live
entry to make room. This fail-closed behavior is intended for replay caches
whose live entries are security state: evicting one early would allow
the corresponding assertion to be accepted again. The result separates
a blocked replay from exhaustion, so operators can alert on the latter.