@rangojs/router 0.17.0 → 0.18.0

package/src/cache/cache-tag.ts

@@ -15,9 +15,197 @@ import {
   _getRequestContext,
   type RequestContext,
 } from "../server/request-context.js";
+import {
+  getCurrentLoaderBodyId,
+  getLoaderBodyTags,
+  isInsideLoaderScope,
+  type LoaderIdentityRead,
+  type LoaderIdentityReadVerb,
+} from "../server/context.js";
 
 const cacheTagStorage = new AsyncLocalStorage<Set<string>>();
 
+/**
+ * Tag owners (#957). A route cache() record replays its segments without
+ * running their handlers or re-rendering their server components, so the
+ * tags that content recorded must ride on the record, or a HIT (and the PPR
+ * capture that replays it) loses them.
+ *
+ * Every tag records onto its owner: the running loader body
+ * (getCurrentLoaderBodyId, server/context.ts), else the segment whose handler
+ * or record serialization is running (runInSegmentTagScope). No segment scope
+ * opens inside a loader body, so this is innermost-wins. A loader's value
+ * reaches a record only through the handler (or loader) that reads it, so
+ * ctx.use() links the reader to the loader (linkLoaderTags) whoever started
+ * it, and getSegmentTags follows those links. A loader nobody reads
+ * server-side (useLoader under loading()) stays off every record.
+ *
+ * The sets are keyed by the request context a tag records on, so a shell
+ * capture's derived context (Object.create(reqCtx)) never reads or feeds the
+ * foreground's.
+ *
+ * All of it runs only for a request that can write a record
+ * (RequestContext._recordTagOwners, armed by armRecordTagOwners at match
+ * time): elsewhere a handler call takes no scope, closure or allocation.
+ */
+const segmentOwnerStorage = new AsyncLocalStorage<string>();
+
+/**
+ * Arm the record tag owners for `ctx`: its match resolved a cache scope, so
+ * it can write a route cache() record (match-api.ts). A capture's or
+ * background re-render's derived context inherits the flag.
+ */
+export function armRecordTagOwners(
+  ctx: RequestContext | undefined = _getRequestContext(),
+): void {
+  if (ctx) ctx._recordTagOwners = true;
+}
+
+/** Whether `ctx` records tag owners (see armRecordTagOwners). */
+export function recordTagOwnersArmed(
+  ctx: RequestContext | undefined = _getRequestContext(),
+): boolean {
+  return ctx?._recordTagOwners === true;
+}
+
+interface RequestTagOwners {
+  /** owner key -> tags recorded while it ran */
+  tags: Map<string, Set<string>>;
+  /** owner key -> loader owner keys whose values it consumed */
+  uses: Map<string, Set<string>>;
+}
+const tagOwnersByRequest = new WeakMap<RequestContext, RequestTagOwners>();
+
+const segmentOwner = (segmentId: string): string => `s:${segmentId}`;
+const loaderOwner = (loaderId: string): string => `l:${loaderId}`;
+
+function ownersFor(ctx: RequestContext): RequestTagOwners {
+  let owners = tagOwnersByRequest.get(ctx);
+  if (!owners) {
+    owners = { tags: new Map(), uses: new Map() };
+    tagOwnersByRequest.set(ctx, owners);
+  }
+  return owners;
+}
+
+function setFor(map: Map<string, Set<string>>, key: string): Set<string> {
+  let set = map.get(key);
+  if (!set) {
+    set = new Set();
+    map.set(key, set);
+  }
+  return set;
+}
+
+function currentOwner(): string | undefined {
+  const loaderId = getCurrentLoaderBodyId();
+  return loaderId !== undefined
+    ? loaderOwner(loaderId)
+    : segmentOwnerStorage.getStore();
+}
+
+/**
+ * Call `fn(arg)` inside segment `segmentId`'s tag scope: tags recorded while
+ * it or its async continuations run (outside a loader body) are owned by that
+ * segment. Unarmed, it is a plain call.
+ */
+export function runInSegmentTagScope<R, A = undefined>(
+  segmentId: string,
+  fn: (arg: A) => R,
+  arg?: A,
+): R {
+  if (!recordTagOwnersArmed()) return fn(arg as A);
+  return segmentOwnerStorage.run(segmentOwner(segmentId), fn, arg as A);
+}
+
+/**
+ * Record that the current owner reads loader `loaderId`'s value (ctx.use),
+ * so the loader's tags follow the reader onto a record. The DSL funnel
+ * starting a loader (resolveLoaderData, inside the DSL loader scope but no
+ * loader body) is not a reader.
+ */
+export function linkLoaderTags(
+  loaderId: string,
+  ctx: RequestContext | undefined = _getRequestContext(),
+): void {
+  if (!ctx || !recordTagOwnersArmed(ctx)) return;
+  const owner = currentOwner();
+  if (owner === undefined) return;
+  if (owner.startsWith("s:") && isInsideLoaderScope()) return;
+  setFor(ownersFor(ctx).uses, owner).add(loaderOwner(loaderId));
+}
+
+/**
+ * Record `tags` as loader `loaderId`'s own, read outside its body (its
+ * cache() config tags, or a loader-cache HIT's stored tags):
+ * recordRequestTags with an explicit owner.
+ */
+export function recordLoaderTags(
+  loaderId: string,
+  tags: Iterable<string> | undefined,
+  ctx: RequestContext | undefined = _getRequestContext(),
+): void {
+  recordOwnedTags(
+    tags,
+    ctx,
+    recordTagOwnersArmed(ctx) ? loaderOwner(loaderId) : undefined,
+  );
+}
+
+/**
+ * The tags segment `segmentId`'s content recorded in `ctx`: its own, plus
+ * those of every loader it consumed, transitively.
+ */
+export function getSegmentTags(
+  ctx: RequestContext,
+  segmentId: string,
+): ReadonlySet<string> {
+  const owners = tagOwnersByRequest.get(ctx);
+  const out = new Set<string>();
+  if (!owners) return out;
+  const seen = new Set<string>();
+  const pending = [segmentOwner(segmentId)];
+  for (let owner = pending.pop(); owner !== undefined; owner = pending.pop()) {
+    if (seen.has(owner)) continue;
+    seen.add(owner);
+    for (const tag of owners.tags.get(owner) ?? []) out.add(tag);
+    for (const used of owners.uses.get(owner) ?? []) pending.push(used);
+  }
+  return out;
+}
+
+/**
+ * Record `tags` onto each of `segmentIds` (a route cache() HIT replaying
+ * those segments): a record written from the replay, such as a shell
+ * capture's doc record (match-middleware/cache-store.ts), then carries them
+ * as a fresh render's record would. Unarmed, a no-op.
+ */
+export function recordSegmentTags(
+  segmentIds: readonly string[],
+  tags: Iterable<string> | undefined,
+  ctx: RequestContext | undefined = _getRequestContext(),
+): void {
+  if (!tags || !ctx || !recordTagOwnersArmed(ctx)) return;
+  for (const id of segmentIds) recordOwnedTags(tags, ctx, segmentOwner(id));
+}
+
+/**
+ * The owner of the loaders a shell capture bakes (loader-cache.ts bake
+ * lane): their data is shell material that no handler reads, so their tags
+ * reach the shell through this owner (shell-capture.ts), not a record.
+ */
+export const SHELL_BAKE_TAG_OWNER: string = "#shell-bake";
+
+/** Link loader `loaderId`'s tags to `ownerId` (see SHELL_BAKE_TAG_OWNER). */
+export function linkLoaderTagsTo(
+  ownerId: string,
+  loaderId: string,
+  ctx: RequestContext | undefined = _getRequestContext(),
+): void {
+  if (!ctx || !recordTagOwnersArmed(ctx)) return;
+  setFor(ownersFor(ctx).uses, segmentOwner(ownerId)).add(loaderOwner(loaderId));
+}
+
 export function normalizeTag(tag: string): string | null {
   // Trim and return the canonical (trimmed) form, not the raw tag. Both the
   // write path (cacheTag) and the invalidate path (updateTag/revalidateTag)
@@ -57,14 +245,15 @@ export function normalizeTags(tags: Iterable<string>): string[] {
  *    cache" in its tree. This is PPR's DERIVATIVE invalidation: PPR is
  *    execution-PRESERVING (everything still runs underneath; only document bytes
  *    are shortcut), so its tags ride this existing instrument rather than a
- *    first-class ppr key/tag API. The shell-expiry invariant holds by
- *    construction — baked ⇒ evicts (bake-lane loaders execute during capture and
- *    record here), hole ⇒ fresh (masked loaders behind a renderable loading()
- *    never execute during capture, so nothing under a hole can tag the shell).
- *
- * Inside a cache() DSL segment the render-callable form records at the DOCUMENT
- * level, not the segment (only the "use cache" runtime enters the tag scope) — a
- * documented semantic, not a filtered one. An empty/whitespace-only tag is
+ *    first-class ppr key/tag API. Whatever renders into the shell records here,
+ *    at capture or on the route's cache() record the capture replays. A masked
+ *    live-lane loader never executes at capture, so its own tags reach a shell
+ *    only through a handler that reads it (ctx.use).
+ *
+ * Inside a route cache() boundary the render-callable form also tags that
+ * route's cache() record, which re-records it on every HIT (#957). A loader's
+ * tags reach the record only when a handler consumes its value (ctx.use);
+ * see runInSegmentTagScope / linkLoaderTags. An empty/whitespace-only tag is
  * dropped in both forms (the render-callable form silently, via normalizeTags in
  * recordRequestTags; the scope form with a dev warning).
  *
@@ -120,12 +309,187 @@ export function recordRequestTags(
   tags: Iterable<string> | undefined,
   ctx: RequestContext | undefined = _getRequestContext(),
 ): void {
+  recordOwnedTags(
+    tags,
+    ctx,
+    recordTagOwnersArmed(ctx) ? currentOwner() : undefined,
+  );
+}
+
+/**
+ * Recorded-tag sets (#964). A loader with its own cache() skips its body on a
+ * HIT, so its entry stores what its execution recorded, including the tags of
+ * every loader value it read, whoever ran that loader.
+ *
+ * Each loader execution records into its own set, held on its body scope
+ * (runInsideLoaderBodyScope); a loader-cache MISS opens one around its
+ * execution and value encodes (captureRecordedTags). The innermost wins. A
+ * read of a loader's value links the reader's set to the value's
+ * (readValueTags), and the entry write flattens the links
+ * (flattenRecordedTags) after its value settled.
+ *
+ * The per-execution sets and read links run only for a request that resolves
+ * a loader-cache binding (armLoaderTagSets); elsewhere a loader execution
+ * allocates no set and a read links nothing.
+ *
+ * The same sets carry the execution's request-identity reads (#972,
+ * recordLoaderIdentityRead in server/context.ts): an entry with no declared
+ * key refuses an execution whose links reach one (recordedIdentityRead).
+ */
+interface TagCapture {
+  into: Set<string>;
+  /** The loader body set active when the capture opened. */
+  outer: Set<string> | undefined;
+}
+// On globalThis like the loader scopes (server/context.ts): the identity-read
+// recorder is installed there too, so a second evaluated copy of this module
+// (a duplicated package, a dev re-evaluation) must share the capture scope and
+// the recorded reads, or its recorder writes where no fill looks.
+const recordedTagCapture: AsyncLocalStorage<TagCapture> = ((globalThis as any)[
+  Symbol.for("rangojs-router:recorded-tag-capture")
+] ??= new AsyncLocalStorage<TagCapture>());
+const tagLinks = new WeakMap<Set<string>, Set<Set<string>>>();
+const loaderValueTags = new WeakMap<object, Set<string>>();
+const identityReads: WeakMap<Set<string>, LoaderIdentityRead> = ((
+  globalThis as any
+)[Symbol.for("rangojs-router:identity-reads")] ??= new WeakMap());
+
+/**
+ * Arm the per-execution loader tag sets for `ctx`: its match resolved a
+ * loader bound with its own cache() (match-api.ts, bindsLoaderCache), or such
+ * a binding started (loader-cache.ts). A loader-cache MISS captures its own
+ * execution and encodes either way.
+ */
+export function armLoaderTagSets(
+  ctx: RequestContext | undefined = _getRequestContext(),
+): void {
+  if (ctx) ctx._recordLoaderTags = true;
+}
+
+/** Whether `ctx` records per-execution loader tag sets (armLoaderTagSets). */
+export function loaderTagSetsArmed(ctx: RequestContext | undefined): boolean {
+  return ctx?._recordLoaderTags === true;
+}
+
+function activeTagSet(): Set<string> | undefined {
+  const capture = recordedTagCapture.getStore();
+  const body = getLoaderBodyTags();
+  if (capture && capture.outer === body) return capture.into;
+  return body ?? capture?.into;
+}
+
+/**
+ * Call `fn`, adding every tag recorded in its async chain
+ * (recordRequestTags, recordLoaderTags) to `into`, until a loader body
+ * started inside it takes over with its own set.
+ */
+export function captureRecordedTags<T>(into: Set<string>, fn: () => T): T {
+  return recordedTagCapture.run({ into, outer: getLoaderBodyTags() }, fn);
+}
+
+/** `into` also answers for every tag `from` records. */
+export function linkRecordedTags(into: Set<string>, from: Set<string>): void {
+  if (into === from) return;
+  let links = tagLinks.get(into);
+  if (!links) tagLinks.set(into, (links = new Set()));
+  links.add(from);
+}
+
+/** Mark a loader's value promise as carrying `tags` (see readValueTags). */
+export function tagLoaderValue(value: object, tags: Set<string>): void {
+  loaderValueTags.set(value, tags);
+}
+
+/** A loader value's tags also answer for `tags` (tagLoaderValue). */
+export function linkValueTags(value: object, tags: Set<string>): void {
+  const own = loaderValueTags.get(value);
+  if (own) linkRecordedTags(own, tags);
+}
+
+/** The current execution reads a loader's value: it takes on its tags. */
+export function readValueTags(value: object): void {
+  const tags = loaderValueTags.get(value);
   if (!tags) return;
-  const set = ctx?._requestTags;
-  if (!set) return;
+  const into = activeTagSet();
+  if (into) linkRecordedTags(into, tags);
+}
+
+// recordLoaderIdentityRead (server/context.ts) calls this through the shared
+// key, not an import: a test mocking context.ts would break module init. First
+// read per execution: the fill's error names it.
+(globalThis as Record<symbol, unknown>)[
+  Symbol.for("rangojs-router:identity-read-recorder")
+] = (surface: string, verb: LoaderIdentityReadVerb): void => {
+  const set = activeTagSet();
+  if (set === undefined || identityReads.has(set)) return;
+  identityReads.set(set, { surface, verb, bodyId: getCurrentLoaderBodyId() });
+};
+
+/**
+ * A loader-cache HIT restores the read its entry's MISS recorded onto the
+ * value's set, so an unkeyed reader of the value refuses it as it would on
+ * the MISS (loader-cache.ts identity mark).
+ */
+export function markIdentityRead(
+  set: Set<string>,
+  read: LoaderIdentityRead,
+): void {
+  if (!identityReads.has(set)) identityReads.set(set, read);
+}
+
+/**
+ * The identity read `root`'s execution recorded, or one a set it links to
+ * recorded, nearest first (breadth-first, so the execution's own read wins).
+ */
+export function recordedIdentityRead(
+  root: Set<string>,
+): LoaderIdentityRead | undefined {
+  const seen = new Set<Set<string>>();
+  const queue = [root];
+  for (let i = 0; i < queue.length; i++) {
+    const set = queue[i]!;
+    if (seen.has(set)) continue;
+    seen.add(set);
+    const read = identityReads.get(set);
+    if (read) return read;
+    for (const linked of tagLinks.get(set) ?? []) queue.push(linked);
+  }
+  return undefined;
+}
+
+/** `root`'s tags plus those of every set it links to, transitively. */
+export function flattenRecordedTags(root: Set<string>): Set<string> {
+  const out = new Set<string>();
+  const seen = new Set<Set<string>>();
+  const pending = [root];
+  for (let set = pending.pop(); set !== undefined; set = pending.pop()) {
+    if (seen.has(set)) continue;
+    seen.add(set);
+    for (const tag of set) out.add(tag);
+    for (const linked of tagLinks.get(set) ?? []) pending.push(linked);
+  }
+  return out;
+}
+
+/** recordRequestTags, also recording onto `owner`'s set (#957). */
+function recordOwnedTags(
+  tags: Iterable<string> | undefined,
+  ctx: RequestContext | undefined,
+  owner: string | undefined,
+): void {
+  if (!tags || !ctx?._requestTags) return;
+  const set = ctx._requestTags;
+  const captured = activeTagSet();
+  let owned: Set<string> | undefined;
   for (const tag of tags) {
     const normalized = normalizeTag(tag);
-    if (normalized !== null) set.add(normalized);
+    if (normalized === null) continue;
+    set.add(normalized);
+    captured?.add(normalized);
+    if (owner !== undefined) {
+      owned ??= setFor(ownersFor(ctx).tags, owner);
+      owned.add(normalized);
+    }
   }
 }
 

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

@@ -7,9 +7,28 @@
 // (~65k). 8192 turns a per-byte concat loop into O(n/8192) apply calls.
 const FROM_CHARCODE_CHUNK = 8192;
 
+/**
+ * TC39 Uint8Array base64 methods (workerd, V8 >= 14; not Node 22/24). Same
+ * alphabet, padding, and invalid-character throw as btoa/atob, and about 15x
+ * faster than the per-byte loop on a 629 KB PPR prelude in workerd (0.05 ms vs
+ * 0.75 ms, issue #941). Looked up per call, not captured at import, so a
+ * polyfill or test spy installed later is the one that runs.
+ */
+type NativeUint8ArrayBase64 = {
+  fromBase64?: (b64: string) => Uint8Array;
+  prototype: { toBase64?: (this: Uint8Array) => string };
+};
+const NativeUint8Array = Uint8Array as unknown as NativeUint8ArrayBase64;
+
 /** Encode ArrayBuffer to base64 string. */
 export function bufferToBase64(buffer: ArrayBuffer): string {
-  const bytes = new Uint8Array(buffer);
+  return bytesToBase64(new Uint8Array(buffer));
+}
+
+/** Encode bytes (a view's own region only) to a base64 string. */
+export function bytesToBase64(bytes: Uint8Array): string {
+  const nativeToBase64 = NativeUint8Array.prototype.toBase64;
+  if (nativeToBase64) return nativeToBase64.call(bytes);
   // Build the binary (latin1) string in fixed-size chunks instead of one
   // String.fromCharCode per byte. Identical output to the per-byte loop (each
   // byte maps to the same code unit); just far fewer string concatenations for
@@ -22,12 +41,25 @@ export function bufferToBase64(buffer: ArrayBuffer): string {
   return btoa(binary);
 }
 
-/** Decode base64 string to ArrayBuffer. */
-export function base64ToBuffer(base64: string): ArrayBuffer {
+/** Decode a base64 string to bytes. Throws on a character outside the alphabet. */
+export function base64ToBytes(base64: string): Uint8Array {
+  if (NativeUint8Array.fromBase64) return NativeUint8Array.fromBase64(base64);
   const binary = atob(base64);
   const bytes = new Uint8Array(binary.length);
   for (let i = 0; i < binary.length; i++) {
     bytes[i] = binary.charCodeAt(i);
   }
-  return bytes.buffer;
+  return bytes;
+}
+
+/** The byte length `base64` decodes to (padded or not), without decoding. */
+export function base64ByteLength(base64: string): number {
+  let length = base64.length;
+  while (length > 0 && base64.charCodeAt(length - 1) === 61 /* = */) length--;
+  return Math.floor((length * 3) / 4);
+}
+
+/** Decode base64 string to ArrayBuffer. */
+export function base64ToBuffer(base64: string): ArrayBuffer {
+  return base64ToBytes(base64).buffer as ArrayBuffer;
 }

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

@@ -132,3 +132,15 @@ export const EDGE_READ_TIMEOUT_MS = 20;
  * Override per store via `CFCacheStoreOptions.kvReadTimeoutMs` (<= 0 disables).
  */
 export const KV_READ_TIMEOUT_MS = 170;
+
+/**
+ * Floor (ms) on the budget for reading a PPR shell's snapshot, the rest of a
+ * frame whose head and prelude were already read. A document HIT has sent
+ * its prelude by then and cannot render the rest without the snapshot's doc
+ * record, so a timed-out read degrades the HIT (the entry is replaced, the
+ * page reloads once into a MISS; rsc-rendering.ts degradeUnreplayableShell).
+ * That costs far more than waiting, so a slow body read gets at least this
+ * long; `kvReadTimeoutMs` above it wins, and `kvReadTimeoutMs <= 0` still
+ * disables the bound.
+ */
+export const SHELL_SNAPSHOT_READ_MIN_TIMEOUT_MS = 1000;