Skip to content
AstilbaCache
Sponsor

Runtime architecture

See how the portable Astilba Cache kernel composes storage, coordination, time, and encoding capabilities.

Astilba Cache keeps its behavior in a portable kernel and receives runtime capabilities through typed contracts. The kernel owns keys, scopes, tier order, decode safety, fill coordination, and invalidation decisions. Your runtime supplies storage, coordination, time, randomness, and any custom encoding.

This is an advanced integration page. For application-level definitions and a smaller starting point, begin with Core concepts or the preview walkthrough.

Capabilities at the boundary

Section titled “Capabilities at the boundary”
Capability What Cache uses it for Current requirement
Clock and Rng Injected time and randomness keep the kernel portable and deterministic in tests. Required by createCache(); a future runtime preset should normally supply them.
Store Key/value I/O for local L1, shared L2, and the replication mirror. L2 is currently required whenever a factory must run. L1 is optional.
Registry The authoritative record of soft, hard, and namespace invalidation. Required by expire(), delete(), and clear().
Bus The live delivery path for ordered invalidation events. Participates in coordinated read validation when Registry is also configured. L2 separately supports fills and mirror replay.
Codec Value encoding and a wire identity checked before decode. Optional when the built-in JSON round trip is sufficient.
Lock Cross-isolate exclusion and write arbitration. Optional and only used when a driver is supplied and the call opts in.
Cdn A future edge-purge boundary. Declared but not wired in the current kernel.

These contracts keep the correctness rules independent of a storage vendor. They do not make every driver combination equivalent: coordinated invalidation needs a complete coordination path.

Follow one read or fill

Section titled “Follow one read or fill”
  1. Cache resolves the namespace, scope, and user key into one canonical storage key.
  2. It checks L1 before L2, verifies the stored codec identity, and reconstructs the entry.
  3. When coordinated invalidation is configured, it decides whether its tag knowledge is sufficient for the requested consistency level.
  4. On a miss, compatible callers share one in-isolate factory execution.
  5. Before write-back, Cache checks for a conflicting hard invalidation, then writes only to tiers allowed by the resolved scope.

See Reading and filling for return metadata, singleflight compatibility, codec changes, and fill failures. See How Cache works for the invalidation and recovery path around the same operation.

Compose the current source preview

Section titled “Compose the current source preview”
Configuration Current behavior
clock + rng + l2 Reads and fills through the portable kernel without coordinated invalidation.
Add l1 Adds an isolate-local read tier and retains principal-derived, L1-only values.
Add registry Enables the purge methods. Reads do not build the coordinated invalidation path without Bus.
Add registry + bus together Enables coordinated validation and live delivery. With L2, a suspect reader can also replay durable delta batches.
Add lock Allows opted-in calls to coordinate work across isolates. No production Lock driver is exported.
Add a custom codec Changes the wire format and identity. Accepted older identities must still be decodable by that codec.

Supplying Bus without Registry does not build the invalidation reader. Registry without Bus can still accept purge commands, but it is not a coordinated read configuration.

Keep runtime integrations outside the kernel

Section titled “Keep runtime integrations outside the kernel”

The repository exercises Cloudflare-backed storage, coordination, and recovery internally, but those modules are not supported package entry points. There is no public deployment bundle or framework adapter yet, and the internal worker is a test host rather than an application template.

Section titled “Related”