@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.141

package/src/cache/shell-snapshot.ts

@@ -0,0 +1,368 @@
+/**
+ * Capture data snapshot: recording + seeding stores for PPR shell parity.
+ *
+ * The scar tissue this fixes: a PPR HIT serves frozen prelude bytes, then a
+ * FULL FRESH Flight render for hydration. Any shell-baked (non-hole) content
+ * that drifts between capture time and hit time — a cache() segment with a
+ * shorter ttl than the shell, a tag-invalidated item — makes the fresh payload
+ * disagree with the prelude, so React throws a hydration text mismatch and
+ * regenerates the tree client-side (wiping the FOUC theme class, flashing
+ * content). See docs/design/ppr-shell-resume.md.
+ *
+ * The fix (Next.js resume-data-cache analog, adapted to Rango's cache rings):
+ * the CAPTURE render records every cache-store read-hit and write it performed
+ * (the {@link RecordingShellStore}); the record rides inside the ShellCacheEntry
+ * as its `snapshot`; on a HIT the tail render reads through a
+ * {@link SeededShellStore} overlay that serves those recorded values AS FRESH,
+ * so the shell region reproduces byte-identically while everything NOT recorded
+ * (the holes — masked loaders were never executed at capture, so their reads
+ * were never recorded) stays live.
+ *
+ * The invariant, verbatim: the snapshot is exactly the set of cache-store reads
+ * the capture render performed; replaying them on a HIT reproduces the shell
+ * content byte-identically; everything not recorded stays live.
+ */
+
+import type {
+  SegmentCacheStore,
+  CacheGetResult,
+  CacheItemResult,
+  CacheItemOptions,
+  CachedEntryData,
+  ShellCacheEntry,
+  ShellSnapshotRecord,
+  ShellSnapshotItemValue,
+  ShellSnapshotResponseValue,
+} from "./types.js";
+import { bufferToBase64, base64ToBuffer } from "./cf/cf-base64.js";
+import { isPerClientSignalHeader } from "../browser/cookie-name.js";
+
+/** Compose the last-write-wins map key. NUL (`\u0000`) cannot appear in a cache key. */
+function recordKey(family: ShellSnapshotRecord["family"], key: string): string {
+  return `${family}\u0000${key}`;
+}
+
+/** Serialize a Response to the snapshot's stored shape (base64 body). */
+async function serializeResponse(
+  response: Response,
+): Promise<ShellSnapshotResponseValue> {
+  const body = await response.clone().arrayBuffer();
+  const headers: [string, string][] = [];
+  response.headers.forEach((value, name) => {
+    // Mirror putResponse: per-client signal headers never enter a shared entry.
+    if (isPerClientSignalHeader(name)) return;
+    headers.push([name, value]);
+  });
+  return { status: response.status, headers, body: bufferToBase64(body) };
+}
+
+/** Rebuild a live Response from a snapshot's stored response shape. */
+function deserializeResponse(value: ShellSnapshotResponseValue): Response {
+  return new Response(base64ToBuffer(value.body), {
+    status: value.status,
+    headers: new Headers(value.headers),
+  });
+}
+
+/**
+ * A store wrapper the CAPTURE render reads through. Every call passes through to
+ * the underlying store unchanged; for the item/segment/response families it also
+ * RECORDS, last-write-wins per (family, key):
+ *   - read-hits (get/getItem/getResponse returning non-null) — the value that
+ *     fed the shell,
+ *   - writes (set/setItem/putResponse) — the value a MISS computed and baked.
+ * The shell family (getShell/putShell) is never recorded (the snapshot rides
+ * inside a shell entry). Reads that MISS are not recorded (a miss produced no
+ * shell content; if the render then computed and wrote, that write is recorded).
+ *
+ * Deferred writes: cache writes run under waitUntil (fire-and-forget on Node,
+ * executionContext on workerd), so their setItem/set calls — hence their records
+ * — may land after the shell has quiesced. The capture collects those write
+ * promises via {@link trackWrite} and awaits them ({@link settleWrites}) before
+ * draining, so a MISS-at-capture value is still pinned.
+ */
+export class RecordingShellStore<
+  TEnv = unknown,
+> implements SegmentCacheStore<TEnv> {
+  private readonly records = new Map<string, ShellSnapshotRecord>();
+  private readonly writes: Promise<unknown>[] = [];
+
+  constructor(private readonly inner: SegmentCacheStore<TEnv>) {}
+
+  get defaults(): SegmentCacheStore<TEnv>["defaults"] {
+    return this.inner.defaults;
+  }
+  get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"] {
+    return this.inner.keyGenerator;
+  }
+
+  private record(
+    family: ShellSnapshotRecord["family"],
+    key: string,
+    value: ShellSnapshotRecord["value"],
+  ): void {
+    this.records.set(recordKey(family, key), { family, key, value });
+  }
+
+  /** Track a deferred cache-write promise so the capture can await it pre-drain. */
+  trackWrite(p: Promise<unknown>): void {
+    this.writes.push(p);
+  }
+
+  /**
+   * Await the tracked deferred writes so their records are present before drain.
+   * Drains ITERATIVELY: a write task can schedule a NESTED write (the ring-3
+   * cacheRoute path schedules its actual store.set in a second waitUntil while the
+   * first is running), so each awaited batch may enqueue more. Loop until the
+   * queue empties or the deadline passes. Bounded: a pathologically slow write
+   * must never stall the capture task, so a key that does not settle in time is
+   * left unpinned (it drifts, the pre-snapshot behavior) rather than hanging.
+   */
+  async settleWrites(timeoutMs: number): Promise<void> {
+    const deadline = Date.now() + timeoutMs;
+    while (this.writes.length > 0) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) return;
+      // Take the current batch; new writes scheduled while awaiting accumulate in
+      // this.writes and are drained on the next iteration.
+      const batch = this.writes.splice(0);
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const guard = new Promise<void>((resolve) => {
+        timer = setTimeout(resolve, remaining);
+        (timer as { unref?: () => void }).unref?.();
+      });
+      await Promise.race([Promise.allSettled(batch).then(() => {}), guard]);
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  /** The recorded snapshot (last-write-wins per family+key), or undefined if empty. */
+  drainSnapshot(): ShellSnapshotRecord[] | undefined {
+    return this.records.size > 0 ? [...this.records.values()] : undefined;
+  }
+
+  async get(key: string): Promise<CacheGetResult | null> {
+    const result = await this.inner.get(key);
+    if (result) this.record("segment", key, result.data);
+    return result;
+  }
+
+  async set(
+    key: string,
+    data: CachedEntryData,
+    ttl: number,
+    swr?: number,
+  ): Promise<void> {
+    this.record("segment", key, data);
+    return this.inner.set(key, data, ttl, swr);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.inner.delete(key);
+  }
+
+  async clear(): Promise<void> {
+    return this.inner.clear?.();
+  }
+
+  async getResponse(
+    key: string,
+  ): Promise<{ response: Response; shouldRevalidate: boolean } | null> {
+    if (!this.inner.getResponse) return null;
+    const result = await this.inner.getResponse(key);
+    if (result)
+      this.record("response", key, await serializeResponse(result.response));
+    return result;
+  }
+
+  async putResponse(
+    key: string,
+    response: Response,
+    ttl: number,
+    swr?: number,
+    tags?: string[],
+  ): Promise<void> {
+    if (!this.inner.putResponse) return;
+    this.record("response", key, await serializeResponse(response));
+    return this.inner.putResponse(key, response, ttl, swr, tags);
+  }
+
+  async getItem(key: string): Promise<CacheItemResult | null> {
+    if (!this.inner.getItem) return null;
+    const result = await this.inner.getItem(key);
+    if (result) {
+      const value: ShellSnapshotItemValue = {
+        value: result.value,
+        handles: result.handles,
+        tags: result.tags,
+      };
+      this.record("item", key, value);
+    }
+    return result;
+  }
+
+  async setItem(
+    key: string,
+    value: string,
+    options?: CacheItemOptions,
+  ): Promise<void> {
+    if (!this.inner.setItem) return;
+    const stored: ShellSnapshotItemValue = {
+      value,
+      handles: options?.handles,
+      tags: options?.tags,
+    };
+    this.record("item", key, stored);
+    return this.inner.setItem(key, value, options);
+  }
+
+  async getShell(
+    key: string,
+  ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
+    return this.inner.getShell ? this.inner.getShell(key) : null;
+  }
+
+  async putShell(
+    key: string,
+    entry: ShellCacheEntry,
+    ttlSeconds?: number,
+    swrSeconds?: number,
+    tags?: string[],
+  ): Promise<void> {
+    return this.inner.putShell?.(key, entry, ttlSeconds, swrSeconds, tags);
+  }
+
+  async invalidateTags(tags: string[]): Promise<void> {
+    return this.inner.invalidateTags?.(tags);
+  }
+}
+
+/** True iff `store` is a RecordingShellStore (duck-typed across module copies). */
+export function getRecordingStore<TEnv>(
+  store: SegmentCacheStore<TEnv> | undefined,
+): RecordingShellStore<TEnv> | undefined {
+  return store instanceof RecordingShellStore ? store : undefined;
+}
+
+/**
+ * A read-through overlay the HIT tail render reads through. For a key present in
+ * the snapshot it serves the recorded value AS FRESH (shouldRevalidate: false —
+ * a pinned key must NOT kick SWR background revalidation) so the tail's payload
+ * matches the frozen prelude. Every other read falls through to the real store
+ * (the holes — masked loaders were never recorded — stay live). ALL writes pass
+ * through unchanged: a live hole's loader may legitimately write. The shell
+ * family always passes through.
+ */
+export class SeededShellStore<
+  TEnv = unknown,
+> implements SegmentCacheStore<TEnv> {
+  private readonly items = new Map<string, ShellSnapshotItemValue>();
+  private readonly segments = new Map<string, CachedEntryData>();
+  private readonly responses = new Map<string, ShellSnapshotResponseValue>();
+
+  constructor(
+    private readonly inner: SegmentCacheStore<TEnv>,
+    snapshot: ShellSnapshotRecord[],
+  ) {
+    for (const rec of snapshot) {
+      if (rec.family === "item") {
+        this.items.set(rec.key, rec.value as ShellSnapshotItemValue);
+      } else if (rec.family === "segment") {
+        this.segments.set(rec.key, rec.value as CachedEntryData);
+      } else {
+        this.responses.set(rec.key, rec.value as ShellSnapshotResponseValue);
+      }
+    }
+  }
+
+  get defaults(): SegmentCacheStore<TEnv>["defaults"] {
+    return this.inner.defaults;
+  }
+  get keyGenerator(): SegmentCacheStore<TEnv>["keyGenerator"] {
+    return this.inner.keyGenerator;
+  }
+
+  async get(key: string): Promise<CacheGetResult | null> {
+    const seeded = this.segments.get(key);
+    if (seeded) return { data: seeded, shouldRevalidate: false };
+    return this.inner.get(key);
+  }
+
+  async set(
+    key: string,
+    data: CachedEntryData,
+    ttl: number,
+    swr?: number,
+  ): Promise<void> {
+    return this.inner.set(key, data, ttl, swr);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    return this.inner.delete(key);
+  }
+
+  async clear(): Promise<void> {
+    return this.inner.clear?.();
+  }
+
+  async getResponse(
+    key: string,
+  ): Promise<{ response: Response; shouldRevalidate: boolean } | null> {
+    const seeded = this.responses.get(key);
+    if (seeded) {
+      return { response: deserializeResponse(seeded), shouldRevalidate: false };
+    }
+    return this.inner.getResponse ? this.inner.getResponse(key) : null;
+  }
+
+  async putResponse(
+    key: string,
+    response: Response,
+    ttl: number,
+    swr?: number,
+    tags?: string[],
+  ): Promise<void> {
+    return this.inner.putResponse?.(key, response, ttl, swr, tags);
+  }
+
+  async getItem(key: string): Promise<CacheItemResult | null> {
+    const seeded = this.items.get(key);
+    if (seeded) {
+      return {
+        value: seeded.value,
+        handles: seeded.handles,
+        tags: seeded.tags,
+        shouldRevalidate: false,
+      };
+    }
+    return this.inner.getItem ? this.inner.getItem(key) : null;
+  }
+
+  async setItem(
+    key: string,
+    value: string,
+    options?: CacheItemOptions,
+  ): Promise<void> {
+    return this.inner.setItem?.(key, value, options);
+  }
+
+  async getShell(
+    key: string,
+  ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
+    return this.inner.getShell ? this.inner.getShell(key) : null;
+  }
+
+  async putShell(
+    key: string,
+    entry: ShellCacheEntry,
+    ttlSeconds?: number,
+    swrSeconds?: number,
+    tags?: string[],
+  ): Promise<void> {
+    return this.inner.putShell?.(key, entry, ttlSeconds, swrSeconds, tags);
+  }
+
+  async invalidateTags(tags: string[]): Promise<void> {
+    return this.inner.invalidateTags?.(tags);
+  }
+}

package/src/cache/tag-invalidation.ts

@@ -0,0 +1,230 @@
+/**
+ * Cache Tag Invalidation API
+ *
+ * Two on-demand invalidation verbs, mirroring the distinction popularized by
+ * Next.js so consumers can pick the right consistency model:
+ *
+ * - updateTag(...tags): read-your-own-writes. Awaitable - resolves only after
+ *   in-process invalidation across every configured store completes. Use in a
+ *   Server Action and `await` it before the action re-renders, so the action's
+ *   own response reflects the mutation.
+ *
+ * - revalidateTag(...tags): fire-and-forget via waitUntil - the response is not
+ *   blocked. Use in Route Handlers / webhooks. NOTE: both verbs hard-purge; the
+ *   only difference is awaitability. revalidateTag does NOT serve stale content -
+ *   the next read after the invalidation lands is a hard miss that re-renders.
+ *   (The name mirrors Next.js, where it is SWR; here it is background-purge.)
+ *
+ * Both fan out across the app-level store (ctx._cacheStore) and every explicit
+ * per-scope store from cache({ store }) registered for this handler
+ * (ctx._explicitTaggedStores), calling the store-level invalidateTags()
+ * primitive for each tag. A single configured store (the common case) owns its
+ * own tag index and distributed invalidation - there is no separate
+ * tag-invalidation store.
+ */
+
+import { _getRequestContext } from "../server/request-context.js";
+import { reportingAsync } from "./cache-error.js";
+import { normalizeTags } from "./cache-tag.js";
+import type { SegmentCacheStore } from "./types.js";
+
+/**
+ * Collect every store that may hold entries tagged for this request's handler:
+ * the app-level store plus all explicit per-scope stores (deduplicated). Splits
+ * them into tag-capable (implement invalidateTags()) and not, so callers can
+ * warn about configured stores whose tagged entries will NOT be invalidated.
+ *
+ * `hasContext` reports whether an ALS request context existed at all. Without one
+ * (e.g. a queue consumer or cron job calling updateTag/revalidateTag) no stores
+ * are reachable, and the empty-capable case is a missing-context problem, not a
+ * store-config problem - callers branch on this to warn about the right cause.
+ */
+function collectStores(): {
+  capable: SegmentCacheStore[];
+  incapable: number;
+  hasContext: boolean;
+} {
+  const ctx = _getRequestContext();
+  const stores = new Set<SegmentCacheStore>();
+  if (ctx?._cacheStore) stores.add(ctx._cacheStore);
+  if (ctx?._explicitTaggedStores) {
+    for (const store of ctx._explicitTaggedStores) stores.add(store);
+  }
+  const capable: SegmentCacheStore[] = [];
+  let incapable = 0;
+  for (const store of stores) {
+    if (typeof store.invalidateTags === "function") capable.push(store);
+    else incapable++;
+  }
+  return { capable, incapable, hasContext: ctx != null };
+}
+
+/**
+ * Production-visible warning. A misconfigured store silently dropping
+ * invalidations is a data-correctness footgun, so this surfaces in every
+ * environment (not dev-only).
+ */
+function warnNoTagStore(fn: string, tags: string[]): void {
+  console.warn(
+    `[${fn}] No tag-capable cache store is configured; tags ` +
+      `[${tags.join(", ")}] were not invalidated. The configured store must ` +
+      `implement invalidateTags() (the built-in MemorySegmentCacheStore and ` +
+      `CFCacheStore do).`,
+  );
+}
+
+/**
+ * Production-visible warning for the no-request-context case. Distinct from
+ * warnNoTagStore: the stores are not unreachable because they are misconfigured,
+ * but because there is no ALS request context to reach them through (e.g. a queue
+ * consumer or scheduled job). Naming the real cause keeps consumers from chasing
+ * a store-config red herring.
+ */
+function warnNoRequestContext(fn: string, tags: string[]): void {
+  console.warn(
+    `[${fn}] Called outside a request context (e.g. from a queue consumer or ` +
+      `scheduled job); no cache stores are reachable and tags ` +
+      `[${tags.join(", ")}] were not invalidated. Invoke it within a request ` +
+      `(Server Action or route handler).`,
+  );
+}
+
+/**
+ * Production-visible warning for mixed-store configs: at least one configured
+ * store does not support tag invalidation, so its tagged entries (if any) are
+ * left stale even though other stores were invalidated.
+ */
+function warnPartialTagStore(fn: string, incapable: number): void {
+  console.warn(
+    `[${fn}] ${incapable} configured cache store(s) do not implement ` +
+      `invalidateTags(); their tagged entries were NOT invalidated. Use a ` +
+      `tag-capable store (e.g. MemorySegmentCacheStore / CFCacheStore) for any ` +
+      `cache({ store }) boundary whose entries you invalidate by tag.`,
+  );
+}
+
+async function invalidateAcross(
+  stores: SegmentCacheStore[],
+  tags: string[],
+): Promise<void> {
+  // One invalidateTags(tags) call per store: the store receives the whole tag
+  // batch so it can do a single CDN purge request rather than one per tag.
+  //
+  // allSettled, not all: a store's invalidateTags() can reject (e.g. CFCacheStore
+  // surfaces a failed durable KV marker write). With Promise.all, the first
+  // rejection would short-circuit and the other stores' outcomes would go
+  // unobserved. Attempt every store, then surface a combined error so an awaited
+  // updateTag() still rejects (read-your-own-writes honesty) without masking the
+  // stores that did succeed.
+  const results = await Promise.allSettled(
+    stores.map((store) => store.invalidateTags!(tags)),
+  );
+  const errors = results
+    .filter((r): r is PromiseRejectedResult => r.status === "rejected")
+    .map((r) => r.reason);
+  if (errors.length > 0) {
+    const err = new Error(
+      `[tag invalidation] ${errors.length}/${stores.length} store(s) failed to ` +
+        `invalidate tags [${tags.join(", ")}]; their entries may still serve ` +
+        `stale data. Retry the invalidation.`,
+    );
+    (err as Error & { cause?: unknown }).cause = errors[0];
+    throw err;
+  }
+}
+
+/**
+ * Immediately expire every cache entry tagged with any of `tags`, resolving
+ * once in-process invalidation across all configured stores completes.
+ *
+ * Read-your-own-writes: because the returned promise resolves before you return
+ * from a Server Action, awaiting it guarantees the action's own re-render (and
+ * any subsequent read) sees fresh data.
+ *
+ * @example
+ * ```typescript
+ * async function updateProduct(formData: FormData) {
+ *   "use server";
+ *   await db.updateProduct(formData);
+ *   await updateTag("products");   // next render is fresh
+ * }
+ * ```
+ */
+export async function updateTag(...tags: string[]): Promise<void> {
+  const valid = normalizeTags(tags);
+  if (valid.length === 0) return;
+
+  const { capable, incapable, hasContext } = collectStores();
+  if (capable.length === 0) {
+    if (hasContext) warnNoTagStore("updateTag", valid);
+    else warnNoRequestContext("updateTag", valid);
+    return;
+  }
+  if (incapable > 0) warnPartialTagStore("updateTag", incapable);
+
+  await invalidateAcross(capable, valid);
+}
+
+/**
+ * Invalidate every cache entry tagged with any of `tags` in the background,
+ * without blocking the current response (fire-and-forget via waitUntil).
+ *
+ * This is NOT stale-while-revalidate: like updateTag() it hard-purges, so the
+ * next read after the invalidation lands is a miss that re-renders fresh. The
+ * only difference from updateTag() is awaitability - revalidateTag() defers the
+ * purge off the response path and is not awaited.
+ *
+ * Use in Route Handlers / webhooks. For read-your-own-writes inside a Server
+ * Action, use updateTag() instead so the action's own response is fresh.
+ *
+ * Fire-and-forget: because this returns void and runs in the background, a
+ * failed durable marker write (e.g. a transient KV outage) is NOT surfaced to
+ * the caller. It IS reported - logged loudly and routed through the router's
+ * `onError` callback (phase `cache`, `metadata.category === "cache-invalidate"`)
+ * via reportingAsync - so the failure is observable in telemetry even though it
+ * cannot be awaited. If you need the invalidation to be CONFIRMED (and to retry
+ * on failure), use `await updateTag()` instead, which rejects when a store's
+ * durable write fails.
+ *
+ * @example
+ * ```typescript
+ * // route handler invoked by an external webhook
+ * export async function POST() {
+ *   "use server";
+ *   revalidateTag("products");
+ *   return new Response("ok");
+ * }
+ * ```
+ */
+export function revalidateTag(...tags: string[]): void {
+  const valid = normalizeTags(tags);
+  if (valid.length === 0) return;
+
+  const { capable, incapable, hasContext } = collectStores();
+  if (capable.length === 0) {
+    if (hasContext) warnNoTagStore("revalidateTag", valid);
+    else warnNoRequestContext("revalidateTag", valid);
+    return;
+  }
+  if (incapable > 0) warnPartialTagStore("revalidateTag", incapable);
+
+  const ctx = _getRequestContext();
+  // reportingAsync never rejects: it catches a failed durable write and routes
+  // it through reportCacheError (loud log + onError). This is the only place a
+  // revalidateTag failure can be observed, since it is not awaitable. Pass ctx
+  // explicitly - the run executes in a detached waitUntil where the ALS context
+  // is gone, so onError fires only if we hand it the captured context.
+  const run = () =>
+    reportingAsync(
+      () => invalidateAcross(capable, valid),
+      "cache-invalidate",
+      "[revalidateTag] background invalidation",
+      ctx,
+    );
+  if (ctx?.waitUntil) {
+    ctx.waitUntil(run);
+  } else {
+    // No request context (e.g. called outside ALS): best-effort background run.
+    void run();
+  }
+}