Skip to content
AstilbaCache
Sponsor

Driver implementations

See which Cache drivers and runtime adapters exist in current source and which production boundaries remain open.

Astilba Cache keeps its semantics behind small contracts, then implements platform I/O at adapter boundaries. This page separates an implemented source driver from a released, supported integration.

Application developers can begin with Cache fundamentals. Runtime authors and production-readiness reviewers should use this page together with Implementation status.

Understand the driver model

Section titled “Understand the driver model”
Contract Role
Store Key/value I/O for local L1, shared L2, and replication-mirror objects. An optional ReadKind lets a driver choose different read-cache policy for a mutable pointer and immutable deltas or snapshots.
Registry The authoritative record used for live tag checks and soft or hard mutations. Its regId scopes recovery objects.
Bus Delivers ordered frames plus reset, hello, gap, and lost signals. The kernel—not the transport—validates continuity and records channel state.
Lock Optional cross-isolate exclusion with a monotone fence token.
Codec Value encoding plus a wire identity checked before decode.
Cdn Planned edge-purge queue boundary; not wired today.
Clock, Rng Explicit time and randomness for portable, deterministic kernel behavior.

The base Store shape is small:

store.ts
interface Store {
  get(key: string, readKind?: ReadKind): Promise<StoreValue | undefined>
  set(
    key: string,
    value: string,
    options?: StoreWriteOptions,
  ): Promise<void>
  delete(key: string): Promise<void>
}

Classified writes use the public structural StoreWriteError shape. throttled and unavailable failures may leave a successful fill at durable: false; too_large is permanent and propagates rather than truncating the value.

Serving-path reads also recognize structural throttled and unavailable failures, but that read-error shape is intentionally internal rather than a root export. A classified failure emits store_read_suppressed and acts as a tier miss; an unclassified error propagates unchanged. In explain(), the same classified failure becomes read-failed when no other tier finds the entry, preserving the distinction between “nothing stored” and “Store did not answer.”

Check each implementation

Section titled “Check each implementation”
Surface Current source status What is covered
Portable kernel and contracts Implemented Deterministic invariant, scenario, unit, and conformance lanes cover the public read, fill, invalidation, scope, codec, recovery, and failure behavior.
memory() Implemented root export Per-instance LRU Store with maxEntries and UTF-8 maxBytes limits. With an injected Clock it also honors Store-level expirationTtl.
cloudflareKV() Unreleased source preview KV-backed Store with metadata round trips, a 25 MiB value ceiling, read and write classification, 60-second minimum write residency, and intent-specific mirror read-cache hints.
Coordinator Unreleased source preview SQLite-backed Durable Object host for Registry RPC, a replayable command journal, coalesced flush alarms, mirror deltas and snapshots, and WebSocket fan-out.
doRegistry() Unreleased source preview Thin Registry RPC client scoped to the named Coordinator. It accepts either a stub or a per-use stub thunk and passes the Registry contract under workerd.
doBus() Unreleased source preview Mechanism-only WebSocket Bus client with wire validation, Registry identity checks, and close reporting.
redialingDoBus() Unreleased source preview Schedules DO Bus reconnection with injected jitter and exponential backoff capped at 300 seconds; a due tick(nowMs) performs the redial without a platform timer.
Replication reader Implemented kernel path Replays contiguous deltas, escalates persistent holes to a pointer-blessed snapshot, replays the tail, and remains fail closed on corrupt or unfillable chains.
Replication poller Implemented internal seam Runs baseline pointer observation, bounded recovery retries, snapshot escalation, and failure backoff from externally supplied ticks.
createWorkersCache() Unreleased source preview Composes the Workers Clock/Rng, memory L1, KV L2, lazily minted named Coordinator Registry handles, tick-redialed Bus, and an unawaited read-triggered recovery carrier. Construction performs no I/O.
React Router middleware Unreleased source preview Supplies Cache through typed Router context, carries request identity, starts request-entry poll ticks with optional waitUntil adoption, collects served dependencies, emits eligible Cache-Tag headers, and demotes unsafe responses.
Local chaos demo Source-only evidence app Runs the real Workers composition against local KV and Coordinator bindings. Demo-owned wrappers inject three binding failures and the UI compares observed behavior with documented permissions without asserting an SLO.
Composed demo boot witness Required source CI lane Builds and boots the emitted demo Worker on local workerd with its real Coordinator and KV bindings. Bounded polling requires a healthy channel to reach established and, after arming the fault, a fresh scene-owned reader to report never-established plus bus_dial_failed. Probe failure remains distinct from a channel verdict. This is a composition witness, not a deployed measurement or kernel-semantics test.
Redis, production Lock, and CDN drivers Not implemented Contracts exist, but no package subpaths or production implementations are present.

“Unreleased source preview” means the symbol is present in the package export map and publish configuration in the reviewed private source snapshot. It does not mean consumers can inspect or install it. npm still has no @astilba/cache package.

Understand Cloudflare-specific behavior

Section titled “Understand Cloudflare-specific behavior”

The Cloudflare path uses one named Coordinator identity for the Durable Object address, Registry scope, and Cache namespace. The KV binding used by createWorkersCache() must expose the same namespace that the Coordinator receives as REGISTRY_KV; otherwise the reader and writer see different recovery mirrors.

The KV Store uses different read-cache hints for recovery objects:

  • mutable pointer reads use the platform’s 30-second minimum, reduced from 60 seconds in January 2026;
  • immutable deltas and snapshots use 24 hours;
  • ordinary value reads do not supply a hint and inherit the platform default.

These read hints are distinct from physical write residency. The Coordinator writes immutable delta batches with a 48-hour expirationTtl, snapshots with seven days, and its mutable pointer with no expiration. The KV driver floors any supplied write residency to Cloudflare’s 60-second minimum.

See Cloudflare’s reduced minimum cacheTtl announcement for the read-cache change and KV write API for write residency, value size, and rate limits.

The Coordinator can refresh an idle pointer through REGISTRY_HEARTBEAT_MS. This is disabled unless the deployment sets the variable. The Workers factory independently defaults its reader heartbeat interval to 30 seconds, so matching the Coordinator value is an operator action, not an automatic handshake.

Workers deployments must use a compatibility date of 2024-09-23 or later and enable nodejs_compat. The root package uses node:crypto, and that flag also supplies the AsyncLocalStorage support needed by React Router. nodejs_als alone is insufficient.

See Cloudflare Workers for the binding and lifecycle example.

Know the recovery scheduling model

Section titled “Know the recovery scheduling model”

The kernel poller contains no timer. A runtime hands it ticks so portable code never reads ambient time or schedules work.

The Workers factory fires an unawaited tick from getOrSet() or getOrSetEntry(), at most once per second per Cache instance. That carrier first performs any due Bus redial, then offers the same instant to the poller. The React Router adapter additionally fires a tick at request start and can pass it to waitUntil. The shared poller applies its longer baseline cadence and bounded retry schedule, so multiple offers do not imply duplicate I/O. Failed tick work is swallowed and can emit poll_tick_failed telemetry.

A raw runtime that uses neither the Workers factory nor React Router still has reactive recovery: a suspect read performs one bounded fast resync attempt. It does not receive proactive baseline polls unless its embedding drives the internal tick seam.

Keep the release boundary visible

Section titled “Keep the release boundary visible”

The Workers path still needs work before a production release:

  • elapsed TTL, grace, and negative-entry expiry—entry age is measured, but it does not enforce timing policy;
  • Coordinator journal checkpointing and truncation;
  • a CDN purge queue and completion promises that track real acceptance—the response adapter now emits safe tags, but does not deliver purges;
  • a production Lock driver and the deferred Redis/Valkey path;
  • deployed consistency, propagation, caching, and production-threshold measurements behind the local chaos demo;
  • an npm release, compatibility policy, deployment guide, and upgrade process.

The integration Worker and React Router fixture prove runtime wiring and build compatibility. The required built-demo witness adds one local composition check for healthy and refused Bus establishment. The chaos demo remains a local evidence app, not a production template or an SLO. Do not import deep adapter files. Use only the root, ./cloudflare, and ./react-router entry points documented here.

Section titled “Related”