Struct CachekitIOBuilder 

pub struct CachekitIOBuilder { /* private fields */ }

Builder for CachekitIO.

Implementations

impl CachekitIOBuilder

pub fn api_key(self, key: impl Into<String>) -> Self

Set the API key (required).

pub fn api_url(self, url: impl Into<String>) -> Self

Override the API base URL (default: https://api.cachekit.io).

pub fn allow_custom_host(self, allow: bool) -> Self

Allow non-standard hostnames (e.g. custom proxies). Private IPs are still blocked.

pub fn metrics_provider(self, provider: MetricsProvider) -> Self

Override the source of the X-CacheKit-* telemetry headers.

Not needed for normal use: CacheKitBuilder::build attaches the client’s own live counters to any backend without one. Set this only to report numbers from somewhere else; it takes precedence.

pub fn read_timeout(self, timeout: Duration) -> Self

Per-attempt timeout for every request but a write: get, exists, health, the TTL calls and the lock calls (default 5 s, the protocol’s CACHEKIT_TIMEOUT). It runs from send through the last byte of the response body and surfaces as BackendErrorKind::Timeout. A new connection’s DNS, TCP and TLS count against it, and never take more than 5 s whatever the budget.

The budget is per attempt. When the reliability stack wraps this backend through CacheKitBuilder::reliability, each retry gets a fresh budget, so with the default 3 attempts one read can take about three budgets plus backoff before it errors. Each operation that ends in a timeout counts as one failure toward opening the circuit breaker, which a tokio::time::timeout around the call does not: a cancelled call records no outcome. (CacheKit::io builds its own backend with the default budgets and also caps all attempts of a read at 5 s; a backend passed to CacheKitBuilder::backend gets no such cap.)

build rejects Duration::ZERO with CachekitError::Config.

pub fn write_timeout(self, timeout: Duration) -> Self

Per-attempt timeout for a write, set or delete (default 10 s, twice the read budget: a write carries the payload, and the service commits it before it answers). Otherwise as read_timeout: it covers the whole request, applies per attempt under the reliability stack, and counts toward the circuit breaker.

build rejects Duration::ZERO with CachekitError::Config.

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

Consume the builder and construct a CachekitIO.

Errors

Returns an error if:

• api_key was not set, or holds bytes an HTTP header cannot carry (a control character such as a newline).
• the resolved URL scheme is not https, or the URL carries a query or a fragment.
• the URL carries credentials, or its hostname is not permitted (see validate_cachekitio_url).
• the read or write timeout is zero.

Trait Implementations

impl Default for CachekitIOBuilder

fn default() -> Self

Returns the “default value” for a type.