@rangojs/router 0.17.0 → 0.18.0

package/src/cache/shell-snapshot.ts

@@ -1,26 +1,27 @@
 /**
  * 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.
+ * A PPR HIT serves frozen prelude bytes, then a Flight payload for hydration
+ * that must agree with them byte for byte. The handler layer's part of that
+ * payload is the capture's own doc segment record: the capture writes it
+ * first, renders its prelude from it, and every HIT replays it (no handler
+ * runs on a HIT). What still executes on a HIT is the loader layer: live
+ * loaders and promise-carrying bake-lane (`ssr: false`) loaders run, and the
+ * values the bake-lane ones read must match what the capture baked (a
+ * promise-free bake-lane loader is served from its pin and does not run). 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 mechanism (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 records ride 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.
+ * 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.
+ * The invariant, verbatim: the snapshot is the doc record plus the cache-store
+ * reads the capture's loaders performed; replaying them on a HIT reproduces
+ * the shell content byte-identically; everything not recorded stays live.
+ * {@link pruneShellSnapshot} drops the rest.
  */
 
 import type {
@@ -39,6 +40,7 @@ import type {
 import { CACHE_READ_ERROR } from "./types.js";
 import { bufferToBase64, base64ToBuffer } from "./cf/cf-base64.js";
 import { isPerClientSignalHeader } from "../browser/cookie-name.js";
+import { isInsideAnyLoaderScope } from "../server/context.js";
 
 /** Compose the last-write-wins map key. NUL (`\u0000`) cannot appear in a cache key. */
 function recordKey(family: ShellSnapshotRecord["family"], key: string): string {
@@ -83,12 +85,21 @@ function deserializeResponse(value: ShellSnapshotResponseValue): Response {
  * — 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.
+ *
+ * Loader attribution: every item/response access made inside a loader scope
+ * (hit, miss or write) marks its key in {@link loaderKeys}. A loader re-runs
+ * on every HIT, so those records stay pinned when the snapshot is pruned. A
+ * miss counts too: a loader that joins a handler's in-flight "use cache" call
+ * reads the store first (cache-runtime.ts) and finds nothing, and the record
+ * then comes from the handler's write.
  */
 export class RecordingShellStore<
   TEnv = unknown,
 > implements SegmentCacheStore<TEnv> {
   private readonly records = new Map<string, ShellSnapshotRecord>();
   private readonly writes: Promise<unknown>[] = [];
+  /** Record keys ({@link recordKey}) a loader read or wrote during the capture. */
+  readonly loaderKeys: Set<string> = new Set();
 
   constructor(private readonly inner: SegmentCacheStore<TEnv>) {}
 
@@ -110,6 +121,13 @@ export class RecordingShellStore<
     this.records.set(recordKey(family, key), { family, key, value });
   }
 
+  private noteLoaderAccess(
+    family: ShellSnapshotRecord["family"],
+    key: string,
+  ): void {
+    if (isInsideAnyLoaderScope()) this.loaderKeys.add(recordKey(family, key));
+  }
+
   /** Track a deferred cache-write promise so the capture can await it pre-drain. */
   trackWrite(p: Promise<unknown>): void {
     this.writes.push(p);
@@ -134,25 +152,35 @@ export class RecordingShellStore<
    * 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.
+   * must never stall the capture task. Resolves true when every tracked write
+   * settled, false at the deadline (settleCaptureRecord then fails the capture
+   * when the doc record is among the writes still pending).
    */
-  async settleWrites(timeoutMs: number): Promise<void> {
+  async settleWrites(timeoutMs: number): Promise<boolean> {
     const deadline = Date.now() + timeoutMs;
     while (this.writes.length > 0) {
       const remaining = deadline - Date.now();
-      if (remaining <= 0) return;
+      if (remaining <= 0) return false;
       // 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);
+      const guard = new Promise<false>((resolve) => {
+        timer = setTimeout(() => resolve(false), remaining);
         (timer as { unref?: () => void }).unref?.();
       });
-      await Promise.race([Promise.allSettled(batch).then(() => {}), guard]);
+      const settled = await Promise.race([
+        Promise.allSettled(batch).then(() => true as const),
+        guard,
+      ]);
       if (timer) clearTimeout(timer);
+      if (!settled) {
+        // Keep tracking the batch: a later settleWrites still waits for it.
+        this.writes.unshift(...batch);
+        return false;
+      }
     }
+    return true;
   }
 
   /** The recorded snapshot (last-write-wins per family+key), or undefined if empty. */
@@ -160,6 +188,14 @@ export class RecordingShellStore<
     return this.records.size > 0 ? [...this.records.values()] : undefined;
   }
 
+  /** One recorded value, by family and key. */
+  getRecord(
+    family: ShellSnapshotRecord["family"],
+    key: string,
+  ): ShellSnapshotRecord["value"] | undefined {
+    return this.records.get(recordKey(family, key))?.value;
+  }
+
   async get(key: string): Promise<CacheGetResult | null | CacheReadError> {
     const result = await this.inner.get(key);
     if (result && result !== CACHE_READ_ERROR) {
@@ -190,6 +226,7 @@ export class RecordingShellStore<
     key: string,
   ): Promise<{ response: Response; shouldRevalidate: boolean } | null> {
     if (!this.inner.getResponse) return null;
+    this.noteLoaderAccess("response", key);
     const result = await this.inner.getResponse(key);
     if (result)
       this.record("response", key, await serializeResponse(result.response));
@@ -204,12 +241,14 @@ export class RecordingShellStore<
     tags?: string[],
   ): Promise<void> {
     if (!this.inner.putResponse) return;
+    this.noteLoaderAccess("response", key);
     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;
+    this.noteLoaderAccess("item", key);
     const result = await this.inner.getItem(key);
     if (result) {
       const value: ShellSnapshotItemValue = {
@@ -228,6 +267,7 @@ export class RecordingShellStore<
     options?: CacheItemOptions,
   ): Promise<void> {
     if (!this.inner.setItem) return;
+    this.noteLoaderAccess("item", key);
     const stored: ShellSnapshotItemValue = {
       value,
       handles: options?.handles,
@@ -266,6 +306,130 @@ export function getRecordingStore<TEnv>(
   return store instanceof RecordingShellStore ? store : undefined;
 }
 
+/**
+ * True when `snapshot` carries the canonical doc segment record `docKey`
+ * names, with at least one segment: the record partial replay and a
+ * fast-path HIT tail consume.
+ */
+export function hasDocRecord(
+  snapshot: readonly ShellSnapshotRecord[] | undefined,
+  docKey: string | undefined,
+): boolean {
+  if (docKey === undefined || !snapshot) return false;
+  return snapshot.some((record) => {
+    if (
+      !record ||
+      typeof record !== "object" ||
+      record.family !== "segment" ||
+      record.key !== docKey ||
+      typeof record.value !== "object" ||
+      record.value === null
+    ) {
+      return false;
+    }
+    const segments = (record.value as { segments?: unknown }).segments;
+    return Array.isArray(segments) && segments.length > 0;
+  });
+}
+
+/**
+ * Who reads a stored snapshot besides the doc record
+ * (docs/design/shell-entry-layout.md §2):
+ * - "segments": nobody. A navigation-only entry is read only by partial
+ *   replay, which seeds the doc record alone (SeededShellStore
+ *   `segmentsOnly`, implicit doc scope only).
+ * - "loaders": the loaders a document HIT re-runs. Every HIT tail replays
+ *   the handler layer from the doc record and never runs a handler, so the
+ *   records only handler code read are dead weight.
+ */
+export type ShellSnapshotReaders = "segments" | "loaders";
+
+/**
+ * Split a capture's snapshot into what its readers consume and the rest: the
+ * doc record (`docKey`) always; with "loaders", the loader-family records and
+ * the item/response records a loader touched during the capture
+ * (RecordingShellStore.loaderKeys). Every other segment record goes: an
+ * explicit cache() tier's reads and writes are keyed where no HIT tail and no
+ * partial replay looks (both consult only the doc record). The doc record
+ * stays a copy inside the entry: a reference to a separately stored record
+ * could be evicted on its own, and the HIT would have nothing to replay.
+ */
+export function pruneShellSnapshot(
+  snapshot: readonly ShellSnapshotRecord[],
+  readers: ShellSnapshotReaders,
+  loaderKeys: ReadonlySet<string>,
+  docKey: string,
+): { kept: ShellSnapshotRecord[]; pruned: ShellSnapshotRecord[] } {
+  const kept: ShellSnapshotRecord[] = [];
+  const pruned: ShellSnapshotRecord[] = [];
+  for (const record of snapshot) {
+    const keep =
+      (record.family === "segment" && record.key === docKey) ||
+      (readers === "loaders" &&
+        (record.family === "loader" ||
+          (record.family !== "segment" &&
+            loaderKeys.has(recordKey(record.family, record.key)))));
+    (keep ? kept : pruned).push(record);
+  }
+  return { kept, pruned };
+}
+
+/**
+ * The shell entry head's fields estimateShellEntryBytes does not measure
+ * (versions, timestamps, theme, lengths, flags; about 200 bytes in a
+ * CFCacheStore frame) and the frame's 12-byte prefix, with room to spare.
+ */
+export const SHELL_ENTRY_HEAD_ALLOWANCE_BYTES: number = 512;
+
+const ENTRY_BYTE_ENCODER = new TextEncoder();
+
+/**
+ * Bytes (UTF-8) a stored shell entry takes, as the built-in stores write it:
+ * the prelude, the snapshot's JSON, and a JSON head that carries the
+ * postponed state as an escaped string next to the tags and doc key
+ * (CFCacheStore's frame head, VercelCacheStore's envelope), plus
+ * SHELL_ENTRY_HEAD_ALLOWANCE_BYTES for the head's fixed fields and the
+ * frame prefix. Measuring the raw postponed bytes undercounted: every quote
+ * in it is escaped in the head (a /ppr-large/holes entry measured 1,098
+ * bytes under its KV value). The capture's whole-entry guard compares this
+ * with the store's value limit.
+ */
+export function estimateShellEntryBytes(parts: {
+  preludeBytes: number;
+  postponed: string | null | undefined;
+  snapshot: readonly ShellSnapshotRecord[] | undefined;
+  tags: readonly string[] | undefined;
+  docKey: string | undefined;
+  prunedRecords: string | undefined;
+}): number {
+  const head = ENTRY_BYTE_ENCODER.encode(
+    JSON.stringify({
+      po: parts.postponed,
+      t: parts.tags,
+      dk: parts.docKey,
+      pr: parts.prunedRecords,
+    }),
+  ).length;
+  const snapshot =
+    parts.snapshot && parts.snapshot.length > 0
+      ? ENTRY_BYTE_ENCODER.encode(JSON.stringify(parts.snapshot)).length
+      : 0;
+  return (
+    parts.preludeBytes + head + snapshot + SHELL_ENTRY_HEAD_ALLOWANCE_BYTES
+  );
+}
+
+/** Snapshot records by family, e.g. `segment:1/item:5` (no commas: it rides a Server-Timing desc). */
+export function countSnapshotFamilies(
+  snapshot: readonly ShellSnapshotRecord[],
+): string {
+  const counts = new Map<string, number>();
+  for (const record of snapshot) {
+    counts.set(record.family, (counts.get(record.family) ?? 0) + 1);
+  }
+  return [...counts].map(([family, n]) => `${family}:${n}`).join("/");
+}
+
 /**
  * The store the shell fast path's IMPLICIT doc-cache scope resolves during a
  * capture: reads pass through the recording store (a real-store hit is
@@ -324,6 +488,12 @@ export interface ShellLoaderSeedEntry {
    * from the pin (loader-cache.ts pin-first path).
    */
   holes: boolean;
+  /**
+   * The record needs its loader body to run on a HIT for pushes the capture
+   * could not record (ShellSnapshotLoaderValue.runs). Only read for a
+   * hole-free record: a hole-carrying one always runs.
+   */
+  runs: boolean;
 }
 
 export async function buildShellLoaderSeed(
@@ -345,9 +515,12 @@ export async function buildShellLoaderSeed(
             rec.key,
             {
               container: await deserializeResult(stored.value),
-              // A record without the bit (pre-bit snapshot) reads as
-              // hole-carrying: unknown hole-ness must keep the gated path.
+              // A record without a bit predates it: without the hole bit it
+              // reads as hole-carrying (unknown hole-ness keeps the gated
+              // path), and without the runs bit as runs (its snapshot lacks
+              // the loader-owned pushes, so the body supplies them).
               holes: stored.holes !== 0,
+              runs: stored.runs !== 0,
             },
           ];
         } catch {
@@ -514,3 +687,20 @@ export class SeededShellStore<
     return this.inner.invalidateTags?.(tags);
   }
 }
+
+/**
+ * Thrown by a document HIT tail's match when its doc record cannot supply the
+ * handler layer (it failed to decode, or the entry lost it). The tail must not
+ * run handlers after the prelude committed, so withCacheLookup throws this
+ * instead of resolving segments, and serveShellHit degrades the response:
+ * the entry is replaced with a tombstone, the memo is dropped, a recapture is
+ * scheduled, and the browser reloads into a MISS.
+ */
+export class ShellRecordUnavailableError extends Error {
+  constructor(docKey: string | undefined) {
+    super(
+      `PPR shell HIT: the doc record${docKey ? ` "${docKey}"` : ""} could not supply the handler layer`,
+    );
+    this.name = "ShellRecordUnavailableError";
+  }
+}

package/src/cache/tag-invalidation.ts

@@ -21,9 +21,28 @@
  * 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.
+ *
+ * Both call invalidateTags() synchronously, inside the request (#973). A store
+ * masks the tags for the rest of the request before its first await (the
+ * built-in stores write their per-request marker state there), so the request
+ * that ran either verb reads its own writes; revalidateTag() leaves only the
+ * durable remainder (KV marker put, tag purge, expireTag) to waitUntil.
+ * Invariant: the mask only turns the invalidating request's hits into misses.
+ * If the durable write then fails, that request paid extra misses, never a
+ * stale read, and other requests read the durable state. Both also record
+ * the tags on the request (markInvalidated), so a "use cache" execution or
+ * stale refresh this request started before one of its own tags was
+ * invalidated is neither joined nor written (cache-runtime.ts). Its own tags
+ * only: a nested "use cache" function's tags do not reach the enclosing
+ * entry (#980), for this gate as for eviction. Not covered (#977): such an
+ * execution in another request, or a loader cache() write, still lands, and
+ * the store accepts it (docs/design/caching.md "Read-your-own-writes").
  */
 
-import { _getRequestContext } from "../server/request-context.js";
+import {
+  _getRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
 import { reportingAsync } from "./cache-error.js";
 import { normalizeTags } from "./cache-tag.js";
 import type { SegmentCacheStore } from "./types.js";
@@ -104,6 +123,66 @@ function warnPartialTagStore(fn: string, incapable: number): void {
   );
 }
 
+/**
+ * Set the fresh-reads cookie on this request's response for as long as the
+ * invalidated stores' isolate memos can stay stale (isolate-tag-memo.ts), so
+ * the same user's next requests read past them on every isolate.
+ */
+function markFreshReads(stores: SegmentCacheStore[]): void {
+  const ctx = _getRequestContext();
+  if (!ctx?._setFreshReadsCookie) return;
+  let windowMs = 0;
+  for (const store of stores) {
+    windowMs = Math.max(windowMs, store.freshReadsWindowMs ?? 0);
+  }
+  if (windowMs > 0) ctx._setFreshReadsCookie(windowMs);
+}
+
+/**
+ * The isolate's order of tag invalidations and "use cache" execution starts
+ * (#973). A counter, not Date.now(): Workers advance the clock only on I/O,
+ * so an execution started right after an invalidation would share its
+ * millisecond and read as older.
+ */
+let cacheSeq = 0;
+
+/** The current position in that order; an execution records it at start. */
+export function currentCacheSeq(): number {
+  return cacheSeq;
+}
+
+/**
+ * Whether the request invalidated any of `tags` after `since` (a
+ * currentCacheSeq() value an execution recorded when it started): its value
+ * may predate the invalidation, so the request neither joins nor writes it.
+ */
+export function invalidatedSince(
+  ctx: RequestContext<any, any> | undefined,
+  tags: readonly string[] | undefined,
+  since: number,
+): boolean {
+  const record = (ctx?._requestRoot ?? ctx)?._tagInvalidations;
+  if (!record || !tags) return false;
+  for (const tag of tags) {
+    const at = record.get(tag);
+    if (at !== undefined && at > since) return true;
+  }
+  return false;
+}
+
+/**
+ * Record the invalidation on the request (RequestContext._tagInvalidations,
+ * on the root so derived contexts share it), before any store sees it.
+ */
+function markInvalidated(tags: readonly string[]): void {
+  const ctx = _getRequestContext();
+  if (!ctx) return;
+  const root = ctx._requestRoot ?? ctx;
+  const at = ++cacheSeq;
+  const record = (root._tagInvalidations ??= new Map());
+  for (const tag of tags) record.set(tag, at);
+}
+
 async function invalidateAcross(
   stores: SegmentCacheStore[],
   tags: string[],
@@ -163,6 +242,8 @@ export async function updateTag(...tags: string[]): Promise<void> {
   }
   if (incapable > 0) warnPartialTagStore("updateTag", incapable);
 
+  markFreshReads(capable);
+  markInvalidated(valid);
   await invalidateAcross(capable, valid);
 }
 
@@ -173,10 +254,12 @@ export async function updateTag(...tags: string[]): Promise<void> {
  * 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.
+ * durable write 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.
+ * Read-your-own-writes (#973): each built-in store masks the tags for the rest
+ * of this request before revalidateTag() returns, so a Server Action's own
+ * re-render after it is fresh, as after `await updateTag()`. Other requests see
+ * the invalidation once the durable write lands.
  *
  * 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
@@ -209,23 +292,25 @@ export function revalidateTag(...tags: string[]): void {
   }
   if (incapable > 0) warnPartialTagStore("revalidateTag", incapable);
 
+  markFreshReads(capable);
   const ctx = _getRequestContext();
+  // A build-time render drops background work (RequestContext.waitUntil), so
+  // it never ran this invalidation; keep it that way.
+  if (ctx?.build) return;
+  markInvalidated(valid);
+  // Started here, not in the waitUntil task, so each store masks the tags
+  // before this returns (#973, header above).
+  //
   // 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();
-  }
+  // explicitly: the write can settle after the response, outside the
+  // request's ALS scope, and onError fires only with the captured context.
+  const pending = reportingAsync(
+    () => invalidateAcross(capable, valid),
+    "cache-invalidate",
+    "[revalidateTag] background invalidation",
+    ctx,
+  );
+  ctx?.waitUntil(() => pending);
 }