@rangojs/router 0.17.0 → 0.18.0

package/src/router/segment-resolution/loader-cache.ts

@@ -17,18 +17,36 @@
  * On stale hit (SWR): returns stale data, schedules background revalidation.
  * On miss: executes loader, schedules non-blocking cache write.
  *
+ * Identity (#972): without a key() or a store keyGenerator the entry is
+ * shared across users, so a fill whose execution recorded a request-identity
+ * read fails and is not stored, whoever started that execution
+ * (server/context.ts recordLoaderIdentityRead).
+ *
  * Handle pushes (`ctx.use(Handle)(...)` in the loader body) are a side effect
  * the HIT must reproduce: the MISS records the pushes of the body and of the
  * loaders it awaits via ctx.use into the entry's `handles` blob (the
  * "use cache" capture/encode), and every HIT — stale included — replays
  * them, each loader's pushes at most once per request (a dependency another
  * reader already ran keeps its live pushes). See replayLoaderHandles.
+ *
+ * Tags too (#964): the entry stores its cache() tags plus every tag its
+ * execution recorded, those of the loader values it read included
+ * (cache-tag.ts "Recorded-tag sets"), so updateTag() of any of them drops it.
+ * Every HIT records the stored tags through the loader's tag owner
+ * (recordLoaderTags), so a route cache() record, PPR shell or document built
+ * over the HIT carries them, and a loader that reads this one takes them on.
+ * Once the binding started, a loader body's ctx.use of it gets the same
+ * dataPromise as a handler read (createLoaderExecutor's useLoader); a stale
+ * refresh does not (setupLoaderAccess _runLoaderIsolated).
  */
 
 import {
   getCurrentLoaderBodyId,
   isInsideLoaderBody,
+  loaderCacheIdentityError,
+  type EntryData,
   type LoaderEntry,
+  type LoaderIdentityRead,
 } from "../../server/context.js";
 import type { HandlerContext, InternalHandlerContext } from "../../types.js";
 import type { HandleStore } from "../../server/handle-store.js";
@@ -59,7 +77,20 @@ import {
   maskNestedContainerThenables,
   overlayLoaderContainer,
 } from "./loader-snapshot.js";
-import { recordRequestTags } from "../../cache/cache-tag.js";
+import {
+  SHELL_BAKE_TAG_OWNER,
+  armLoaderTagSets,
+  captureRecordedTags,
+  flattenRecordedTags,
+  linkLoaderTags,
+  linkLoaderTagsTo,
+  linkRecordedTags,
+  markIdentityRead,
+  readValueTags,
+  recordedIdentityRead,
+  recordLoaderTags,
+  tagLoaderValue,
+} from "../../cache/cache-tag.js";
 import {
   isShellCaptureActive,
   createMaskedLoaderPromise,
@@ -98,7 +129,8 @@ function getDefaultLoaderCacheKey(
 }
 
 /**
- * Resolve cache key using the shared 3-tier priority.
+ * Resolve cache key using the shared 3-tier priority. `declared`: a key() or
+ * store keyGenerator produced it, so it can carry request identity (#972).
  */
 async function resolveLoaderKey(
   loaderEntry: LoaderEntry,
@@ -106,7 +138,7 @@ async function resolveLoaderKey(
   loaderId: string,
   pathname: string,
   params: Record<string, string>,
-): Promise<string> {
+): Promise<{ key: string; declared: boolean }> {
   const options = loaderEntry.cache!.options;
   // The host is part of the loader cache identity, matching the route-level
   // cache (cache-scope getCacheKeyBase: `${host}${pathname}`) and "use cache"
@@ -115,8 +147,11 @@ async function resolveLoaderKey(
   // loader data to another.
   const host = getRequestContext()?.url?.host ?? "localhost";
   const defaultKey = getDefaultLoaderCacheKey(loaderId, host, pathname, params);
-  if (options === false) return defaultKey;
-  return resolveCacheKey(options.key, store, defaultKey, "LoaderCache");
+  if (options === false) return { key: defaultKey, declared: false };
+  return {
+    key: await resolveCacheKey(options.key, store, defaultKey, "LoaderCache"),
+    declared: Boolean(options.key || store.keyGenerator),
+  };
 }
 
 /**
@@ -131,6 +166,39 @@ function resolveTags(loaderEntry: LoaderEntry): string[] | undefined {
   return resolveTagsOption(options.tags, getRequestContext(), "LoaderCache");
 }
 
+const bindsLoaderCacheMemo = new WeakMap<EntryData, boolean>();
+
+const hasLoaderCache = (loaders: readonly LoaderEntry[] | undefined) =>
+  loaders?.some((l) => l.cache !== undefined && l.cache.options !== false) ??
+  false;
+
+function entryBindsLoaderCache(entry: EntryData): boolean {
+  let binds = bindsLoaderCacheMemo.get(entry);
+  if (binds === undefined) {
+    binds =
+      hasLoaderCache(entry.loader) ||
+      (entry.intercept?.some((i) => hasLoaderCache(i.loader)) ?? false) ||
+      (entry.layout?.some(entryBindsLoaderCache) ?? false) ||
+      Object.values(entry.parallel ?? {}).some(
+        (p) => p !== undefined && entryBindsLoaderCache(p),
+      );
+    bindsLoaderCacheMemo.set(entry, binds);
+  }
+  return binds;
+}
+
+/**
+ * Whether a request over the matched chain `entries` resolves a loader bound
+ * with its own cache(): on a chain entry, or on its parallel slots, orphan
+ * layouts or intercepts. The match arms the per-execution loader tag sets on
+ * it (cache-tag.ts armLoaderTagSets), before any loader starts, so a
+ * dependency the handler or another binding starts first still records.
+ * Memoized per entry.
+ */
+export function bindsLoaderCache(entries: readonly EntryData[]): boolean {
+  return entries.some(entryBindsLoaderCache);
+}
+
 function getLoaderStore(
   loaderEntry: LoaderEntry,
 ): import("../../cache/types.js").SegmentCacheStore | null {
@@ -158,9 +226,10 @@ function getLoaderStore(
  * keyed on that body scope (executeLoaderData), which would swallow the
  * replay; and the store reads the body scope to tell a live push from a
  * replayed one.
- * Outside it, a PPR shell capture classifies replayed pushes as
- * loader-scoped and unbaked (shell-capture.ts), so a shell HIT gets them
- * from the loader's own re-run, not twice.
+ * A PPR shell capture records the replayed pushes under this loader (its
+ * push funnel reads the pushReplayed owner, shell-capture.ts), so a shell
+ * HIT restores them owned: the claim above then skips this replay when the
+ * loader runs on that HIT, and its live pushes replace the restored ones.
  */
 async function replayLoaderHandles(
   encoded: string,
@@ -187,6 +256,36 @@ async function replayLoaderHandles(
   }
 }
 
+/**
+ * Identity mark (#972): a declared-key entry whose MISS recorded a
+ * request-identity read stores that read ahead of its payload. A HIT skips the
+ * body, so without the mark an unkeyed loader reading this value on a HIT
+ * would store another user's data. The value string is this module's own
+ * (serialize/deserialize below), so the mark needs no store support; Flight
+ * and JSON payloads never start with "~".
+ */
+const IDENTITY_MARK = "~identity:";
+
+function markIdentity(
+  value: string,
+  read: LoaderIdentityRead | undefined,
+): string {
+  return read ? `${IDENTITY_MARK}${JSON.stringify(read)}\n${value}` : value;
+}
+
+function unmarkIdentity(value: string): {
+  read: LoaderIdentityRead | undefined;
+  payload: string;
+} {
+  if (!value.startsWith(IDENTITY_MARK))
+    return { read: undefined, payload: value };
+  const end = value.indexOf("\n");
+  return {
+    read: JSON.parse(value.slice(IDENTITY_MARK.length, end)),
+    payload: value.slice(end + 1),
+  };
+}
+
 /**
  * Record key for the MISS capture: run-length groups by the innermost loader
  * body, `${seq}:${loaderId}` — the cached loader or a dependency it awaits
@@ -226,18 +325,23 @@ function recordOwnerKey(cachedLoaderId: string): () => string {
  * never run under a shell capture), so the lane is decided here, per LOADER,
  * never by the entry's loading():
  *
- * - BAKE lane: `loader(Def, { ssr: false })` (awaitBeforeFlush) with a
- *   `bakeSegmentKey` from the caller. The loader EXECUTES at capture (the
+ * - BAKE lane: `loader(Def, { ssr: false })` (LoaderEntry `bake`: the
+ *   caller passes a `bakeSegmentKey` for it on document and navigation
+ *   evaluations alike; a capture, a document evaluation, also has
+ *   awaitBeforeFlush). The loader EXECUTES at capture (the
  *   flag's "data in the HTML before first flush" maps to the frozen prelude)
  *   and its settled non-promise data bakes into the shell. Promises nested in
- *   plain objects/arrays are masked (mask-nested.ts) and stay live holes at
- *   the consumer's own Suspense — per-request material must be promise-shaped
- *   (the #692 cross-session scar). The masked container registers on
- *   `_shellCaptureLoaderRecords`: it holds the capture gate (bounded by
- *   `ppr.captureTimeout`) and pins into the snapshot's loader family, and on a
- *   HIT the recorded container is overlaid onto the fresh run (below) so the
- *   payload matches the frozen prelude byte-for-byte. cookies()/headers() in
- *   its body (nested promise bodies included) trip the capture guard.
+ *   plain objects, arrays and JSX props are masked (mask-nested.ts) and stay
+ *   live holes at the consumer's own Suspense — per-request material must be
+ *   promise-shaped (the #692 cross-session scar). The masked container
+ *   registers on `_shellCaptureLoaderRecords`: it holds the capture gate
+ *   (bounded by `ppr.captureTimeout`) and pins into the snapshot's loader
+ *   family, and on a HIT the recorded container is overlaid onto the fresh
+ *   run (below) so the payload matches the frozen prelude outside the holes.
+ *   A server-component element holding a promise is a hole as a whole, so its
+ *   other props come from the fresh run (loader-snapshot.ts
+ *   elideLoaderContainer). cookies()/headers() in its body (nested promise
+ *   bodies included) trip the capture guard.
  * - LIVE lane: every other loader, whatever its entry's loading(). Never
  *   executes at capture: the slot gets a never-resolving promise
  *   (loader-mask.ts) and postpones at the reader's boundary — loading() or an
@@ -269,6 +373,8 @@ export function resolveLoaderData<TEnv>(
       );
       maskedPromise.catch(() => {});
       reqCtx?._shellCaptureLoaderRecords?.set(bakeSegmentKey, maskedPromise);
+      // Its data bakes into the shell, so its tags tag the shell.
+      linkLoaderTagsTo(SHELL_BAKE_TAG_OWNER, loaderEntry.loader.$$id, reqCtx);
       return maskedPromise;
     }
     return createMaskedLoaderPromise();
@@ -280,31 +386,31 @@ export function resolveLoaderData<TEnv>(
       const recorded = seed.get(bakeSegmentKey)!;
       if (!recorded.holes) {
         // Pin-first (hole-free record): the pinned container is what the
-        // payload serves either way (recorded paths win wholesale), so
-        // resolve it immediately instead of gating on the fresh run's
-        // latency — a slow bake-lane loader body otherwise stalls the HIT
-        // tail for values that get discarded. The fresh run still executes
-        // for its side effects and cache read-through writes, lifetime-
-        // extended so the runtime cannot cancel it when the stream closes
-        // first; its rejection is swallowed here (the payload already
-        // matches the prelude, which a fresh error value never could).
+        // payload serves (recorded paths win wholesale), resolved
+        // immediately. The body does not run: a HIT is rendered from the
+        // shell, like the handlers it replays, and the loader's settled
+        // pushes (and those of loaders it awaits) are restored from the
+        // record. Only a record whose capture saw a push it could not keep
+        // (`runs`) still runs the body, in the background, lifetime-extended
+        // so the runtime cannot cancel it when the stream closes first; its
+        // rejection is swallowed (the payload already matches the prelude,
+        // which a fresh error value never could).
         //
         // CONTRACT (deliberate divergence from the gated overlay's
         // fresh-only-keys passthrough): a hole-free pin serves the pinned
-        // SHAPE wholesale — a key the fresh run adds mid-TTL is dropped.
-        // It could never render server-side anyway: no hole was postponed
-        // for it at capture, so the prelude froze the without-that-field
-        // branch and the resume pass has nothing to fill; passing it
-        // through only made the hydration payload disagree with the frozen
-        // prelude (client-side mismatch repair — the divergence class the
-        // snapshot exists to prevent). A field that is per-request must be
-        // promise-shaped at capture (masked -> hole marker -> holes: 1 ->
-        // the gated path below, which preserves fresh-only passthrough) or
-        // live behind loading(). Anything else is uncached nondeterminism
-        // in shell material — the documented drift residual.
-        const fresh = executeLoaderData(loaderEntry, ctx, pathname);
-        fresh.catch(() => {});
-        reqCtx?.executionContext?.waitUntil?.(fresh);
+        // SHAPE wholesale. A field the body would return now had no hole
+        // postponed for it at capture, so the prelude froze the
+        // without-that-field branch and the resume pass has nothing to
+        // fill. A field that is per-request must be promise-shaped at
+        // capture (masked -> hole marker -> holes: 1 -> the gated path
+        // below, which preserves fresh-only passthrough) or live behind
+        // loading(). Anything else is uncached nondeterminism in shell
+        // material — the documented drift residual.
+        if (recorded.runs) {
+          const fresh = executeLoaderData(loaderEntry, ctx, pathname);
+          fresh.catch(() => {});
+          reqCtx?.executionContext?.waitUntil?.(fresh);
+        }
         return Promise.resolve(
           overlayLoaderContainer(undefined, recorded.container),
         );
@@ -368,7 +474,13 @@ function executeLoaderData<TEnv>(
     internal._loaderCacheOriginalUse = originalUse;
     ctx.use = ((item: any) => {
       const cached = overrides!.get(item?.$$id);
-      if (cached) return cached;
+      if (cached) {
+        // A read is a consumption (#957, #964): see createLoaderExecutor's
+        // useLoader.
+        linkLoaderTags(item.$$id);
+        readValueTags(cached);
+        return cached;
+      }
       return originalUse(item);
     }) as typeof ctx.use;
   }
@@ -395,7 +507,17 @@ function executeLoaderData<TEnv>(
   const swrWindow = resolveSwrWindow(options.swr, store.defaults);
   const swr = swrWindow || undefined;
   const tags = resolveTags(loaderEntry);
-  recordRequestTags(tags);
+  recordLoaderTags(loaderId, tags);
+  // Production arms at match, before any loader runs (match-api.ts,
+  // bindsLoaderCache); no production path relies on this. It only keeps a
+  // resolveLoaders call outside a match from running unarmed after this
+  // point (loaders it started earlier stay unrecorded).
+  armLoaderTagSets();
+  // An execution of this loader outside the binding (a reader started it
+  // first, a stale refresh) answers for the cache() tags too.
+  if (tags && tags.length > 0) {
+    internal._bindLoaderCacheTags?.(loaderId, new Set(tags));
+  }
 
   // Handle pushes: the store and the owning segment are read synchronously
   // at kickoff, as createLoaderExecutor does for the body's own pushes.
@@ -406,10 +528,14 @@ function executeLoaderData<TEnv>(
   // concurrently. A dependency can still run on a HIT for another reader
   // (memoized per request); the replay's claim keeps its pushes to one copy.
   const isOwnBodyPush = () => isInsideLoaderBody(loaderId);
+  // What a reader of this value takes on (tagLoaderValue below,
+  // readValueTags): the cache() tags, plus the entry's tags on a HIT or the
+  // execution's on a MISS.
+  const valueTags = new Set(tags);
 
   const dataPromise = (async () => {
     const codec = await getCodec();
-    const key = await resolveLoaderKey(
+    const { key, declared } = await resolveLoaderKey(
       loaderEntry,
       store,
       loaderId,
@@ -428,15 +554,21 @@ function executeLoaderData<TEnv>(
 
     // One readThroughItem call runs at most one execution — the foreground
     // MISS or the background stale revalidation (flagged by wrapBackground)
-    // — so a single capture slot serves the setItem that follows it.
+    // — so one handle capture and one tag set serve the setItem after it.
+    // The entry's tags: its cache() tags plus what the execution recorded.
     let capture: HandleCapture | undefined;
+    const bodyTags = new Set(tags);
     let revalidating = false;
     let hitHandles: string | undefined;
     const onCachedRead = (label: string, cached: CacheItemResult) => {
       hitHandles = cached.handles;
+      const { read } = unmarkIdentity(cached.value);
+      if (read) markIdentityRead(valueTags, read);
+      recordLoaderTags(loaderId, cached.tags);
+      for (const tag of cached.tags ?? []) valueTags.add(tag);
       debugLoaderCacheLog(`[LoaderCache] ${label}: ${key}`);
     };
-    const execute = async (): Promise<any> => {
+    const runBody = async (): Promise<any> => {
       // A stale-hit revalidation runs on its own executor: it diverts its
       // pushes (below), so sharing the page's memoized run of a dependency
       // would take that dependency's pushes off the page.
@@ -457,6 +589,26 @@ function executeLoaderData<TEnv>(
         c.stop();
       }
     };
+    // #972: the execution's identity reads, and those of the loader values it
+    // read, are on the bodyTags links whoever started them. With an undeclared
+    // key one fails the fill (the MISS or the stale refresh); one that settles
+    // after the value (a nested promise, a pending handle push) skips the write
+    // instead. With a declared key it is stored as the entry's identity mark
+    // for the HITs, as this loader's readers see it (through this loader when
+    // another made it), and a foreground execution marks the value it serves.
+    // A stale refresh does not: the page is served the stale entry, which its
+    // own mark (or its lack) describes.
+    const identityRead = (): LoaderIdentityRead | undefined => {
+      const read = recordedIdentityRead(bodyTags);
+      if (!read) return undefined;
+      if (!declared) throw loaderCacheIdentityError(read, loaderId);
+      const seen =
+        read.bodyId === undefined || read.bodyId === loaderId
+          ? { ...read, bodyId: loaderId, via: undefined }
+          : { ...read, via: loaderId };
+      if (!revalidating) markIdentityRead(valueTags, seen);
+      return seen;
+    };
 
     // Flight encodes a rejected promise in the value or a handle push as an
     // error row and completes normally. setItem runs after serialize and
@@ -473,15 +625,27 @@ function executeLoaderData<TEnv>(
       // pushes awaited up to its timeout, the whole blob dropped on a timeout
       // or a thrown encode). Encoded here, inside the deferred write, so a
       // MISS response never waits on it.
-      setItem: async (k, v, o) => {
-        const handles = capture
-          ? await encodeHandles(capture.data, onFlightError)
-          : "";
-        if (flightErrors.length > 0) throw flightErrors[0];
-        await store.setItem!(k, v, handles ? { ...o, handles } : o);
-      },
+      setItem: (k, v, o) =>
+        captureRecordedTags(bodyTags, async () => {
+          const handles = capture
+            ? await encodeHandles(capture.data, onFlightError)
+            : "";
+          if (flightErrors.length > 0) throw flightErrors[0];
+          // After the handle encode: it settles pending pushes, which can read.
+          const read = identityRead();
+          const entryTags = [...flattenRecordedTags(bodyTags)];
+          await store.setItem!(k, markIdentity(v, read), {
+            ...o,
+            tags: entryTags.length > 0 ? entryTags : undefined,
+            ...(handles ? { handles } : {}),
+          });
+        }),
       key,
-      execute,
+      execute: async () => {
+        const value = await captureRecordedTags(bodyTags, runBody);
+        identityRead();
+        return value;
+      },
       // The rango.background span (kind=loader-revalidation) wraps the WHOLE
       // stale revalidation — the re-execution AND the serialize/setItem write
       // (read-through-swr routes the full task through wrapBackground) — so
@@ -495,12 +659,18 @@ function executeLoaderData<TEnv>(
           observePhase(PHASES.background("loader-revalidation"), run),
         );
       },
-      serialize: (d) => codec.serializeResult(d, onFlightError),
-      deserialize: (v) => codec.deserializeResult(v),
+      serialize: (d) =>
+        captureRecordedTags(bodyTags, () =>
+          codec.serializeResult(d, onFlightError),
+        ),
+      deserialize: (v) => codec.deserializeResult(unmarkIdentity(v).payload),
       storeOptions: { ttl, swr, tags },
       onHit: (cached) => onCachedRead("HIT", cached),
       onStale: (cached) => onCachedRead("STALE", cached),
-      onMiss: () => debugLoaderCacheLog(`[LoaderCache] MISS: ${key}`),
+      onMiss: () => {
+        linkRecordedTags(valueTags, bodyTags);
+        debugLoaderCacheLog(`[LoaderCache] MISS: ${key}`);
+      },
       onCached: () => debugLoaderCacheLog(`[LoaderCache] Cached: ${key}`),
       host: requestCtxForExecute,
     });
@@ -522,6 +692,7 @@ function executeLoaderData<TEnv>(
   // push after full drain throws LateHandlePushError.
   handleStore?.trackAuxiliary(dataPromise);
 
+  tagLoaderValue(dataPromise, valueTags);
   overrides.set(loaderId, dataPromise);
 
   return dataPromise;