Skip to main content

TtlCache

Struct TtlCache 

Source
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>
where K: Clone + Eq + Hash + Ord,

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn get<Q>(&self, key: &Q) -> Option<V>
where K: Borrow<Q>, Q: Hash + Eq + ?Sized, V: Clone,

Look up key, returning a clone of the value if present and not yet expired. Performs a bounded inline reap first.

Accepts any borrowed form of the key (e.g. &str for a String-keyed cache) to avoid allocating on lookup.

Source

pub fn len(&self) -> usize

Number of live (un-reaped) entries.

Source

pub fn is_empty(&self) -> bool

True when no entries are present.

Auto Trait Implementations§

§

impl<K, V> !Freeze for TtlCache<K, V>

§

impl<K, V> !RefUnwindSafe for TtlCache<K, V>

§

impl<K, V> Send for TtlCache<K, V>
where K: Send, V: Send,

§

impl<K, V> Sync for TtlCache<K, V>
where K: Send, V: Send,

§

impl<K, V> Unpin for TtlCache<K, V>
where K: Unpin, V: Unpin,

§

impl<K, V> UnsafeUnpin for TtlCache<K, V>

§

impl<K, V> UnwindSafe for TtlCache<K, V>
where K: UnwindSafe, V: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.