Struct CacheKitBuilder 

pub struct CacheKitBuilder { /* private fields */ }

Fluent builder for CacheKit.

Implementations

impl CacheKitBuilder

pub fn backend(self, backend: SharedBackend) -> Self

Set the storage backend.

pub fn default_ttl(self, ttl: Duration) -> Self

Override the default TTL (used when no per-call TTL is specified).

pub fn namespace(self, ns: impl Into<String>) -> Self

Set a namespace prefix. All keys will be stored as {namespace}:{key}.

pub fn max_payload_bytes(self, limit: usize) -> Self

Set the maximum accepted payload size in bytes.

pub fn l1_capacity(self, capacity: usize) -> Self

Set the L1 cache capacity (max entries).

pub fn no_l1(self) -> Self

Disable the L1 cache entirely.

pub fn swr_enabled(self, enabled: bool) -> Self

Enable or disable L1 stale-while-revalidate (default: enabled, matching the Python and TypeScript SDKs).

With SWR on, an L1 hit older than swr_threshold_ratio of its TTL is still served immediately, and the #[cachekit] macro schedules at most one background refresh (deduplicated on the CacheKit::single_flight locks, in-process and — on lock-capable backends — across processes). A refresh that finds either lock held, or whose lock call fails, stands down instead of waiting, and the stale value keeps being served. A hard-expired entry is never served: it falls through to a normal blocking miss.

Native targets only: this knob does not exist on wasm32, under the unsync feature, or without l1 — calling it there is a compile error rather than a silent no-op.

pub fn swr_threshold_ratio(self, ratio: f64) -> Self

Set the SWR freshness threshold as a fraction of each L1 entry’s TTL (default: 0.5, matching the Python and TypeScript SDKs).

An entry is fresh until it has lived ratio × TTL (±10% jitter, drawn once when the entry is inserted, to de-synchronise refreshes across processes), then stale — served immediately with a background refresh — until hard expiry. Mirrors cachekit-py’s swr_threshold_ratio semantics (elapsed-lifetime fraction). Must be in (0.0, 1.0]; validated at Self::build.

pub fn reliability(self, config: ReliabilityConfig) -> Self

Wrap the backend in the reliability stack (retry with exponential backoff + jitter, circuit breaker, backpressure) — see crate::reliability.

Enabled by default with production settings by the production, secure, and io intent presets; off for minimal and for manually-built clients. To opt a preset out, pass ReliabilityConfig::disabled() — a disabled config applies no wrapping at all.

pub fn encryption_from_bytes( self, master_key: &[u8], tenant_id: &str, ) -> Result<Self, CachekitError>

Configure encryption from raw master key bytes and tenant ID.

The master key must be exactly 32 raw bytes; anything else is a CachekitError::Config. Hex-encoded keys go to Self::encryption (or Self::encryption_with_previous to rotate) — their ASCII bytes are 64 bytes long and rejected here. Keys are derived per-tenant via HKDF-SHA256.

The built client encrypts every value read and write, not only those through the secure_cache() handle; see Encryption. Calling any encryption method again replaces the earlier configuration.

Without the encryption cargo feature this method, and every other builder encryption method, returns CachekitError::Config: a build that cannot encrypt never accepts a key.

pub fn encryption_from_bytes_with_previous( self, master_key: &[u8], previous_keys: &[&[u8]], tenant_id: &str, ) -> Result<Self, CachekitError>

Configure encryption with decrypt-only previous master keys for key rotation.

Writes encrypt under master_key; reads attempt it first, then each key in previous_keys sequentially (attempt order = slice order). At most 3 previous keys; supplying more is a config error, never truncated. See crate::encryption::EncryptionLayer::with_previous_keys.

Every key, current and previous, must be exactly 32 raw bytes. For hex keys, use the hex counterpart, Self::encryption_with_previous.

Encrypts every value read and write, as for Self::encryption_from_bytes.

pub fn encryption( self, hex_key: &str, tenant_id: &str, ) -> Result<Self, CachekitError>

Configure encryption from a hex-encoded master key string.

Hex-decodes with the same decoder as CacheKit::from_env and the secure preset. The key must decode to at least 32 bytes; use exactly 32 (64 hex chars), the only length every SDK accepts.

Encrypts every value read and write, as for Self::encryption_from_bytes.

pub fn encryption_with_previous( self, hex_key: &str, previous_hex_keys: &[&str], tenant_id: &str, ) -> Result<Self, CachekitError>

Configure encryption from hex-encoded keys, with decrypt-only previous master keys for key rotation.

The hex counterpart of Self::encryption_from_bytes_with_previous. Every key, current and previous, is decoded as for Self::encryption and must decode to at least 32 bytes, so a key longer than 32 bytes that Self::encryption accepted can be listed as a previous key under the tenant it was written for (the env variables always derive for tenant "default"). Use exactly 32 bytes (64 hex chars) for new keys, the only length every SDK accepts.

Writes encrypt under hex_key; reads attempt it first, then each key in previous_hex_keys sequentially (attempt order = slice order). At most 3 previous keys, and the current key must not be among them; either violation is a CachekitError::Config, never truncated.

let cache = cachekit::CacheKit::builder()
    .backend(backend)
    .encryption_with_previous(k2_hex, &[k1_hex], "tenant-a")?
    .build()?;

Encrypts every value read and write, as for Self::encryption_from_bytes.

pub fn encryption_from_env(self) -> Result<Self, CachekitError>

Configure encryption from the environment: the hex key in CACHEKIT_MASTER_KEY, plus any decrypt-only rotation keys in CACHEKIT_PREVIOUS_MASTER_KEYS, for tenant "default".

The explicit call that turns a CACHEKIT_MASTER_KEY into encryption: no constructor, CacheKit::from_env included, encrypts because the variable is set. Keys are decoded and validated as for Self::encryption_with_previous and CacheKit::from_env.

let cache = cachekit::CacheKit::from_env()?
    .encryption_from_env()?
    .build()?;

Encrypts every value read and write, as for Self::encryption_from_bytes.

Errors

CachekitError::Config when CACHEKIT_MASTER_KEY is unset, empty, not UTF-8, not hex or shorter than 32 bytes, or when CACHEKIT_PREVIOUS_MASTER_KEYS is malformed: asked to encrypt, the builder never falls back to plaintext.

pub fn no_encryption(self) -> Self

State that this client does not encrypt, even with CACHEKIT_MASTER_KEY set: the explicit opt-out of protocol spec/intent-presets.md § Encryption Activation, rule 3.

No client encrypts without an encryption call, so this changes nothing on its own. It answers the transitional check on a builder from CacheKit::from_env that saw CACHEKIT_MASTER_KEY, and it records the intent at the call site. Combined with any encryption call, or the secure preset, Self::build returns CachekitError::Config: an opt-out never quietly undoes one.

pub fn build(self) -> Result<CacheKit, CachekitError>

Finalise and build the CacheKit client.

Returns an error if no backend was provided, if Self::no_encryption was combined with an encryption call, or if the builder came from CacheKit::from_env with CACHEKIT_MASTER_KEY set and states no encryption intent.

Trait Implementations

impl Default for CacheKitBuilder

fn default() -> Self

Returns the “default value” for a type.