Crate cachekit 

CacheKit — caching for Rust.

Supports cachekit.io SaaS, Redis, Memcached, local File, and Cloudflare Workers backends. Zero-knowledge encryption via AES-256-GCM with HKDF key derivation.

Getting started: intent presets

The intent presets are the primary entry point — one call that names your use case and returns a pre-configured CacheKitBuilder you can still override before build():

Intent	Backend	L1	Encryption	Auto-reconnect²	Reliability¹	Default TTL
CacheKit::minimal³	Redis	On (no SWR)	No	No	Off	300 s
CacheKit::production³	Redis	On	No	Yes	On	600 s
CacheKit::secure³ ⁵	Redis	On	AES-256-GCM	Yes	On	600 s
io⁴	cachekit.io	On	No	n/a (HTTP)	On	3 600 s

¹ Retry with backoff + jitter, a circuit breaker, and backpressure around backend ops — see reliability. Requires the default-on reliability cargo feature. ² production/secure re-establish a dropped Redis connection with exponential backoff (100 ms → 30 s, retrying indefinitely); minimal is fail-fast (a dropped connection stays dead). Initial connections fail fast for every Redis preset — io opens no connection at construction: an empty API key fails at construction, while an invalid key or unreachable endpoint surfaces at the first request. Auto-reconnect is connection-level repair, distinct from the per-operation reliability stack. ³ Requires the redis cargo feature; secure also needs the default-on encryption feature. ⁴ API key by argument, or from CACHEKIT_API_KEY via io_from_env. Neither reads CACHEKIT_MASTER_KEY. ⁵ Master key as a hex string, secure(url, master_key_hex), or from CACHEKIT_MASTER_KEY via secure_from_env(url) — the same hex decoding either way, so one key value derives the same key bytes in every CacheKit SDK. Use exactly 32 bytes (64 hex chars), the only length every SDK accepts. secure_from_env also reads decrypt-only rotation keys from CACHEKIT_PREVIOUS_MASTER_KEYS, validated as from_env validates them. A missing, non-hex or short key fails at construction, before any Redis I/O; secure never falls back to plaintext.

Which calls encrypt. On a secure client — and on any client built with a builder encryption method, such as io plus .encryption() — every value read and write encrypts: plain get, set, set_with_ttl, interop_get and interop_get_swr behave exactly as the SecureCache handle from cache.secure_cache() does, and L1 holds ciphertext. The handle is optional: it fails on a client without encryption, for code that must never run unencrypted. A build without the encryption feature rejects every builder encryption call with CachekitError::Config.

No other client encrypts. CACHEKIT_MASTER_KEY is a key source, never a switch: after from_env with the variable set, chain .encryption_from_env() to encrypt with it or .no_encryption() for a plaintext client; stating neither is an error at build() (a transitional check, see from_env).

let cache = cachekit::CacheKit::io_from_env()?
    .namespace("myapp")
    .build()?;

cache.set("greeting", &"Hello, world!").await?;
let val: Option<String> = cache.get("greeting").await?;

For full control, drop down to CacheKit::builder or CacheKit::from_env.

Observability

Every client counts its reads: CacheKit::stats answers “is my cache hitting?” (L1 hits / L2 hits / misses), CacheKit::l1_entry_count reports L1 occupancy, and with reliability on, CacheKit::circuit_state reports the breaker. The same counters feed the cachekit.io backends’ X-CacheKit-* telemetry headers automatically. Enable the tracing cargo feature for a debug event per operation on the cachekit target (op, outcome, key_hash — never the key) and breaker transitions on cachekit::reliability — see metrics.

Re-exports

pub use client::CacheKit;

pub use client::CacheKitBuilder;

pub use client::SharedBackend;

pub use client::SwrRead;

pub use client::SwrToken;

pub use config::CachekitConfig;

pub use error::BackendError;

pub use error::BackendErrorKind;

pub use error::CachekitError;

pub use metrics::L1Stats;

pub use client::SecureCache;

pub use encryption::EncryptionLayer;

pub use flight::SingleFlight;

pub use reliability::BackpressureConfig;

pub use reliability::CircuitBreakerConfig;

pub use reliability::CircuitState;

pub use reliability::ReliabilityConfig;

pub use reliability::RetryConfig;

Modules

backend

Pluggable cache backend trait and implementations (CachekitIO, Redis, Memcached, File, Workers).

client

High-level cache client with dual-layer (L1/L2) support.

config

Configuration types and environment variable parsing.

encryption

Client-side AES-256-GCM encryption with HKDF key derivation. Zero-knowledge encryption layer using AES-256-GCM with AAD v0x03 format.

error

Error types for cache operations and backend communication.

flight

Cold-miss single-flight: dedup concurrent fills of the same key. Cold-miss single-flight: dedup concurrent fills of the same key.

interop

Interop mode (interop/v1): cross-SDK cache keys and plain-MessagePack values. Interop mode (interop/v1): language-neutral cache keys and plain-MessagePack values.

l1

In-process L1 cache with per-entry TTL, backed by quick_cache.

metrics

Live hit/miss counters, the SaaS telemetry headers built from them, and (feature tracing) structured events for cache operations. Telemetry: live hit/miss counters, the X-CacheKit-* SaaS telemetry headers built from them, and — behind the tracing feature — structured events for cache operations.

prelude

Convenient glob import for the most common types.

reliability

Reliability tier: retry with backoff + jitter, circuit breaker. Reliability tier: backpressure (bounded backend concurrency), retry with exponential backoff + jitter, and a closed/open/half-open circuit breaker around backend operations.

serializer

Serialization and deserialization of cached values via MessagePack.

session

SDK session tracking (session ID and start timestamp).

url_validator

SSRF-safe URL validation for CachekitIO endpoints.

Attribute Macros

cachekit

Cache the result of an async function under an interop/v1 cache key.