@astilba/cache 0.0.0-stage → 0.1.0

package/dist/adapters/react-router/index.d.ts

@@ -0,0 +1,92 @@
+import { Ct as TelemetrySink, O as RequestContext, _t as SinkErrorHook, t as Cache, x as L3Budget, yt as TELEMETRY_EVENTS } from "../../cache-YWn0VZpn.js";
+import { MiddlewareFunction, RouterContext } from "react-router";
+//#region src/adapters/react-router/middleware.d.ts
+/**
+ * The RR-v8 middleware argument object (the first parameter RR passes a `MiddlewareFunction`:
+ * `{ request, url, params, context }`, `context` being the request's `RouterContextProvider`).
+ * Re-exported off `MiddlewareFunction` so the `request` derivation option below is typed without
+ * naming react-router's private `DataFunctionArgs`.
+ */
+type CacheMiddlewareArgs = Parameters<MiddlewareFunction>[0];
+/** The single telemetry event a shared-cache-INELIGIBLE response emits — exactly
+ * one per response, naming the reason CLASS in its `reason` field and nothing else. No tag names
+ * ride the payload: which dependency did it is a question for `explain()`, and an operator
+ * watching this counter only needs to see THAT a route stopped being CDN-cacheable. */
+declare const L3_INELIGIBLE: typeof TELEMETRY_EVENTS.l3_ineligible;
+/**
+ * The shared-cache header budget: 16 KB aggregate, ~1,000 tags. (The 1,024-char cap is a
+ * purge-API limit, not a header one — header tags carry no per-tag cap.) Overridable per
+ * middleware via `CacheMiddlewareOptions.l3Budget`.
+ */
+declare const L3_BUDGET_DEFAULT: L3Budget;
+/**
+ * `cacheMiddleware` configuration. `cache` is the already-built instance the middleware provides
+ * into the request lifecycle (a `createWorkersCache(...)` / `createCache(...)` result). `request`
+ * is the OPTIONAL principal derivation: it maps the RR request to the identity fields the kernel
+ * reads (`userId`/`tenant`) — the app owns that mapping because identity is app-domain.
+ * Omit it and the request carries no derivable principal (the shared `pub` class, 4).
+ *
+ * `waitUntil` is the Workers `ExecutionContext.waitUntil` the poll tick rides on — pass
+ * `context.cloudflare.ctx.waitUntil` (RR's Cloudflare load context) or `waitUntil` from
+ * `cloudflare:workers`, bound. It is OPTIONAL and never load-bearing for correctness: without it the
+ * tick still fires (unawaited, best-effort) and simply is not kept alive past the response. It is
+ * never awaited on the request path either way — the tick races the loaders, it does not gate them.
+ *
+ * `telemetry` receives the driver's swallowed-tick counter (`poll_tick_failed`) and the single
+ * `l3_ineligible` event a demoted response emits. Every delivery to it goes through
+ * `safeEmit`, so a throwing/rejecting sink is swallowed; `onSinkError` is the OPTIONAL injectable
+ * hook `safeEmit` calls when it swallows such a failure — a sink for reporting the reporter.
+ *
+ * `l3Budget` overrides the header budget (`L3_BUDGET_DEFAULT`).
+ */
+interface CacheMiddlewareOptions {
+  readonly cache: Cache;
+  readonly request?: (args: CacheMiddlewareArgs) => RequestContext;
+  readonly waitUntil?: (promise: Promise<unknown>) => void;
+  readonly telemetry?: TelemetrySink;
+  readonly onSinkError?: SinkErrorHook;
+  readonly l3Budget?: L3Budget;
+}
+/**
+ * The `RouterContext<Cache>` key the middleware writes the cache under. A loader/action reads the
+ * request's cache with `context.get(cacheContext)`. Created with no default value, so a `get` in a
+ * request the middleware never ran on throws (an honest misconfiguration signal, not a silent miss).
+ */
+declare const cacheContext: RouterContext<Cache>;
+/**
+ * The current request's principal-bearing `RequestContext`, or `undefined` outside a middleware
+ * frame. Pass it straight through to `getOrSet`'s `request` option so the kernel derives the
+ * request's scope: `cache.getOrSet({ key, request: currentRequest(), factory })`.
+ */
+declare function currentRequest(): RequestContext | undefined;
+/**
+ * Build the RR-v8 root middleware. Always-on in v8 (the `unstable_`/`v8_middleware` flag
+ * was removed at 8.0.0): register the returned function in a route module's `middleware` array. It
+ * provides the cache into `context`, opens the request + collector frames, fires the replication
+ * poll tick (unawaited), `await`s `next()`, commits the collector, and applies the
+ * header algorithm.
+ */
+declare function cacheMiddleware(options: CacheMiddlewareOptions): MiddlewareFunction;
+//#endregion
+//#region src/adapters/react-router/poll-driver.d.ts
+/**
+ * Minimum ms between two piggybacked ticks on ONE cache instance. Set to the ladder's fastest rung
+ * (~1s): ticking faster can never make the poller act sooner (every path it drives is gated by its
+ * own due-time), so anything below this is pure waste under load.
+ */
+declare const TICK_MIN_INTERVAL_MS = 1000;
+/**
+ * The counter a swallowed tick failure increments. The tick runs OUT-OF-BAND from the response,
+ * so its failure must never surface to the caller — but a silently failing replication poll is
+ * exactly the kind of degradation an operator has to be able to see, so the swallow is paired with
+ * this event. Deliberately payload-free apart from the error's NAME (a code, never free-form detail
+ * or a key/tag reference), so a plain sink can be pointed at it safely.
+ *
+ * NOTE: `registry_degraded` / `state_stale` — the richer telemetry names this event may
+ * eventually be folded into — are now ENROLLED in the const-union catalog (`TELEMETRY_EVENTS`) as
+ * RESERVED members, but their emit condition is unruled: `poll_tick_failed` keeps emitting as-is.
+ * (FOR FABLE: whether to enrich/rename this counter into a degraded-mode signal is an open question.)
+ */
+declare const POLL_TICK_FAILED: typeof TELEMETRY_EVENTS.poll_tick_failed;
+//#endregion
+export { type CacheMiddlewareArgs, type CacheMiddlewareOptions, L3_BUDGET_DEFAULT, L3_INELIGIBLE, POLL_TICK_FAILED, TICK_MIN_INTERVAL_MS, cacheContext, cacheMiddleware, currentRequest };

package/dist/adapters/react-router/index.js

@@ -0,0 +1,272 @@
+import { a as replicationPollerOf, i as managedDependenciesOf, m as safeEmit, n as bindRenderCollector, o as resolveCacheIdentity, p as TELEMETRY_EVENTS } from "../../cache-Z4cJzPmm.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createContext } from "react-router";
+//#region src/adapters/react-router/poll-driver.ts
+/**
+* Minimum ms between two piggybacked ticks on ONE cache instance. Set to the ladder's fastest rung
+* (~1s): ticking faster can never make the poller act sooner (every path it drives is gated by its
+* own due-time), so anything below this is pure waste under load.
+*/
+const TICK_MIN_INTERVAL_MS = 1e3;
+/**
+* The counter a swallowed tick failure increments. The tick runs OUT-OF-BAND from the response,
+* so its failure must never surface to the caller — but a silently failing replication poll is
+* exactly the kind of degradation an operator has to be able to see, so the swallow is paired with
+* this event. Deliberately payload-free apart from the error's NAME (a code, never free-form detail
+* or a key/tag reference), so a plain sink can be pointed at it safely.
+*
+* NOTE: `registry_degraded` / `state_stale` — the richer telemetry names this event may
+* eventually be folded into — are now ENROLLED in the const-union catalog (`TELEMETRY_EVENTS`) as
+* RESERVED members, but their emit condition is unruled: `poll_tick_failed` keeps emitting as-is.
+* (FOR FABLE: whether to enrich/rename this counter into a degraded-mode signal is an open question.)
+*/
+const POLL_TICK_FAILED = TELEMETRY_EVENTS.poll_tick_failed;
+/** Last piggybacked tick per cache instance — the staleness gate's cursor. Per-isolate by nature
+* (an isolate holds one `Cache`), and keyed by the instance so two caches in one isolate never
+* starve each other's ticks.
+*
+* Keyed by RESOLVED identity (the third instance-keyed seam, and the one that does not live beside
+* the other two). A facade and the instance it fronts drive the SAME poller, so they must share the
+* SAME gate: two gates over one poller would let an app holding both objects tick it twice per
+* window, which is exactly the hammering the gate exists to stop. */
+const lastTickMs = /* @__PURE__ */ new WeakMap();
+/**
+* THE SWALLOW WRAP (adapter-side; the guard itself now lives in the shared `safeEmit`).
+* `ctx.waitUntil(tick())` on a rejecting promise surfaces as an unhandled rejection in the request's
+* lifecycle — a failing L2 read would then be able to reach the response of a request that never
+* needed that read. So the tick is wrapped: catch → count → swallow. Adapter code by ruling, not
+* kernel: the kernel's `resync` is entitled to reject, and the driver that chose to run it
+* out-of-band is what owes the caller its silence.
+*
+* The returned promise NEVER rejects — and the guarantee is AIRTIGHT over the whole failure surface,
+* INCLUDING the reporting channel itself: the telemetry emit is routed through `safeEmit`, so
+* neither a throwing sink nor a rejecting `async` sink can turn the swallow into an escape, and the
+* injected `onSinkError` hook observes a swallowed sink failure. (The default `waitUntil` drops
+* the promise on the floor; a rejection here would therefore become an unhandled rejection —
+* process-fatal on the Node/RR lane, an uncaught request error on workerd. A background freshness
+* probe must never be able to kill a user's request.)
+*/
+async function runTick(poller, nowMs, telemetry, onSinkError) {
+	try {
+		await poller.onPollTick(nowMs);
+	} catch (error) {
+		safeEmit(telemetry, {
+			error: error instanceof Error ? error.name : "unknown",
+			type: POLL_TICK_FAILED
+		}, onSinkError);
+	}
+}
+/**
+* Fire one replication poll tick for `cache` IF the last one is stale (see `TICK_MIN_INTERVAL_MS`).
+*
+* Returns the in-flight tick — hand it straight to `ctx.waitUntil` so it outlives the response — or
+* `undefined` when nothing is due (the gate held, or the cache is registry-absent and has no reader
+* to drive). The returned promise NEVER rejects: a store/resync failure inside the tick is caught,
+* counted through `telemetry` (`poll_tick_failed`), and swallowed, because a background freshness
+* probe has no business failing a user's response. The `telemetry` sink is NOT trusted to keep that
+* promise: it is app code on the failure path, so a sink that throws — or an `async` sink that
+* rejects — is neutralized too, and floats nothing.
+*/
+function tickIfStale(cache, nowMs, telemetry, onSinkError) {
+	const poller = replicationPollerOf(cache);
+	if (poller === void 0) return;
+	const gateKey = resolveCacheIdentity(cache);
+	const last = lastTickMs.get(gateKey);
+	if (last !== void 0 && nowMs - last < 1e3) return;
+	lastTickMs.set(gateKey, nowMs);
+	return runTick(poller, nowMs, telemetry, onSinkError);
+}
+//#endregion
+//#region src/adapters/react-router/middleware.ts
+/** The single telemetry event a shared-cache-INELIGIBLE response emits — exactly
+* one per response, naming the reason CLASS in its `reason` field and nothing else. No tag names
+* ride the payload: which dependency did it is a question for `explain()`, and an operator
+* watching this counter only needs to see THAT a route stopped being CDN-cacheable. */
+const L3_INELIGIBLE = TELEMETRY_EVENTS.l3_ineligible;
+/**
+* The shared-cache header budget: 16 KB aggregate, ~1,000 tags. (The 1,024-char cap is a
+* purge-API limit, not a header one — header tags carry no per-tag cap.) Overridable per
+* middleware via `CacheMiddlewareOptions.l3Budget`.
+*/
+const L3_BUDGET_DEFAULT = {
+	maxBytes: 16384,
+	maxTags: 1e3
+};
+/**
+* The reason CLASS a telemetry consumer sees, mapped from the kernel's `L3Ineligibility` union.
+* TWO VOCABULARIES, ONE MAPPING POINT — deliberately: the kernel's union is kebab (its own existing
+* convention, `late-tag`), while the event vocabulary is snake (`poll_tick_failed`,
+* `singleflight_option_mismatch`), and the design fixes `scope_unreadable` as the literal class name. This
+* function is the ONLY place the two meet; nothing downstream re-spells either.
+*/
+const REASON_CLASS = {
+	budget: "budget",
+	"late-tag": "late_tag",
+	scope: "scope",
+	"scope-unreadable": "scope_unreadable"
+};
+/** The two response headers this adapter governs. `Cache-Control` carries the shared-cache
+* posture; `Cache-Tag` is the CDN purge handle keyed off the render's dependency tags. */
+const CACHE_CONTROL = "Cache-Control";
+const CACHE_TAG = "Cache-Tag";
+/** The one directive the adapter ever WRITES to `Cache-Control`. It never writes
+* `public` or an `s-maxage` — opting into shared caching is the application's call, and the
+* adapter's job is to emit the purge tags when that is safe and to demote when it is not. */
+const PRIVATE = "private";
+/**
+* The `RouterContext<Cache>` key the middleware writes the cache under. A loader/action reads the
+* request's cache with `context.get(cacheContext)`. Created with no default value, so a `get` in a
+* request the middleware never ran on throws (an honest misconfiguration signal, not a silent miss).
+*/
+const cacheContext = createContext();
+/** The empty principal-bearing frame used when no `request` derivation is configured — a request
+* with no adapter-visible identity: `derivePrincipal` finds none ⇒ the `pub` class. */
+const EMPTY_REQUEST_CONTEXT = Object.freeze({});
+const requestFrame = new AsyncLocalStorage();
+const collectorFrame = new AsyncLocalStorage();
+/**
+* The current request's principal-bearing `RequestContext`, or `undefined` outside a middleware
+* frame. Pass it straight through to `getOrSet`'s `request` option so the kernel derives the
+* request's scope: `cache.getOrSet({ key, request: currentRequest(), factory })`.
+*/
+function currentRequest() {
+	return requestFrame.getStore();
+}
+/** The `waitUntil` used when the app configures none: the tick still runs, it is simply not held
+* alive past the response (best-effort, and safe — the driver's promise never rejects). */
+function floatingWaitUntil(promise) {}
+/** Nothing to write — the app's headers stand exactly as authored. */
+const NO_EDIT = Object.freeze({});
+/**
+* Decide the posture for the response, given the render's emission and how many
+* dependencies that render consumed (`managed` — hits, fills, and explicit `dependsOn`
+* declarations, read off the kernel's in-package seam; it is deliberately NOT a field of the
+* spec-verbatim public `L3Emission`, which stays exactly the shape names).
+*
+* THREE postures, in precedence order:
+*
+*   1. NO MANAGED DEPENDENCY (the jurisdiction floor). The render consumed nothing this library
+*      manages, so the adapter asserts nothing: it fills in `Cache-Control: private` ONLY where the
+*      application set no cache header at all, and it leaves an app-set `Cache-Tag` alone. A
+*      default-fill, never an override — the adapter has observed nothing that licenses an opinion.
+*      This is also what separates the floor from an ELIGIBLE render that happens to emit no tag:
+*      the emission alone cannot tell those apart, and they get different postures.
+*
+*   2. INELIGIBLE (scope-poisoned, or late-tag/budget). `Cache-Control: private` is FORCED — it
+*      overwrites whatever the application set, because the application's own header is what has to
+*      lose here: the whole point of the branch is a route that asked to be publicly cached while
+*      its render read per-principal content. Any `Cache-Tag` is DELETED, including one the adapter
+*      never assembled: removing it, rather than declining to add one, is what the branch is for —
+*      a downstream cache parses the header off the wire whether or not it stores the response.
+*
+*   3. ELIGIBLE. The adapter's own assembled `Cache-Tag` replaces whatever was there — DEDUPLICATED
+*      here, at the join. One entry read by several loaders in a render reaches the collector once
+*      per consumption, so its tag arrives once per consumption; a header that repeats the same
+*      purge handle buys nothing and costs bytes. The dedup lives HERE and NOT in the collector on
+* purpose: `commitHeaders`'s BUDGET counts every occurrence (that is the measure invariant
+*      13 pins — collapsing duplicates there would make an over-budget tag list come out eligible),
+*      and emitting fewer bytes than were measured is always safe, while measuring fewer bytes than
+*      are emitted is not. The adapter does NOT fabricate public caching — no `public`, no
+*      `s-maxage`, ever. The application opts into shared caching with its own `Cache-Control`; the
+*      adapter's job is to emit the purge tags when that is safe and to demote when it is not. So
+*      the safe `private` default still fills in where the app wrote no cache header.
+*/
+function decidePosture(emission, managed, appSetCacheControl) {
+	const safeDefault = appSetCacheControl ? NO_EDIT : { cacheControl: PRIVATE };
+	if (managed === 0) return safeDefault;
+	if (!emission.eligible) return {
+		cacheControl: PRIVATE,
+		cacheTag: null
+	};
+	const emitted = [...new Set(emission.cacheTags)];
+	return {
+		...safeDefault,
+		cacheTag: emitted.length > 0 ? emitted.join(",") : null
+	};
+}
+/** Write one decided posture onto a mutable `Headers`. Throws iff the guard is immutable — which is
+* exactly the signal `applyHeaders` acts on, and never a partial write: an immutable guard rejects
+* the FIRST mutation, so either the whole posture lands or none of it does. */
+function writePosture(headers, posture) {
+	if (posture.cacheControl !== void 0) headers.set(CACHE_CONTROL, posture.cacheControl);
+	if (posture.cacheTag === null) headers.delete(CACHE_TAG);
+	else if (posture.cacheTag !== void 0) headers.set(CACHE_TAG, posture.cacheTag);
+}
+/**
+* Rebuild `response` with a MUTABLE header guard and the posture written onto it, preserving status,
+* statusText, body, and every header the original carried (the `Response(body, response)` init form
+* copies all three). `undefined` when the platform refuses to reconstruct the response at all — see
+* `applyHeaders` for why that residue is safe.
+*/
+function rebuiltWithPosture(response, posture) {
+	try {
+		const rebuilt = new Response(response.body, response);
+		writePosture(rebuilt.headers, posture);
+		return rebuilt;
+	} catch {
+		return;
+	}
+}
+/**
+* Apply the posture to the response and return the response to send.
+*
+* NOT ALL RESPONSES ARE WRITABLE. A `Response` obtained from `Response.redirect(...)`, from a
+* `fetch()` passthrough, or from `caches.match(...)` carries an IMMUTABLE header guard: every
+* `set`/`delete` on it throws `TypeError`. A middleware that mutates headers unconditionally
+* therefore rejects its own promise on such a response and turns it into a 500 — a route that
+* merely redirects would break. So the write is attempted, and on refusal the SAME decided posture
+* is written onto a rebuilt copy (status, statusText, body and headers all preserved) which is
+* returned in the original's place.
+*
+* THE RESIDUE, and why it is safe: a response the platform will not let us reconstruct either
+* (`Response.error()` and the other sub-200 network-error forms) is returned untouched. Such a
+* response carries NO readable or writable headers at all — there is no app-set `Cache-Control` to
+* override and no `Cache-Tag` for a shared cache to read off it — so declining to write a posture
+* onto it withholds nothing and leaks nothing. The one thing that must never happen — a throw out
+* of the middleware — cannot.
+*
+* The telemetry event an ineligible response owes is emitted exactly once, off the
+* DECISION, so it is independent of which of the three write paths the response takes: one event per
+* response, naming the reason CLASS, carrying no tag names.
+*/
+function applyHeaders(response, emission, telemetry, onSinkError) {
+	const managed = managedDependenciesOf(emission);
+	const posture = decidePosture(emission, managed, response.headers.has(CACHE_CONTROL));
+	if (managed > 0 && !emission.eligible && emission.ineligibleReason !== void 0) safeEmit(telemetry, {
+		reason: REASON_CLASS[emission.ineligibleReason],
+		type: L3_INELIGIBLE
+	}, onSinkError);
+	if (posture === NO_EDIT) return response;
+	try {
+		writePosture(response.headers, posture);
+		return response;
+	} catch {}
+	return rebuiltWithPosture(response, posture) ?? response;
+}
+/**
+* Build the RR-v8 root middleware. Always-on in v8 (the `unstable_`/`v8_middleware` flag
+* was removed at 8.0.0): register the returned function in a route module's `middleware` array. It
+* provides the cache into `context`, opens the request + collector frames, fires the replication
+* poll tick (unawaited), `await`s `next()`, commits the collector, and applies the
+* header algorithm.
+*/
+function cacheMiddleware(options) {
+	const { cache, l3Budget = L3_BUDGET_DEFAULT, onSinkError, request: deriveRequest, telemetry, waitUntil = floatingWaitUntil } = options;
+	bindRenderCollector(cache, () => collectorFrame.getStore());
+	return async (args, next) => {
+		const requestContext = deriveRequest?.(args) ?? EMPTY_REQUEST_CONTEXT;
+		const collector = cache.collect();
+		return await requestFrame.run(requestContext, async () => {
+			args.context.set(cacheContext, cache);
+			const tick = tickIfStale(cache, Date.now(), telemetry, onSinkError);
+			if (tick !== void 0) waitUntil(tick);
+			return await collectorFrame.run(collector, async () => {
+				const response = await next();
+				if (response instanceof Response) return applyHeaders(response, collector.commitHeaders(l3Budget), telemetry, onSinkError);
+				return response;
+			});
+		});
+	};
+}
+//#endregion
+export { L3_BUDGET_DEFAULT, L3_INELIGIBLE, POLL_TICK_FAILED, TICK_MIN_INTERVAL_MS, cacheContext, cacheMiddleware, currentRequest };