Struct CacheBuilder 

pub struct CacheBuilder<K, V, CT = ()> { /* private fields */ }

Builder for constructing a cache with a single tier.

Created by calling Cache::builder(). Allows configuring storage, TTL, telemetry, and adding fallback tiers.

Examples

use std::time::Duration;

use cachet::Cache;
use tick::Clock;

let clock = Clock::new_tokio();
let cache = Cache::builder::<String, i32>(clock)
    .memory()
    .ttl(Duration::from_secs(60))
    .build();

Implementations

impl<K, V> CacheBuilder<K, V, ()>

pub fn storage<CT>(self, storage: CT) -> CacheBuilder<K, V, CT>

where CT: CacheTier<K, V>,

Sets a custom storage backend for the cache.

Use this to provide your own CacheTier implementation instead of the built-in options like memory().

Examples

use cachet::Cache;
use cachet_memory::InMemoryCache;
use tick::Clock;

let clock = Clock::new_tokio();
let cache = Cache::builder::<String, i32>(clock)
    .storage(InMemoryCache::new())
    .build();

pub fn memory(self) -> CacheBuilder<K, V, InMemoryCache<K, V>>

where K: Hash + Eq + Clone + Send + Sync + 'static, V: Clone + Send + Sync + 'static,

Available on crate feature memory only.

Configures the cache to use in-memory storage.

This is the most common storage backend, providing fast concurrent access with automatic eviction based on capacity.

Examples

use cachet::Cache;
use tick::Clock;

let clock = Clock::new_tokio();
let cache = Cache::builder::<String, i32>(clock).memory().build();

pub fn memory_with<F>( self, configure: F, ) -> CacheBuilder<K, V, InMemoryCache<K, V>>

where K: Hash + Eq + Clone + Send + Sync + 'static, V: Clone + Send + Sync + 'static, F: FnOnce(InMemoryCacheBuilder<K, V>) -> InMemoryCacheBuilder<K, V>,

Available on crate feature memory only.

Configures the cache to use in-memory storage, exposing the inner InMemoryCacheBuilder for additional configuration (capacity, TTL, eviction policy, custom hasher, etc.).

Call InMemoryCacheBuilder::with_eviction_telemetry inside the closure to emit cache.eviction on capacity evictions and cache.expired on background TTL/TTI expiry.

Panics

Panics if the configured InMemoryCacheBuilder fails validation (for example, max_capacity < initial_capacity).

Examples

use cachet::Cache;
use tick::Clock;

let clock = Clock::new_tokio();
let cache = Cache::builder::<String, i32>(clock)
    .memory_with(|b| b.max_capacity(1_000).with_eviction_telemetry())
    .build();

pub fn service<S>( self, service: S, ) -> CacheBuilder<K, V, ServiceAdapter<K, V, S>>

where K: Hash + Eq + Clone + Send + Sync + 'static, V: Clone + Send + Sync + 'static, S: Service<CacheOperation<K, V>, Out = Result<CacheResponse<V>, Error>> + Send + Sync,

Available on crate feature service only.

Configures the cache to use a service as the storage backend.

This adapts any Service<CacheOperation> to work as a CacheTier, enabling remote cache services (Redis, Memcached) or service-based storage implementations. The service can be composed with middleware (retry, timeout, circuit breakers) before being wrapped.

Examples

let cache = Cache::builder::<String, i32>(clock)
    .service(redis_service)
    .ttl(Duration::from_secs(300))
    .build();

impl<K, V, CT> CacheBuilder<K, V, CT>

pub fn name(self, name: &'static str) -> Self

Sets a human-readable name for this cache tier, used in telemetry attributes.

If not set, a name is derived from the storage type.

Requires &'static str because the name is embedded in every telemetry event (tracing fields, handler callbacks). A static reference avoids cloning the name into a new allocation on each cache operation, which matters at high throughput. In practice, cache names are always string literals.

pub fn enable_logs(self) -> Self

Available on crate features logs only.

Enables logging for this cache.

When enabled, cache operations will emit structured logs via the tracing crate.

pub fn stampede_protection(self) -> Self

Enables stampede protection for cache reads.

When enabled, concurrent requests for the same key will be merged so that only one request performs the lookup. Others wait and share the result.

This prevents the “thundering herd” problem where many concurrent cache misses for the same key overwhelm the backend.

Examples

use cachet::Cache;
use tick::Clock;

let clock = Clock::new_tokio();
let cache = Cache::builder::<String, i32>(clock)
    .memory()
    .stampede_protection()
    .build();

pub fn event_handler(self, handler: impl CacheEventHandler + 'static) -> Self

Registers a callback for structured cache events.

pub fn ttl(self, ttl: impl Into<Duration>) -> Self

Sets the time-to-live (TTL) for entries in this cache tier.

Entries older than the TTL will be considered expired and won’t be returned by get operations. Per-entry TTL in CacheEntry overrides this tier-level setting.

Examples

use std::time::Duration;

use cachet::Cache;
use tick::Clock;

let clock = Clock::new_tokio();
let cache = Cache::builder::<String, i32>(clock)
    .memory()
    .ttl(Duration::from_secs(300))
    .build();

pub fn insert_policy(self, policy: InsertPolicy<V>) -> Self

Sets the insert policy for this tier.

The policy determines when values should be inserted into this tier. It applies to all inserts, including direct Cache::insert calls, Cache::get_or_insert, and promotion from a fallback tier.

If the policy rejects an insert, the operation is skipped and a cache.insert_rejected telemetry event is recorded.

Examples

use cachet::{Cache, InsertPolicy};
use tick::Clock;

let clock = Clock::new_tokio();
let l2 = Cache::builder::<String, String>(clock.clone()).memory();

let cache = Cache::builder::<String, String>(clock)
    .memory()
    .insert_policy(InsertPolicy::always())
    .fallback(l2)
    .build();

pub fn clock(&self) -> &Clock

Returns a reference to the builder’s clock.

impl<K, V, CT> CacheBuilder<K, V, CT>

where K: Clone + Hash + Eq + Send + Sync + 'static, V: Clone + Send + Sync + 'static, CT: CacheTier<K, V> + Send + Sync + 'static,

pub fn fallback<FB>(self, fallback: FB) -> FallbackBuilder<K, V, Self, FB>

where FB: CacheTierBuilder<K, V>,

Creates a fallback cache with this as the primary tier.

The primary tier is checked first; on a miss, the fallback tier is queried and the result is inserted to the primary tier based on the insert policy.

Accepts either a CacheBuilder or another FallbackBuilder as the fallback.

pub fn build(self) -> Cache<K, V>

Builds the cache with the configured storage and settings.

Examples

use cachet::Cache;
use tick::Clock;

let clock = Clock::new_tokio();
let cache = Cache::builder::<String, i32>(clock).memory().build();

impl<K, V, CT> CacheBuilder<K, V, CT>

where K: Clone + Hash + Eq + Send + Sync + 'static, V: Clone + Send + Sync + 'static, CT: CacheTier<K, V> + Send + Sync + 'static,

pub fn serialize(self) -> TransformBuilder<K, V, BytesView, BytesView, Self>

where K: Serialize, V: Serialize + DeserializeOwned,

Available on crate features serialize only.

Applies a serialization boundary that converts keys and values to BytesView.

Subsequent .fallback() tiers must work with BytesView keys and values.

Examples

use cachet::Cache;
use tick::Clock;

let clock = Clock::new_tokio();
let remote = Cache::builder::<bytesbuf::BytesView, bytesbuf::BytesView>(clock.clone()).memory();

let cache = Cache::builder::<String, String>(clock)
    .memory()
    .serialize()
    .fallback(remote)
    .build();

impl<K, V, CT> CacheBuilder<K, V, CT>

where K: Clone + Hash + Eq + Send + Sync + 'static, V: Clone + Send + Sync + 'static, CT: CacheTier<K, V> + Send + Sync + 'static,

pub fn transform<KT, VT>( self, key_encoder: impl Encoder<K, KT> + 'static, value_codec: impl Codec<V, VT> + 'static, ) -> TransformBuilder<K, V, KT, VT, Self>

where KT: Clone + Hash + Eq + Send + Sync + 'static, VT: Clone + Send + Sync + 'static,

Applies a generic type transform boundary.

The codecs convert FROM user types TO storage types:

• key_encoder: K -> KT (one-directional)
• value_codec: V <-> VT (bidirectional)

Subsequent .fallback() tiers must work with KT, VT.

Trait Implementations

impl<K, V, CT> CacheTierBuilder<K, V> for CacheBuilder<K, V, CT>

where K: Clone + Hash + Eq + Send + Sync + 'static, V: Clone + Send + Sync + 'static, CT: CacheTier<K, V> + Send + Sync + 'static,

impl<K: Debug, V: Debug, CT: Debug> Debug for CacheBuilder<K, V, CT>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.