Struct JsonCache 

pub struct JsonCache<T> { /* private fields */ }

A generic file-based cache with atomic writes, TTL, and schema versioning.

Each entry is a JSON file under cache_dir whose name derives from the entry key. Writes go to a temporary sibling file that is then renamed over the target, so a reader never observes a torn write. Reads enforce both the configured TTL (via file mtime) and the CACHE_SCHEMA_VERSION envelope.

Implementations

impl<T> JsonCache<T>

where T: Serialize + DeserializeOwned,

pub fn new(cache_dir: PathBuf, ttl: Duration) -> Result<Self>

Create a cache rooted at cache_dir, creating the directory if needed.

pub fn path_for(&self, file_name: &str) -> PathBuf

Path for a named entry (the name must already be filesystem-safe).

pub fn dir(&self) -> &Path

Cache directory root.

pub fn get_named(&self, file_name: &str) -> Option<T>

Read a cached value by file name.

Returns None (evicting the file) when the entry is missing, older than the TTL, has a mismatched schema version, or fails to parse.

One exception: in process-wide offline mode a TTL-expired entry is served (and not evicted) so an air-gapped run can fall back to whatever data is on disk. A staleness warning is logged. The online path is unchanged — expired entries are still evicted on read.

pub fn get_named_allow_stale( &self, file_name: &str, ) -> Option<(T, Option<Duration>)>

Read a cached value, tolerating TTL expiry when offline.

Returns the payload together with a staleness signal: Some(age) is the amount the entry is past its TTL when it was served despite being expired (only possible in offline mode), or None when the entry was still fresh.

Unlike get_named, this never logs; it is the building block callers use when they want to surface the staleness (e.g. as CRA evidence) rather than only warn.

pub fn set_named<V: Serialize + ?Sized>( &self, file_name: &str, value: &V, ) -> Result<()>

Atomically write a value under file_name.

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

Read a cached value by CacheKey.

pub fn set<V: Serialize + ?Sized>( &self, key: &CacheKey, value: &V, ) -> Result<()>

Atomically write a value keyed by CacheKey.

pub fn remove(&self, key: &CacheKey) -> Result<()>

Remove a cached entry by CacheKey.

pub fn clear(&self) -> Result<()>

Remove every JSON entry from the cache directory.

pub fn stats(&self) -> CacheStats

Aggregate statistics over the cache directory.