@rangojs/router 0.0.0-experimental.e9c0b2f2 → 0.0.0-experimental.ea9f40f2

package/src/cache/shell-snapshot.ts

@@ -0,0 +1,417 @@
+/**
+ * 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,
+  ShellSnapshotLoaderValue,
+} 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;
+}
+
+/**
+ * Materialize the loader-family seed from a shell snapshot for a HIT's tail
+ * render: Flight-deserialize each recorded (promise-elided) bake-lane
+ * container into a segment-key -> container Map, which serveShellHit assigns
+ * to the tail context's `_shellLoaderSeed` for the resolveLoaderData overlay.
+ * Lives here so every snapshot family is decoded in this module (the
+ * item/segment/response families via {@link SeededShellStore}); the loader
+ * family is not a store read, so it seeds the context instead of a store.
+ *
+ * Deserializations run in parallel; a record that fails to decode is skipped
+ * (that loader drifts — the pre-snapshot behavior — instead of failing the
+ * HIT). Returns undefined when the snapshot carries no loader records, without
+ * touching the Flight codec (kept lazy for cold paths and non-RSC configs).
+ */
+export async function buildShellLoaderSeed(
+  snapshot: ShellSnapshotRecord[],
+): Promise<Map<string, unknown> | undefined> {
+  const loaderRecords: ShellSnapshotRecord[] = [];
+  for (const rec of snapshot) {
+    if (rec.family === "loader") loaderRecords.push(rec);
+  }
+  if (loaderRecords.length === 0) return undefined;
+
+  const { deserializeResult } = await import("./segment-codec.js");
+  const entries = await Promise.all(
+    loaderRecords.map(async (rec): Promise<[string, unknown] | null> => {
+      try {
+        return [
+          rec.key,
+          await deserializeResult(
+            (rec.value as ShellSnapshotLoaderValue).value,
+          ),
+        ];
+      } catch {
+        return null;
+      }
+    }),
+  );
+  const seed = new Map<string, unknown>();
+  for (const entry of entries) {
+    if (entry) seed.set(entry[0], entry[1]);
+  }
+  return seed.size > 0 ? seed : 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 if (rec.family === "response") {
+        this.responses.set(rec.key, rec.value as ShellSnapshotResponseValue);
+      }
+      // "loader" family records are not store reads — serveShellHit seeds them
+      // onto the tail context (_shellLoaderSeed) for the resolveLoaderData
+      // overlay instead.
+    }
+  }
+
+  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/types.ts

@@ -136,6 +136,39 @@ export interface SegmentCacheStore<TEnv = unknown> {
     tags?: string[],
   ): Promise<void>;
 
+  /**
+   * Get a cached PPR shell entry by key.
+   * Returns the stored prelude/postponed pair (see ShellCacheEntry) and whether
+   * it should be revalidated (SWR). Used by the shell-cache middleware to serve
+   * a cached HTML shell and resume fizz for just the live holes.
+   *
+   * Optional: a store that does not implement the shell family disables the
+   * shell-cache middleware (it fails open to the normal HTML render path).
+   */
+  getShell?(
+    key: string,
+  ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null>;
+
+  /**
+   * Store a PPR shell entry with TTL and optional SWR window.
+   * The prelude bytes and postponed state are version- and generation-coupled
+   * and travel together in a single entry (they must never mix across a React
+   * upgrade — the reactVersion field on the entry gates that at read time).
+   * @param key - Cache key
+   * @param entry - The shell prelude/postponed/version/createdAt bundle
+   * @param ttlSeconds - Time-to-live in seconds
+   * @param swrSeconds - Optional stale-while-revalidate window in seconds
+   * @param tags - Optional cache tags for invalidation (participates in
+   *   invalidateTags via the same tag machinery as the item family)
+   */
+  putShell?(
+    key: string,
+    entry: ShellCacheEntry,
+    ttlSeconds?: number,
+    swrSeconds?: number,
+    tags?: string[],
+  ): Promise<void>;
+
   /**
    * Get a cached function result by key.
    * Returns the serialized value, optional handle data, and staleness flag.
@@ -186,6 +219,131 @@ export interface CacheItemResult {
   tags?: string[];
 }
 
+/**
+ * A cached PPR (Partial Pre-rendering) shell entry.
+ *
+ * One entry carries BOTH artifacts a resume needs — the rendered HTML prelude
+ * and React's postponed state — because the pair is version- and
+ * generation-coupled and must never be mixed across a React upgrade or a build
+ * change. The reactVersion and buildVersion fields are the read-time gates that
+ * enforce both halves: isValidShellHit (rsc/shell-serve.ts) treats an entry
+ * whose reactVersion differs from the running React, or whose buildVersion
+ * differs from the running build, as a miss (the postponed blob encodes hole
+ * positions against one exact tree; resuming it against a different React or a
+ * different app build tree-mismatches inside resume(), AFTER the 200 + prelude
+ * are committed — an unrecoverable broken serve).
+ */
+export interface ShellCacheEntry {
+  /** Rendered HTML prelude bytes, base64-encoded (stores are JSON-serializing). */
+  prelude: string;
+  /**
+   * JSON.stringify of React's postponed state, or null when the shell settled
+   * with no holes (the DATA variant — served without a fizz resume).
+   */
+  postponed: string | null;
+  /** React.version captured at prerender time; the read-time invalidation gate. */
+  reactVersion: string;
+  /**
+   * Build version captured at prerender time (the RSC handler's `version` —
+   * the `@rangojs/router:version` build stamp by default, bumped per build and
+   * on dev RSC-module edits). The second read-time gate: a persistent shared
+   * store (KV/runtime-cache) survives deploys, and an app-code change that
+   * keeps the same React version would otherwise leave a stale-build
+   * prelude+postponed live under the same key. Optional only for entries
+   * stored before the field existed — those are treated as a miss and the
+   * recapture re-stamps them (pre-release, no compat shim).
+   */
+  buildVersion?: string;
+  /**
+   * The initialTheme the CAPTURE render was built with (the derived context's
+   * reqCtx.theme). The resume tail must render ThemeProvider with the SAME
+   * initialTheme the frozen prelude was rendered with: React resume requires the
+   * tree above the holes to match the prerendered tree, and initialTheme is
+   * per-request METADATA, not part of the cached segments — a visitor whose
+   * theme differs from the capturer's would otherwise produce a divergent resume
+   * tree (broken stitching/hydration). The visitor's real theme is applied
+   * pre-paint by the FOUC script and re-synced from the cookie post-mount by
+   * ThemeProvider.
+   */
+  initialTheme?: string;
+  /**
+   * The CAPTURE DATA SNAPSHOT: every cache-store read-hit and write the capture
+   * render performed, in stored/serialized form. Replaying these on a HIT (via
+   * the SeededShellStore overlay, for the tail render only) reproduces the
+   * shell's cached content byte-identically, so the freshly rendered hydration
+   * payload matches the frozen prelude even after the underlying cache entries
+   * have drifted (expired, been recomputed, or been tag-invalidated).
+   *
+   * Optional: an entry captured before this field existed simply has no
+   * snapshot and keeps the pre-snapshot behavior (the tail reads live, so any
+   * shell-baked cached value that drifted mismatches the prelude). Recapture
+   * heals it. See docs/design/ppr-shell-resume.md ("the capture data snapshot").
+   */
+  snapshot?: ShellSnapshotRecord[];
+  /** Epoch ms when the shell was captured. */
+  createdAt: number;
+}
+
+/**
+ * The families a shell snapshot pins. The item/segment/response families are
+ * cache-store reads/writes (recorded by RecordingShellStore); the loader family
+ * pins the settled CONTAINER of a bake-lane loader (a loader on an entry with
+ * no renderable loading(), executed during capture — see
+ * docs/design/loader-container-bake.md). Excludes the shell family itself
+ * (getShell/putShell) — the snapshot rides INSIDE a shell entry, so recording
+ * it would be self-referential.
+ */
+export type ShellSnapshotFamily = "item" | "segment" | "response" | "loader";
+
+/**
+ * The stored form of a loader-family snapshot value: the bake-lane loader's
+ * settled container, Flight-serialized AFTER eliding every still-pending nested
+ * promise to a hole marker (the marker paths are holes, not shell material; on
+ * a HIT the overlay re-slots the fresh run's promises there). Flight (not JSON)
+ * so typed values (Date/Map) survive the round trip.
+ */
+export interface ShellSnapshotLoaderValue {
+  /** RSC-serialized elided container (see loader-snapshot.ts). */
+  value: string;
+}
+
+/** A serialized cached Response for the response family of a shell snapshot. */
+export interface ShellSnapshotResponseValue {
+  status: number;
+  /** Client-facing header pairs (per-client signal headers excluded at record). */
+  headers: [string, string][];
+  /** base64-encoded response body (binary-safe, JSON-serializable). */
+  body: string;
+}
+
+/** The stored form of an item-family (use cache / loader cache) snapshot value. */
+export interface ShellSnapshotItemValue {
+  /** RSC-serialized return value. */
+  value: string;
+  /** RSC-encoded handle data, if any. */
+  handles?: string;
+  /** The entry's cache tags. */
+  tags?: string[];
+}
+
+/**
+ * One recorded cache-store read-hit or write from the capture render. `value`
+ * carries the entry in its stored/serialized shape so it round-trips through a
+ * JSON-serializing store (KV, CF, Vercel) with the rest of the ShellCacheEntry:
+ * - `item`    -> {@link ShellSnapshotItemValue}
+ * - `segment` -> {@link CachedEntryData} (already JSON-able)
+ * - `response`-> {@link ShellSnapshotResponseValue}
+ */
+export interface ShellSnapshotRecord {
+  family: ShellSnapshotFamily;
+  key: string;
+  value:
+    | ShellSnapshotItemValue
+    | CachedEntryData
+    | ShellSnapshotResponseValue
+    | ShellSnapshotLoaderValue;
+}
+
 /**
  * Options for setItem() for function-level caching ("use cache").
  */