Struct CacheKit 

pub struct CacheKit { /* private fields */ }

Cache client with optional L1 in-process cache layer.

Clone is cheap and shares everything: backend, L1 cache, single-flight state, and encryption layer. Clones exist so 'static background work (e.g. the SWR refresh spawned by #[cachekit]) can hold the client without borrowing it.

Implementations

impl CacheKit

pub fn builder() -> CacheKitBuilder

Create a new builder.

pub fn from_env() -> Result<CacheKitBuilder, CachekitError>

Build from environment variables via crate::config::CachekitConfig::from_env.

Creates a crate::backend::cachekitio::CachekitIO backend from the config. Requires the cachekitio feature.

pub async fn get<T: DeserializeOwned>( &self, key: &str, ) -> Result<Option<T>, CachekitError>

Retrieve and deserialize a value stored under key.

Returns None if the key does not exist. Checks L1 cache before hitting the backend.

pub async fn interop_get<T: DeserializeOwned>( &self, key: &str, ) -> Result<Option<T>, CachekitError>

Retrieve and deserialize an interop-mode value stored under key.

Identical to Self::get except the payload is decoded with crate::interop::deserialize, which consumes exactly one MessagePack document and rejects trailing bytes (interop/v1 spec MUST). A Python-SDK-internal CK frame is rejected with a specific diagnostic instead of silently decoding as the integer 67.

Use with keys from crate::interop::interop_key on a client without a namespace prefix. There is no interop-specific write method: Self::set already writes plain MessagePack (no ByteStorage envelope), which is the interop value format.

Errors

Returns CachekitError::Config if the client was built with CacheKitBuilder::namespace (or CACHEKIT_NAMESPACE): the prefix would rewrite the storage key to {prefix}:{interop_key}, which no other SDK computes — every cross-SDK entry would silently miss. Interop keys carry their own namespace segment; failing loudly here beats a 100% miss rate that looks like a cold cache.

pub async fn interop_get_swr<T: DeserializeOwned>( &self, key: &str, ) -> Result<SwrRead<T>, CachekitError>

Retrieve and deserialize an interop-mode value with SWR classification.

Identical to Self::interop_get except an L1 hit is classified against the client’s stale-while-revalidate freshness window:

• SwrRead::Fresh — L1 hit within swr_threshold_ratio of the entry’s TTL (±10% jitter), or any L2 hit. Use directly.
• SwrRead::Stale — L1 hit past the threshold but before hard expiry: the value is returned without touching the backend or origin, and the caller should schedule exactly one background refresh (dedup via Self::single_flight — this is what the #[cachekit] macro generates). The accompanying SwrToken makes completion conditional, so a newer set/delete always wins.
• SwrRead::Miss — nothing usable anywhere: normal blocking miss.

A hard-expired L1 entry is a SwrRead::Miss, never Stale — moka drops entries at their TTL, so SWR cannot serve past hard expiry.

With SWR disabled (CacheKitBuilder::swr_enabled(false)), without the l1 feature, on wasm32, or under unsync, this behaves exactly like Self::interop_get: hits are Fresh, Stale is never produced.

Errors

Same as Self::interop_get (including the namespaced-client rejection).

pub async fn set<T: Serialize>( &self, key: &str, value: &T, ) -> Result<(), CachekitError>

Serialize and store value under key using the client’s default TTL.

pub async fn set_with_ttl<T: Serialize>( &self, key: &str, value: &T, ttl: Duration, ) -> Result<(), CachekitError>

Serialize and store value under key with an explicit ttl.

Returns CachekitError::Config if ttl is less than 1 second.

pub async fn delete(&self, key: &str) -> Result<bool, CachekitError>

Delete key and return true if it existed.

Invalidates the L1 entry regardless of the backend result.

pub async fn exists(&self, key: &str) -> Result<bool, CachekitError>

Return true if key exists without fetching the value.

pub async fn single_flight(&self, key: &str) -> SingleFlight

Begin a cold-miss single-flight for key (see crate::flight).

Call after a cache miss, before computing the value. Concurrent in-process fills of the same key are collapsed to one; with the reliability feature and a lock-capable backend (CachekitIO, Redis), fills are also suppressed across processes via a distributed fill lock. The #[cachekit] macro does this automatically.

The key is namespaced like every cache operation but not validated — this call is infallible; an invalid key simply fails later at the actual cache operation.

pub fn secure(&self) -> Result<SecureCache<'_>, CachekitError>

Return a SecureCache handle that encrypts all values before storage.

L1 stores ciphertext (not plaintext) to preserve the zero-knowledge property across all cache layers.

Errors

Returns CachekitError::Config if no encryption layer is configured. Configure encryption via CacheKitBuilder::encryption or CacheKitBuilder::encryption_from_bytes.

impl CacheKit

pub fn io(api_key: &str) -> Result<CacheKitBuilder, CachekitError>

CachekitIO — managed SaaS cache, zero infrastructure.

• Backend: cachekit.io HTTP API
• L1 cache: on (1 000 entries)
• Encryption: no (add via .encryption())
• Reliability: on — retry with backoff + jitter, circuit breaker, backpressure (max 100 concurrent backend ops)
• Default TTL: 3 600 s

Good for: serverless, edge compute, managed caching without Redis.

Errors

Returns CachekitError if api_key is empty.

Example

let cache = cachekit::CacheKit::io("ck_live_abc123")?
    .namespace("edge")
    .build()?;

Trait Implementations

impl Clone for CacheKit

fn clone(&self) -> CacheKit

Returns a duplicate of the value.

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

Performs copy-assignment from source.