@rangojs/router 0.17.0 → 0.18.0

package/src/cache/cf/cf-cache-types.ts

@@ -15,6 +15,7 @@ import type { ExecutionContext } from "../../types/request-scope.js";
 import type { CacheDefaults } from "../types.js";
 import type { RequestContext } from "../../server/request-context.js";
 import type { CloudflareZonePurgeOptions } from "./cf-zone-purge.js";
+import type { StoreMemoOptions } from "../shell-memo.js";
 
 /**
  * Minimal Cloudflare KV Namespace interface.
@@ -340,9 +341,12 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
 
   /**
    * Latency budget (ms) for reading the BODY of a matched L1 entry
-   * (response.json()). CF streams the cache body lazily, so the multi-second
-   * tail can appear after `match` already resolved; this bounds it. On timeout
-   * the read is treated as a miss and falls through to L2/KV or render.
+   * (response.json(); for a PPR shell, only its head and prelude — the
+   * snapshot behind them is read after the HIT commits, under
+   * {@link kvReadTimeoutMs}). CF streams the cache body lazily, so the
+   * multi-second tail can appear after `match` already resolved; this bounds
+   * it. On timeout the read is treated as a miss and falls through to L2/KV or
+   * render.
    *
    * Separate from {@link edgeLookupTimeoutMs} because a healthy body read
    * (fetch + JSON parse of a potentially large Flight payload) takes a little
@@ -356,7 +360,11 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    * Latency budget (ms) for an L2 (KV) read. KV is the last cache tier before a
    * full render and is a global store (~50ms healthy, seconds when degraded);
    * this bounds it so a slow namespace cannot pin the request. On timeout the
-   * read is treated as a miss (no L1 promote) and falls through to render.
+   * read is treated as a miss (no L1 promote) and falls through to render. For
+   * a PPR shell it covers opening the KV value and reading its head and
+   * prelude; separately, it bounds the shell's snapshot read (either tier),
+   * which runs off the commit path: a timeout there lets the tail run without
+   * the snapshot's pins.
    *
    * Defaults to {@link KV_READ_TIMEOUT_MS} (170) -- a few multiples above the
    * ~50ms healthy read, with headroom for legitimate tails (large payloads / far
@@ -367,6 +375,26 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    */
   kvReadTimeoutMs?: number;
 
+  /**
+   * Per-isolate memos ({@link StoreMemoOptions}), one set per isolate and
+   * shared by every CFCacheStore in it. `shellMs` (default 2000) and
+   * `shellMaxBytes` (default 16 MiB) size the PPR shell memo;
+   * `markerFreshMs` (default 1000) and `markerMaxStaleMs` (default 10000)
+   * the tag-marker memo PPR shell reads use with KV bound (served
+   * stale-while-revalidate). A memo HIT still runs the tag-marker check; the
+   * isolate that invalidates drops its own shell copies (and keeps reads in
+   * flight from memoizing them again) and writes the new marker into its
+   * marker memo, and its own `putShell` replaces its copy. Another isolate
+   * rejects a memoized shell once its marker memo sees the invalidation (up
+   * to `markerMaxStaleMs`). Without KV, in purge mode, the purge does not
+   * reach other isolates' memos: they serve the purged shell until their
+   * window passes. The response of a request that ran `updateTag()` /
+   * `revalidateTag()` sets the fresh-reads cookie, and the same user's
+   * requests carrying it skip both memos. `{ shellMs: 0 }` turns the shell
+   * memo off, `{ markerFreshMs: 0 }` the marker memo.
+   */
+  memo?: StoreMemoOptions;
+
   /**
    * Emit a {@link CFCacheReadDebugEvent} per L1 read. `true` logs to console
    * (visible via `wrangler tail`); pass a function to capture events directly.

package/src/cache/cf/cf-shell-frame.ts

@@ -0,0 +1,258 @@
+/**
+ * Prelude-first binary layout of a CFCacheStore PPR shell entry, shared by the
+ * Cache API body and the KV value (issue #941; docs/design/shell-entry-layout.md):
+ *
+ *   "RSH1" | head length, 8 hex digits | head JSON | prelude bytes | snapshot JSON
+ *
+ * A document HIT needs the head (versions, freshness, tags, postponed) and the
+ * raw prelude before its first byte, and the capture snapshot only in the
+ * tail. Laying them out in that order lets the serve path read the head,
+ * start the tag-marker read, read exactly `pl` prelude bytes, and commit while
+ * the snapshot bytes are still arriving. One record keeps the prelude and the
+ * snapshot generation-coupled by construction: a Cache API entry and a KV
+ * value are written and read whole, so a split read can never pair one
+ * capture's prelude with another's pins.
+ *
+ * Every byte is UTF-8 text when the prelude is (React's HTML through
+ * TextEncoder always is), so the KV value is stored as a string (the
+ * KVNamespace contract's `put(key, string)`) and read back as the same bytes
+ * with `{ type: "stream" }`.
+ */
+
+import type { ShellSnapshotRecord } from "../types.js";
+
+const MAGIC = [0x52, 0x53, 0x48, 0x31]; // "RSH1"
+/** Magic (4) + head length as 8 hex digits (8). */
+const PREFIX_BYTES = 12;
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+const strictTextDecoder = new TextDecoder("utf-8", { fatal: true });
+
+/** The frame head: every entry field except the prelude and the snapshot. */
+export interface ShellFrameHead {
+  /** ShellCacheEntry.reactVersion */
+  rv: string;
+  /** ShellCacheEntry.buildVersion */
+  bv?: string;
+  /** Capture-generation start time (ms epoch), used by tag marker checks. */
+  c: number;
+  /** When the entry becomes stale (ms epoch). */
+  s: number;
+  /** When the entry hard-expires (ms epoch). */
+  e: number;
+  /** Cache tags (for distributed tag invalidation). */
+  t?: string[];
+  /** Timestamp when tags were attached (ms epoch). */
+  ta?: number;
+  /** ShellCacheEntry.initialTheme */
+  i?: string;
+  /** ShellCacheEntry.docKey; navigation replay needs it after any round trip. */
+  dk?: string;
+  /** ShellCacheEntry.prunedRecords (diagnostic). */
+  pr?: string;
+  /** ShellCacheEntry.navigationOnly; its partial-context prelude is not document-safe. */
+  no?: true;
+  /** ShellCacheEntry.postponed. Absent iff `no` (no document half is stored). */
+  po?: string | null;
+  /** Prelude byte length (0 for a navigationOnly entry). */
+  pl: number;
+  /**
+   * Snapshot byte length (0 when the entry has none). A body whose snapshot
+   * part is any other length was truncated or corrupted.
+   */
+  sl: number;
+}
+
+/** Validate a parsed head before any field reaches the serve path. */
+function isShellFrameHead(value: unknown): value is ShellFrameHead {
+  if (value == null || typeof value !== "object") return false;
+  const head = value as Partial<ShellFrameHead>;
+  return (
+    typeof head.rv === "string" &&
+    (head.bv === undefined || typeof head.bv === "string") &&
+    isFiniteNumber(head.c) &&
+    isFiniteNumber(head.s) &&
+    isFiniteNumber(head.e) &&
+    (head.t === undefined ||
+      (Array.isArray(head.t) &&
+        head.t.every((tag) => typeof tag === "string"))) &&
+    (head.ta === undefined || isFiniteNumber(head.ta)) &&
+    (head.i === undefined || typeof head.i === "string") &&
+    (head.dk === undefined || typeof head.dk === "string") &&
+    (head.pr === undefined || typeof head.pr === "string") &&
+    (head.no === undefined || head.no === true) &&
+    // Document half: postponed is required unless the entry is navigationOnly.
+    (head.po === null ||
+      typeof head.po === "string" ||
+      (head.po === undefined && head.no === true)) &&
+    isByteLength(head.pl) &&
+    isByteLength(head.sl)
+  );
+}
+
+function isByteLength(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+/**
+ * Serialize a shell entry into one prelude-first frame. Throws when the head's
+ * byte lengths (`pl`, `sl`) do not describe `prelude` and `snapshot`.
+ */
+export function encodeShellFrame(
+  head: ShellFrameHead,
+  prelude: Uint8Array,
+  snapshot?: Uint8Array,
+): Uint8Array<ArrayBuffer> {
+  const snapshotLength = snapshot?.length ?? 0;
+  if (head.pl !== prelude.length || head.sl !== snapshotLength) {
+    throw new Error("shell frame head does not match its prelude/snapshot");
+  }
+  const headBytes = textEncoder.encode(JSON.stringify(head));
+  const frame = new Uint8Array(
+    PREFIX_BYTES + headBytes.length + prelude.length + snapshotLength,
+  );
+  frame.set(MAGIC, 0);
+  frame.set(
+    textEncoder.encode(headBytes.length.toString(16).padStart(8, "0")),
+    MAGIC.length,
+  );
+  frame.set(headBytes, PREFIX_BYTES);
+  frame.set(prelude, PREFIX_BYTES + headBytes.length);
+  if (snapshot) {
+    frame.set(snapshot, PREFIX_BYTES + headBytes.length + prelude.length);
+  }
+  return frame;
+}
+
+/**
+ * The frame as the string KV stores. Throws when the prelude is not valid
+ * UTF-8, which would not round-trip through a string.
+ */
+export function shellFrameToText(frame: Uint8Array): string {
+  return strictTextDecoder.decode(frame);
+}
+
+/** UTF-8 JSON of a snapshot, or undefined when there is none to store. */
+export function encodeShellSnapshot(
+  snapshot: ShellSnapshotRecord[] | undefined,
+): Uint8Array | undefined {
+  return snapshot && snapshot.length > 0
+    ? textEncoder.encode(JSON.stringify(snapshot))
+    : undefined;
+}
+
+/**
+ * Parse the snapshot bytes that follow the prelude. Zero bytes means the entry
+ * carries no snapshot. Throws on anything else that is not a JSON array: the
+ * caller treats that as corruption.
+ */
+export function parseShellSnapshot(
+  bytes: Uint8Array,
+): ShellSnapshotRecord[] | undefined {
+  if (bytes.length === 0) return undefined;
+  const parsed: unknown = JSON.parse(textDecoder.decode(bytes));
+  if (!Array.isArray(parsed)) {
+    throw new Error("shell snapshot is not an array");
+  }
+  return parsed as ShellSnapshotRecord[];
+}
+
+/**
+ * Incremental reader over a streamed frame (a Cache API response body or a KV
+ * `{ type: "stream" }` value). The serve path reads the head and exactly the
+ * prelude's bytes before it commits; the snapshot is whatever remains.
+ */
+export class ShellFrameReader {
+  private readonly reader: ReadableStreamDefaultReader<Uint8Array>;
+  private chunks: Uint8Array[] = [];
+  private buffered = 0;
+  private done = false;
+  /** Bytes of the prefix and head, once readHead has read them. */
+  headBytes = 0;
+
+  constructor(body: ReadableStream<Uint8Array>) {
+    this.reader = body.getReader();
+  }
+
+  /** Exactly `n` bytes, or null when the stream ends first. */
+  async take(n: number): Promise<Uint8Array | null> {
+    while (this.buffered < n && !this.done) {
+      const { done, value } = await this.reader.read();
+      if (done) {
+        this.done = true;
+      } else if (value.length > 0) {
+        this.chunks.push(value);
+        this.buffered += value.length;
+      }
+    }
+    if (this.buffered < n) return null;
+    const out = concat(this.chunks, n);
+    const leftover = this.buffered - n;
+    const last = this.chunks[this.chunks.length - 1]!;
+    this.chunks = leftover > 0 ? [last.subarray(last.length - leftover)] : [];
+    this.buffered = leftover;
+    return out;
+  }
+
+  /** The head, or null when the magic, length, or JSON is malformed or short. */
+  async readHead(): Promise<ShellFrameHead | null> {
+    const prefix = await this.take(PREFIX_BYTES);
+    if (!prefix || MAGIC.some((byte, index) => prefix[index] !== byte)) {
+      return null;
+    }
+    const lengthDigits = textDecoder.decode(prefix.subarray(MAGIC.length));
+    if (!/^[0-9a-f]{8}$/.test(lengthDigits)) return null;
+    const headBytes = await this.take(Number.parseInt(lengthDigits, 16));
+    if (!headBytes) return null;
+    this.headBytes = PREFIX_BYTES + headBytes.length;
+    let head: unknown;
+    try {
+      head = JSON.parse(textDecoder.decode(headBytes));
+    } catch {
+      return null;
+    }
+    return isShellFrameHead(head) ? head : null;
+  }
+
+  /** Everything after what was taken, to the end of the stream. */
+  async readRest(): Promise<Uint8Array> {
+    while (!this.done) {
+      const { done, value } = await this.reader.read();
+      if (done) {
+        this.done = true;
+      } else if (value.length > 0) {
+        this.chunks.push(value);
+        this.buffered += value.length;
+      }
+    }
+    const out = concat(this.chunks, this.buffered);
+    this.chunks = [];
+    this.buffered = 0;
+    return out;
+  }
+
+  /** Stop reading and release the body. */
+  cancel(): void {
+    this.done = true;
+    this.reader.cancel().catch(() => {});
+  }
+}
+
+/** The first `n` bytes of `chunks` as one array (no copy for a single chunk). */
+function concat(chunks: Uint8Array[], n: number): Uint8Array {
+  if (chunks.length === 1 && chunks[0]!.length === n) return chunks[0]!;
+  const out = new Uint8Array(n);
+  let offset = 0;
+  for (const chunk of chunks) {
+    if (offset >= n) break;
+    const part = chunk.subarray(0, Math.min(chunk.length, n - offset));
+    out.set(part, offset);
+    offset += part.length;
+  }
+  return out;
+}

package/src/cache/cf/cf-tag-marker-memo.ts

@@ -2,12 +2,12 @@
 // Tag-marker memo
 // ============================================================================
 //
-// Per-request memoization of tag-invalidation marker reads, plus the prefix and
-// sentinel used by the optional per-colo L1 marker cache. Extracted from
-// cf-cache-store.ts; the WeakMaps stay MODULE SINGLETONS here (the module is
-// evaluated once), so binding-keyed memo semantics are unchanged: the maps are
-// keyed by the request-context object then the store INSTANCE, identical to
-// before the move.
+// CFCacheStore's per-request tag-marker state: the data families' marker memo
+// and in-flight reads, the PPR shell read's own marker record, and the prefix
+// and sentinel of the optional per-colo L1 marker cache. The maps are module
+// singletons keyed by the request-context object, then the store INSTANCE.
+
+import type { MarkerMemoOutcome } from "../isolate-tag-memo.js";
 
 /**
  * Cache-API path prefix for the optional per-colo L1 cache of tag-invalidation
@@ -24,6 +24,32 @@ export const TAG_MARKER_CACHE_PREFIX = "__tagmarker__/";
  */
 export const TAG_MARKER_ABSENT = "none";
 
+/**
+ * Request context -> store instance -> T, both levels weakly held. Also
+ * VercelCacheStore's request tag mask (#973).
+ */
+export type PerRequestStoreMap<T> = WeakMap<object, WeakMap<object, T>>;
+
+/** The value for (ctx, store), created on first use. */
+export function perRequestStoreValue<T>(
+  map: PerRequestStoreMap<T>,
+  ctx: object,
+  store: object,
+  create: () => T,
+): T {
+  let byStore = map.get(ctx);
+  if (!byStore) {
+    byStore = new WeakMap();
+    map.set(ctx, byStore);
+  }
+  let value = byStore.get(store);
+  if (value === undefined) {
+    value = create();
+    byStore.set(store, value);
+  }
+  return value;
+}
+
 /**
  * Per-request memo of tag-invalidation markers (tag -> latest invalidatedAt, or
  * null when no marker exists). Keyed first by the request context object (so it
@@ -42,38 +68,97 @@ export const TAG_MARKER_ABSENT = "none";
  * short-circuits when a store has no KV — and, in purge mode, through
  * isL1Invalidated(), which consults ONLY this memo on an L1 hit (no KV read),
  * so a purge-mode store allocates the memo even without KV for same-request
- * read-your-own-writes after updateTag().
+ * read-your-own-writes after updateTag()/revalidateTag().
  *
  * Without the memo, isGloballyInvalidated() issues a KV read per tag on every
  * tagged cache read, so a page composed of many segments/items sharing a tag
  * pays that cost N times. The memo collapses it to one KV read per distinct tag
- * per (request, store). invalidateTags() writes through so a same-request
- * updateTag() stays read-your-own-writes consistent (the action's own re-render
- * sees its own invalidation from the memo, without a re-read).
+ * per (request, store). invalidateTags() writes the new marker here before its
+ * first await (maskRequestTags, #973), so the request that ran updateTag() or
+ * revalidateTag() reads its own writes: the action's own re-render sees its
+ * invalidation from the memo, without waiting for the KV put that
+ * revalidateTag() leaves to waitUntil.
  *
  * It does NOT span requests, so a hot single-entry route still pays one KV read
  * per request; that read hits Cloudflare KV's own edge read cache for hot keys.
+ * A context derived from the request (Object.create(reqCtx): a PPR HIT tail, a
+ * shell capture) keeps a memo of its own, so its marker reads stay its own; it
+ * starts from the request's mask (requestMasks) instead of empty, and takes
+ * every mask the request sets later (requestMemos).
  */
-const tagMarkerMemo = new WeakMap<
-  object,
-  WeakMap<object, Map<string, number | null>>
->();
+const tagMarkerMemo: PerRequestStoreMap<Map<string, number | null>> =
+  new WeakMap();
+
+/**
+ * The tags each request invalidated through each store, with the
+ * invalidatedAt its mask carries (#973). Keyed by the request's root context
+ * (RequestContext._requestRoot) rather than by the context that called, so a
+ * derived context sees the request's mask and a mask it sets reaches the
+ * request. Its values are unconfirmed until the KV put lands: a marker read
+ * that finds one of them publishes nothing to other requests
+ * (CFCacheStore.fetchTagMarker).
+ */
+const requestMasks: PerRequestStoreMap<Map<string, number>> = new WeakMap();
+
+/**
+ * Every memo of a request, whichever context owns it, per (root, store): a
+ * mask set later reaches the memos that already exist (maskRequestTags), not
+ * only the caller's. They live as long as the request does.
+ */
+const requestMemos: PerRequestStoreMap<Set<Map<string, number | null>>> =
+  new WeakMap();
+
+function requestRoot(ctx: object): object {
+  return (ctx as { _requestRoot?: object })._requestRoot ?? ctx;
+}
 
 export function getTagMarkerMemo(
   ctx: object,
   store: object,
 ): Map<string, number | null> {
-  let byStore = tagMarkerMemo.get(ctx);
-  if (!byStore) {
-    byStore = new WeakMap();
-    tagMarkerMemo.set(ctx, byStore);
-  }
-  let memo = byStore.get(store);
-  if (!memo) {
-    memo = new Map();
-    byStore.set(store, memo);
+  return perRequestStoreValue(tagMarkerMemo, ctx, store, () => {
+    const root = requestRoot(ctx);
+    const memo = new Map<string, number | null>(
+      requestMasks.get(root)?.get(store),
+    );
+    perRequestStoreValue(requestMemos, root, store, () => new Set()).add(memo);
+    return memo;
+  });
+}
+
+/**
+ * Mask `tags` at `at` for the rest of the request: in the request's mask and
+ * in every memo the request's contexts hold for `store` (a memo created later
+ * starts from the mask).
+ */
+export function maskRequestTags(
+  ctx: object,
+  store: object,
+  tags: readonly string[],
+  at: number,
+): void {
+  const root = requestRoot(ctx);
+  const mask = perRequestStoreValue(
+    requestMasks,
+    root,
+    store,
+    () => new Map<string, number>(),
+  );
+  getTagMarkerMemo(ctx, store);
+  const memos = requestMemos.get(root)?.get(store) ?? [];
+  for (const tag of tags) {
+    mask.set(tag, at);
+    for (const memo of memos) memo.set(tag, at);
   }
-  return memo;
+}
+
+/** Whether this request masked `tag` through `store` (maskRequestTags). */
+export function isRequestMasked(
+  ctx: object,
+  store: object,
+  tag: string,
+): boolean {
+  return requestMasks.get(requestRoot(ctx))?.get(store)?.has(tag) ?? false;
 }
 
 /**
@@ -85,24 +170,43 @@ export function getTagMarkerMemo(
  * collapses those to a single KV read. Entries are dropped once resolved (the
  * value is then in the memo), so this only spans the concurrent read window.
  */
-const tagMarkerInflight = new WeakMap<
-  object,
-  WeakMap<object, Map<string, Promise<number | null>>>
->();
+const tagMarkerInflight: PerRequestStoreMap<
+  Map<string, Promise<number | null>>
+> = new WeakMap();
+
+/**
+ * A request's PPR shell-read marker reads (issue #941), kept apart from the
+ * per-request memo above, HIT or MISS. A shell read may answer a marker from
+ * the isolate marker memo (isolate-tag-memo.ts), up to `markerMaxStaleMs`
+ * old; the data families must never see that value. Scar tissue: first the
+ * shell read wrote into the per-request memo, so a MISS request rendered and
+ * stored its `"use cache"` data under a stale marker; then a HIT copied its
+ * entry's tags across, which a partial navigation's matchPartial (on the same
+ * context as its replay gate's getShell) read, and a `cache()` segment it
+ * wrote kept the stale item past `markerMaxStaleMs` under a fresh taggedAt.
+ */
+export interface ShellMarkerReads {
+  /** The read of each tag, settled or in flight (collapses concurrent reads). */
+  reads: Map<string, Promise<number | null>>;
+  /** How the isolate memo answered each tag (the marker row's `memo=`). */
+  outcomes: Map<string, MarkerMemoOutcome>;
+}
+
+const shellMarkerReads: PerRequestStoreMap<ShellMarkerReads> = new WeakMap();
+
+export function getShellMarkerReads(
+  ctx: object,
+  store: object,
+): ShellMarkerReads {
+  return perRequestStoreValue(shellMarkerReads, ctx, store, () => ({
+    reads: new Map(),
+    outcomes: new Map(),
+  }));
+}
 
 export function getTagMarkerInflight(
   ctx: object,
   store: object,
 ): Map<string, Promise<number | null>> {
-  let byStore = tagMarkerInflight.get(ctx);
-  if (!byStore) {
-    byStore = new WeakMap();
-    tagMarkerInflight.set(ctx, byStore);
-  }
-  let inflight = byStore.get(store);
-  if (!inflight) {
-    inflight = new Map();
-    byStore.set(store, inflight);
-  }
-  return inflight;
+  return perRequestStoreValue(tagMarkerInflight, ctx, store, () => new Map());
 }

package/src/cache/handle-snapshot.ts

@@ -140,9 +140,10 @@ export function captureHandleOwners(
  * cache() record owns its segments' arrays, so it REPLACES them.
  *
  * A segment with `owners` is replaced with empty arrays and re-pushed in
- * recorded order, an owned value through pushReplayed: the owning loader
- * re-runs on the HIT (loaders stay live), and its live pushes replace the
- * recorded ones in place instead of appending a second copy. `claim`
+ * recorded order, an owned value through pushReplayed: if the owning loader
+ * runs on the HIT (a live loader, or a promise-carrying `ssr: false` one;
+ * a promise-free one is served from the shell and does not), its live pushes
+ * replace the recorded ones in place instead of appending a second copy. `claim`
  * (setupLoaderAccess _claimLoaderPushes) is asked once per owner, so the
  * loader's own cache() HIT does not replay its pushes a second time
  * (loader-cache.ts replayLoaderHandles); an owner it refuses is skipped. A

package/src/cache/index.ts

@@ -13,6 +13,8 @@ export { CACHE_READ_ERROR } from "./types.js";
 
 export { MemorySegmentCacheStore } from "./memory-segment-store.js";
 
+export type { StoreMemoOptions } from "./shell-memo.js";
+
 export {
   CFCacheStore,
   type CFCacheStoreOptions,