Struct Cache 

pub struct Cache<S: CacheStore> { /* private fields */ }

A flexible caching system with pluggable storage strategies.

Features

• Works with any CacheStore implementation
• Structured cache keys with wildcard invalidation
• Negative caching (caches None results)
• Configurable expiration per operation
• Local stampede protection (prevents duplicate fetches within same process)
• Cost hints embedded in keys for tier-aware stores

Implementations

impl<S: CacheStore> Cache<S>

pub fn new(store: S) -> Self

Create a new cache with the given store

pub fn with_ttl(store: S, ttl: Duration) -> Self

Create a new cache with a custom default TTL

pub fn key<I, T>(&self, parts: I) -> CacheQuery<'_, S>

where I: IntoIterator<Item = T>, T: Into<KeyPart>,

Create a cache query from key parts.

Parts can be:

• String literals: "users", "123"
• KeyPart::hash(unbounded_value) for URLs, file paths, etc.
• KeyPart::hash_with_prefix("prefix", value) for debugging

Use "*" as a segment for wildcard matching during invalidation. An empty array [] maps to __root__.

Example

// Simple key from literals
cache.key(["users", "123"]).get(...).await?;

// Key with hashed segment for unbounded input
cache.key(["convertPCMtoMP3", KeyPart::hash(url)]).get(...).await?;

// Wildcard invalidation
cache.key(["users", "*"]).invalidate().await?;

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

Clear all cache entries

pub async fn stats(&self) -> StoreStats

Get cache statistics

pub fn default_ttl(&self) -> Duration

Get the default TTL

pub fn store(&self) -> &S

Get a reference to the underlying store

pub fn namespace(&self, namespace: impl Into<String>) -> NamespacedCache<'_, S>

Create a namespaced view of this cache.

All keys created through the namespaced cache will be prefixed with the namespace. This is useful for isolating cache entries by domain or feature.

Example

let audio_cache = cache.namespace("audio");

// Key becomes "audio:convert:123"
audio_cache.key(["convert", "123"]).get(...).await?;

// Invalidate all audio cache entries
audio_cache.key(["*"]).invalidate().await?;

pub async fn get_cached<T, F, Fut>( &self, id: T::Id, fetch: F, ) -> Result<Option<T>>

where T: Cached, F: FnOnce() -> Fut + Send, Fut: Future<Output = Option<T>> + Send,

Get a cached entity by ID, using the entity’s Cached trait implementation.

This is a convenience method that constructs the cache key from the entity’s CACHE_PREFIX and the provided ID, and uses the entity’s cache_ttl().

Example

// Entity implements Cached trait
let member: Option<Member> = cache
    .get_cached::<Member, _>(member_id, || async {
        Member::find_by_id(member_id, db).await.ok()
    })
    .await?;

pub async fn invalidate_cached<T>(&self, id: T::Id) -> Result<usize>

where T: Cached,

Invalidate a cached entity by ID, using the entity’s Cached trait implementation.

Example

// Invalidate a specific member's cache
cache.invalidate_cached::<Member>(member_id).await?;

pub async fn invalidate_all_cached<T>(&self) -> Result<usize>

where T: Cached,

Invalidate all cached entities of a given type.

Example

// Invalidate all cached members
cache.invalidate_all_cached::<Member>().await?;

Trait Implementations

impl<S: CacheStore> Clone for Cache<S>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.