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, and gap signals. The kernel—not the transport—validates continuity.
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 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.

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() Public source preview KV-backed Store with metadata round trips, a 25 MiB value ceiling, write classification, 60-second minimum write residency, and intent-specific mirror read-cache hints.
Coordinator Public 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() Public source preview Thin Registry RPC client scoped to the named Coordinator. It passes the Registry contract under workerd.
doBus() Public source preview Mechanism-only WebSocket Bus client with wire validation, Registry identity checks, and close reporting.
redialingDoBus() Public source preview Reconnects the DO Bus with injected jitter and exponential backoff capped at 300 seconds.
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() Public source preview Composes the Workers Clock/Rng, memory L1, KV L2, named Coordinator Registry, and redialing Bus.
React Router middleware Public source preview Supplies Cache through typed Router context, carries request identity, fires request-piggyback poll ticks, collects served dependencies, emits eligible Cache-Tag headers, and demotes unsafe responses.
Redis, production Lock, and CDN drivers Not implemented Contracts exist, but no package subpaths or production implementations are present.

“Public source preview” means the symbol is present in the package export map and publish configuration, not that consumers can 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.

See Cloudflare Workers for the binding and migration 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 React Router adapter fires a tick at request start, at most once per second per Cache instance, and does not await it on the response path. The poller itself applies the longer baseline cadence and bounded retry schedule. Failed tick work is swallowed and can emit poll_tick_failed telemetry.

A runtime that does not use the React Router adapter still has reactive recovery: a suspect read performs one bounded fast resync attempt. It does not receive proactive baseline polls unless another driver calls 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, age, and negative-entry expiry;
  • 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;
  • the chaos demo and deployed consistency measurements;
  • an npm release, compatibility policy, deployment guide, and upgrade process.

The integration Worker and React Router fixture prove runtime wiring and build compatibility; they are not application templates. Do not import deep adapter files. Use only the root, ./cloudflare, and ./react-router entry points documented here.

Section titled “Related”