Struct DecisionCache

pub struct DecisionCache { /* private fields */ }

LRU + TTL decision cache.

Backed by a simple LRU map. Thread-safe via [parking_lot::RwLock]: reads (the common case on a hot PDP) take a shared lock and run concurrently; only put() (cache fill) takes the exclusive lock.

Note: a cache miss can still trigger a “thundering herd” where many concurrent readers all see None for a popular key and all run the underlying authorization. A single-flight pattern (per-key OnceCell) would close this, but is left for a future enhancement.

Implementations

impl DecisionCache

pub fn try_new( config: CacheConfig, clock: Arc<dyn Clock>, ) -> Result<Self, String>

Construct a cache after validating its public configuration.

Use this at application boundaries so invalid capacities produce a recoverable configuration error instead of a panic.

pub fn new(config: CacheConfig, clock: Arc<dyn Clock>) -> Self

Construct a cache with an already validated configuration.

Panics

Panics when the capacity is zero or a TTL exceeds the monotonic clock range. Use Self::try_new when values come from application configuration or another fallible input.

pub fn disabled(clock: Arc<dyn Clock>) -> Self

A disabled cache (every call is a miss).

pub fn policy_version(&self) -> u64

pub fn invalidate_all(&self)

Bump the policy version. All cache entries are invalidated on the next get() because the stored cached_at_policy_version no longer matches.

pub fn set_policy_version(&self, v: u64)

Convenience: set the policy version to a specific value.

pub fn get(&self, key: &CacheKey) -> Option<CachedDecision>

pub fn sweep_stale(&self) -> usize

Drain stale (policy-version mismatch) and expired entries from the cache. Cheap when nothing is stale: O(1) under the fast path. Designed to be called from a background task or after Self::invalidate_all.

Returns the number of entries dropped. Used by tests to assert the eviction worked.

pub fn put(&self, key: CacheKey, decision: CachedDecision)

pub fn stats(&self) -> CacheStats

pub fn config_from_env() -> CacheConfig

👎Deprecated: use try_config_from_env to reject malformed settings

Build a CacheConfig from the AGENTGUARD_CACHE_* environment variables.

Environment knobs (humantime where applicable):

• AGENTGUARD_CACHE_TTL — sets allow_ttl. Does NOT touch deny_ttl (use AGENTGUARD_DENY_CACHE_TTL for that).
• AGENTGUARD_DENY_CACHE_TTL — sets deny_ttl independently. Falls back to the default when unset.
• AGENTGUARD_CACHE_CAPACITY — sets the LRU capacity (positive integer).

Falls back to defaults when unset or unparseable.

pub fn try_config_from_env() -> Result<CacheConfig, String>

Parse cache settings from the process environment, rejecting malformed values rather than silently changing the requested operating limits.

pub fn try_config_from_overrides( cache_ttl: Option<&str>, deny_ttl: Option<&str>, capacity: Option<&str>, ) -> Result<CacheConfig, String>

Parse optional environment-style cache overrides strictly.

pub fn config_from_overrides( cache_ttl: Option<String>, deny_ttl: Option<String>, capacity: Option<String>, ) -> CacheConfig

Same as Self::config_from_env but accepts explicit overrides. Used by tests so they don’t have to mutate std::env from unsafe blocks (the crate forbids unsafe).