@rangojs/router 0.18.0 → 0.19.1

package/src/server/context.ts

@@ -1,3 +1,4 @@
+import type { ServerRouteLocation } from "../types/segments.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { ReactNode } from "react";
 import type {
@@ -15,8 +16,9 @@ import type { DefaultRouteName } from "../types/global-namespace.js";
 import type { ContextVar } from "../context-var.js";
 import { PPR_LANE_HINT } from "../rsc/shell-capture-constants.js";
 import {
-  getCacheExecScope,
-  type CacheExecScope,
+  endIdentityExempt,
+  isInsideCacheExecScope,
+  isInsideIdentityExempt,
 } from "../cache/cache-exec-scope.js";
 
 // ============================================================================
@@ -163,20 +165,22 @@ export type InterceptSegmentsState = {
  * Context passed to intercept selector functions (when())
  * Contains navigation context to determine if interception should occur.
  *
+ * `from` / `to` have the shape transition({ when }) sees, without `state`:
+ * history state never reaches the server.
+ *
  * Note: when() is evaluated during route matching, BEFORE middleware runs.
  * So ctx.get()/ctx.use() are not available, but env (platform bindings) is.
  *
  * @internal This type is an implementation detail and may change without notice.
  */
 export type InterceptSelectorContext<TEnv = any> = {
-  from: URL; // Source URL (where user is coming from)
-  to: URL; // Destination URL (where user is navigating to)
-  params: Record<string, string>; // Matched route params
+  /** Where the navigation comes from: the intercept source while one is open. */
+  from: ServerRouteLocation;
+  /** The navigation target. */
+  to: ServerRouteLocation;
   request: Request; // The HTTP request object
   env: TEnv; // Platform bindings (Cloudflare env, etc.)
   segments: InterceptSegmentsState; // Client's current segments (where navigating FROM)
-  fromRouteName?: DefaultRouteName; // Named route being navigated away from (undefined for unnamed routes)
-  toRouteName?: DefaultRouteName; // Named route being navigated to (undefined for unnamed routes)
 };
 
 /**
@@ -546,7 +550,8 @@ export const getContext = (): {
           // the header guard's middleware exemption depends on the latch dying
           // with the funnel scope (see assertCachedHeaderWriteAllowed).
         },
-        callback,
+        // A funnel (its cache() scope) never runs exempt (runIdentityExempt).
+        () => endIdentityExempt(callback),
       );
     },
     run: <T>(
@@ -865,8 +870,6 @@ interface LoaderBodyScope {
   loaderId?: string;
   /** The body scope this one was entered from (a ctx.use(Loader) chain). */
   parent?: LoaderBodyScope;
-  /** The "use cache" scope the body was entered in (assertNonCacheableReadAllowed). */
-  execScope?: CacheExecScope;
   /** The tags this execution records (#964, cache-tag.ts "Recorded-tag sets"). */
   tags?: Set<string>;
 }
@@ -896,84 +899,133 @@ export function isInsideCacheScope(): boolean {
 }
 
 /**
- * Throw if called during the ACTIVE background shell-capture render
- * (`_shellCaptureRun` true on the derived request context built by
- * shell-capture.ts). The captured shell is shared across every user hitting
- * the URL, so a request-scoped read here would bake one user's cookies,
- * headers, or per-request variables into markup served to others — same
- * hazard as the cache scopes above, at the document tier. DSL segment loaders
- * need no exemption: the live lane is masked (never executed) during capture,
- * and the bake lane is exactly what this guard exists for.
- *
- * It covers everything the capture waits for, not only synchronous handler
- * code: a promise the handler passes or pushes, an async server component,
- * and a loader the handler awaits (`await ctx.use(Loader)`) all run under the
- * capture context and all bake. The last one used to be exempt (the
- * consumption-lane rule, #672/#674): while a HIT re-ran handlers, a slot
- * handler's `ctx.use` of an identity loader rendered per visitor on the HIT.
- * Now every HIT replays the capture's copy, so the exemption would bake the
- * capturing request's identity into every visitor's page. The cache()
- * guards above keep it (a cache() HIT is a separate tier).
- *
- * Keys off `_shellCaptureRun`, NOT the `_shellCapture` descriptor: the descriptor
- * is also present during the FOREGROUND render (it means "a capture is wanted"),
- * and the foreground must read cookies/headers normally to serve the real user.
- * Only the derived capture context sets `_shellCaptureRun`.
+ * What a refused identity read says (guardIdentityRead): its `verb`, and per
+ * refusing scope the text after "<surface> cannot be <verb> ...": why the
+ * value must not reach that scope, and what to do instead. `fix.warning` is
+ * the fix the capture's refusal warning gives (shell-capture.ts
+ * refuseOnCaptureGuard).
+ */
+export interface IdentityReadWording {
+  /** "called" for a function (cookies(), ctx.get()), "read" for a property (the theme getters). */
+  verb: LoaderIdentityReadVerb;
+  fix: {
+    useCache: string;
+    cacheScope: string;
+    capture: string;
+    warning: string;
+  };
+  /**
+   * False when the read is recorded later, by the returned view's read
+   * methods (cookies(), headers()): a view taken outside a loader and read
+   * inside one still counts, and a cookie write alone is not a read.
+   */
+  record?: false;
+}
+
+/**
+ * The one guard every request-identity read goes through: cookies(),
+ * headers(), the theme reads (cookie-store.ts readGuardedTheme), a
+ * non-cacheable ctx.get() (assertNonCacheableReadAllowed), and the raw reads
+ * `ctx.request.headers` and `getRequestContext().cookie()` / `.cookies()`
+ * (cookie-store.ts guardRequestHeaders, guardRawCookieRead; #976). Each surface keeps
+ * its own wording; the ladder and its exemptions are shared, so the surfaces
+ * refuse in exactly the same places:
  *
- * Applies only to the READ surfaces (cookies(), headers(), a { cache: false }
- * variable, and the theme reads through tripShellCaptureGuard) whose values
- * become markup. Response directives
- * (invalidateClientCache(), keepClientCache()) stay callable: during capture
- * they are header effects on a discarded response, and on the live HIT path
- * the full pipeline runs so their headers flow to the client normally.
+ * 0. A cache's own key(), store keyGenerator, condition() and tags(), and
+ *    onError, read freely and record nothing (runIdentityExempt,
+ *    cache/cache-exec-scope.ts): the value picks or labels the entry, or is
+ *    only observed; it is never rendered. A cached body, loader body or
+ *    funnel they start is guarded again.
+ * 1. A PPR shell capture (`ctx` is the capture's derived context,
+ *    `_shellCaptureRun`) trips first: the capture context is flagged (so a
+ *    caught throw still refuses the capture) and the read throws. The shell is
+ *    shared per host+URL, and every HIT replays what the capture read. There
+ *    is no loader-body exemption here: a bake-lane loader and a loader a
+ *    handler awaits both bake.
+ * 2. A "use cache" body throws: the key does not include the value, so the
+ *    first caller's would be stored and served to later callers. That holds
+ *    for a loader body entered inside the cached function too (`await
+ *    ctx.use(Loader)` there): its value is part of what the function returns.
+ *    Before, a non-cacheable ctx.get() there was exempt while cookies() threw,
+ *    and the entry stored the first request's value.
+ * 3. A cache() boundary throws, except inside a loader body
+ *    (isInsideCacheScope): a route cache() never stores loader values.
+ * 4. The read is allowed, and recorded on the current loader execution for a
+ *    loader cache() fill without key() (#972, recordLoaderIdentityRead)
+ *    unless `wording.record` defers it to the returned view.
  *
- * The throw can be caught by the code that made the read, so the guard also
- * flags the capture context; the capture refuses on the flag
- * (shell-capture.ts refuseOnCaptureGuard), nothing is stored, and every
- * request keeps getting the normal axis-1 render.
+ * Outside these scopes every read is allowed, a live loader's included. The
+ * response directives (invalidateClientCache(), keepClientCache()) record
+ * nothing and are not captured reads: they take refuseInCacheScope alone.
  */
-export function assertNotInsideShellCapture(
+export function guardIdentityRead(
   ctx: unknown,
-  fnName: string,
+  surface: string,
+  wording: IdentityReadWording,
 ): void {
-  if (!tripShellCaptureGuard(ctx, `${fnName}()`, REQUEST_READ_CAPTURE_FIX)) {
-    return;
+  if (isInsideIdentityExempt()) return;
+  const { verb, fix } = wording;
+  if (tripShellCaptureGuard(ctx, surface, fix.warning)) {
+    throw new Error(
+      `${surface} cannot be ${verb} while capturing a shared shell ` +
+        `(ppr shell capture). ${fix.capture}`,
+    );
   }
-  const what =
-    fnName === "cookies"
-      ? "cookies"
-      : fnName === "headers"
-        ? "headers"
-        : "per-request variables";
-  throw new Error(
-    `${fnName}() cannot be called while capturing a shared shell ` +
-      `(ppr shell capture). The captured shell is served to every user ` +
-      `of this URL, so request-scoped data read here would leak one user's ` +
-      `${what} to others. Read it ` +
-      `inside a loader without ssr: false and consume it with useLoader, e.g. ` +
-      `createLoader(async () => getUser(cookies().get("session")?.value)). ` +
-      PPR_LANE_HINT,
-  );
+  refuseInCacheScope(surface, wording);
+  if (wording.record !== false) recordLoaderIdentityRead(surface, verb);
 }
 
 /**
- * The fix the capture refusal warning (shell-capture.ts refuseOnCaptureGuard)
- * gives for a cookies()/headers()/{ cache: false } variable read. Recorded
- * with the trip (tripShellCaptureGuard), so each guarded read carries its own
- * fix; the theme reads (cookie-store.ts assertThemeReadAllowed) record theirs.
+ * Steps 2 and 3 of guardIdentityRead: throw when a "use cache" body or a
+ * cache() boundary would store what `surface` produces.
  */
-const REQUEST_READ_CAPTURE_FIX: string =
-  "Read it in a loader without ssr: false and consume it with useLoader under " +
-  "loading() or an inline <Suspense> (a live hole). A promise the handler passes " +
-  "or pushes does not help: the capture waits for it.";
+export function refuseInCacheScope(
+  surface: string,
+  { verb, fix }: IdentityReadWording,
+): void {
+  if (isInsideCacheExecScope()) {
+    throw new Error(
+      `${surface} cannot be ${verb} inside a "use cache" function. ${fix.useCache}`,
+    );
+  }
+  if (isInsideCacheScope()) {
+    throw new Error(
+      `${surface} cannot be ${verb} inside a cache() boundary. ${fix.cacheScope}`,
+    );
+  }
+}
 
 /**
- * True when `ctx` is the active capture render (assertNotInsideShellCapture
- * above). On true the capture context is flagged with the read (`surface`,
- * e.g. "cookies()", "ctx.theme") and the fix the refusal warning gives, plus
- * the loader body (if any) that made the read, and the caller throws.
+ * The capture refusal for a request-scoped read (cookies(), headers(), a
+ * { cache: false } variable): the message after the surface, and the fix the
+ * refusal warning gives. `what` names the data that would leak.
  */
-export function tripShellCaptureGuard(
+export function requestReadCaptureFix(
+  what: string,
+): Pick<IdentityReadWording["fix"], "capture" | "warning"> {
+  return {
+    capture:
+      `The captured shell is served to every user of this URL, so ` +
+      `request-scoped data read here would leak one user's ${what} to ` +
+      `others. Read it inside a loader without ssr: false and consume it ` +
+      `with useLoader, e.g. createLoader(async () => ` +
+      `getUser(cookies().get("session")?.value)). ${PPR_LANE_HINT}`,
+    warning:
+      "Read it in a loader without ssr: false and consume it with useLoader " +
+      "under loading() or an inline <Suspense> (a live hole). A promise the " +
+      "handler passes or pushes does not help: the capture waits for it.",
+  };
+}
+
+/**
+ * True when `ctx` is the active capture render: the derived request context
+ * shell-capture.ts builds (`_shellCaptureRun`), which only the capture sets,
+ * so the foreground render reads identity normally to serve the real user.
+ * On true the capture context is flagged with the read (`surface`, e.g.
+ * "cookies()", "ctx.theme"), the fix the refusal warning gives, and the loader
+ * body (if any) that made the read, and the caller throws.
+ */
+function tripShellCaptureGuard(
   ctx: unknown,
   surface: string,
   fix: string,
@@ -996,50 +1048,40 @@ export function tripShellCaptureGuard(
   return true;
 }
 
+const NON_CACHEABLE_READ: IdentityReadWording = {
+  verb: "called",
+  fix: {
+    useCache:
+      "The variable was created with { cache: false } or set with " +
+      "{ cache: false }, and the cache key does not include its value, so " +
+      "the first caller's value would be served to later callers. Read it " +
+      "before calling the cached function and pass the value in as an " +
+      "argument so it becomes part of the cache key.",
+    cacheScope:
+      "The variable was created with { cache: false } or set with " +
+      "{ cache: false }, and its value would be stale on cache hit. Move the " +
+      "read outside the cached scope.",
+    ...requestReadCaptureFix("per-request variables"),
+  },
+};
+
 /**
  * Read guard for a non-cacheable variable (`createVar({ cache: false })` or a
- * `ctx.set(..., { cache: false })` write). Callers check isNonCacheable() first
- * so ordinary reads never reach the scope lookups.
- *
- * Throws during a PPR shell capture (`requestCtx` is the ambient request
- * context; assertNotInsideShellCapture): the shell is shared per host+URL.
- *
- * Throws inside a "use cache" body: the key does not include the value, so the
- * first caller's value would be stored and served to later callers (#925). A
- * loader body entered INSIDE the cached function is exempt, the same baked-copy
- * trade isInsideCacheScope() makes for cache(). A cached function called FROM a
- * loader is not: the loader re-runs, the cached body does not. The body scope
- * records the exec scope it was entered in, so the exemption holds only while
- * that is still the innermost one.
+ * `ctx.set(..., { cache: false })` write), through guardIdentityRead.
+ * Callers check isNonCacheable() first so ordinary reads never reach the
+ * scope lookups. `requestCtx` is the ambient request context, whose capture
+ * flag the guard reads.
  */
 export function assertNonCacheableReadAllowed(
   keyOrVar: string | ContextVar<unknown>,
   requestCtx?: unknown,
 ): void {
-  // A shell capture bakes what it reads into a page every visitor gets.
-  assertNotInsideShellCapture(requestCtx, "ctx.get");
-  const execScope = getCacheExecScope();
-  const variable = ` for a non-cacheable variable${typeof keyOrVar === "string" ? ` "${keyOrVar}"` : ""}`;
-  if (
-    execScope !== undefined &&
-    loaderBodyScopeALS.getStore()?.execScope !== execScope
-  ) {
-    throw new Error(
-      `ctx.get()${variable} cannot be called inside a "use cache" function. ` +
-        `The variable was created with { cache: false } or set with { cache: false }, ` +
-        `and the cache key does not include its value, so the first caller's value ` +
-        `would be served to later callers. Read it before calling the cached function ` +
-        `and pass the value in as an argument so it becomes part of the cache key.`,
-    );
-  }
-  if (isInsideCacheScope()) {
-    throw new Error(
-      `ctx.get() for a non-cacheable variable cannot be called inside a cache() boundary. ` +
-        `The variable was created with { cache: false } or set with { cache: false }, ` +
-        `and its value would be stale on cache hit. Move the read outside the cached scope.`,
-    );
-  }
-  recordLoaderIdentityRead(`ctx.get()${variable}`);
+  const name = typeof keyOrVar === "string" ? ` "${keyOrVar}"` : "";
+  guardIdentityRead(
+    requestCtx,
+    `ctx.get() for a non-cacheable variable${name}`,
+    NON_CACHEABLE_READ,
+  );
 }
 
 /** How the identity error words a read: a function call or a property read. */
@@ -1089,17 +1131,91 @@ const IDENTITY_READ_RECORDER_KEY = Symbol.for(
  * (cache-tag.ts recordedIdentityRead), so both orders fail the same way.
  * Response directives do not record: a key cannot make a skipped body's side
  * effect reach a HIT.
+ *
+ * The read also lands on the execution's LoaderRunIdentity (#1011), which
+ * every execution has, from either loader runner (runInsideLoaderRun).
  */
 export function recordLoaderIdentityRead(
   surface: string,
   verb: LoaderIdentityReadVerb = "called",
 ): void {
+  if (isInsideIdentityExempt()) return;
+  const run = loaderRunALS.getStore();
+  if (run && run.read === undefined) {
+    run.read = { surface, verb, bodyId: run.loaderId };
+  }
   const recorder = (globalThis as Record<symbol, unknown>)[
     IDENTITY_READ_RECORDER_KEY
   ] as ((surface: string, verb: LoaderIdentityReadVerb) => void) | undefined;
   recorder?.(surface, verb);
 }
 
+/**
+ * One loader execution's request-identity record (#1011): the first identity
+ * read its body made, and the executions whose values it read with
+ * ctx.use(Loader). Every execution has one; the recorded-tag sets that carry
+ * the same reads for a loader cache() fill (cache-tag.ts) exist only in a
+ * request that binds one.
+ *
+ * A "use cache" function that reads a loader's value through the request
+ * memo (a handler, the route's loader() binding or a parent layout's started
+ * it first) does not run the body, so guardIdentityRead never sees the read.
+ * Scar: the entry, keyed without the cookie, stored the first visitor's value
+ * and served it to the next. cache-tag.ts readStartedLoaderValue refuses such
+ * a value through this record.
+ */
+export interface LoaderRunIdentity {
+  readonly loaderId: string;
+  read?: LoaderIdentityRead;
+  reads?: Set<LoaderRunIdentity>;
+}
+
+// Its own scope, not a LoaderBodyScope field: the request-context runner
+// (request-context.ts createUseFunction) records reads too, but does not
+// enter a loader body scope, whose cache() exemption it never had.
+const loaderRunALS: AsyncLocalStorage<LoaderRunIdentity> = ((globalThis as any)[
+  Symbol.for("rangojs-router:loader-run-identity")
+] ??= new AsyncLocalStorage<LoaderRunIdentity>());
+
+/**
+ * Run a loader body with `run` as its identity record: both loader runners
+ * (loader-resolution.ts createLoaderExecutor, request-context.ts
+ * createUseFunction) enter it around the loader function.
+ */
+export function runInsideLoaderRun<T>(run: LoaderRunIdentity, fn: () => T): T {
+  return loaderRunALS.run(run, fn);
+}
+
+/** The innermost loader execution's identity record (runInsideLoaderRun). */
+export function getLoaderRunIdentity(): LoaderRunIdentity | undefined {
+  return loaderRunALS.getStore();
+}
+
+/**
+ * The error a "use cache" function's read of a loader value fails with when
+ * the loader's execution, or one whose value it read, made `read` (#1011).
+ * Worded like guardIdentityRead's "use cache" refusal, naming the loaders.
+ */
+export function useCacheLoaderIdentityError(
+  read: LoaderIdentityRead,
+  loaderId: string,
+): Error {
+  const bodyId = read.bodyId ?? loaderId;
+  const source =
+    bodyId === loaderId
+      ? `Loader "${loaderId}" ${read.verb} it, and the cached function reads that loader's value`
+      : `Loader "${bodyId}" ${read.verb} it, and the cached function reads loader "${loaderId}", whose value is built from it`;
+  return new Error(
+    `${read.surface} cannot be ${read.verb} inside a "use cache" function. ` +
+      `${source}. The loader ran outside the function (a handler or a ` +
+      `loader() binding started it first), but its value becomes part of ` +
+      `what the function returns, and the cache key does not include it, so ` +
+      `the first caller's value would be stored and served to later callers. ` +
+      `Read the loader before calling the cached function and pass the value ` +
+      `in as an argument so it becomes part of the cache key.`,
+  );
+}
+
 /** The error a loader cache() fill with no declared key fails with (#972). */
 export function loaderCacheIdentityError(
   read: LoaderIdentityRead,
@@ -1296,25 +1412,30 @@ export function runInsideLoaderScope<T>(fn: () => T): T {
 
 /**
  * Run `fn` inside a loader BODY scope. Marks loader-function execution for the
- * cache-purity guard only (isInsideCacheScope), WITHOUT affecting
+ * cache() purity guard only (isInsideCacheScope), WITHOUT affecting
  * isInsideLoaderScope()/rendered() gating. Applied to every loader body (DSL
  * and handler-invoked via ctx.use) so request-scoped reads inside a loader
- * never trip the cache-scope guards — loaders always run fresh.
+ * never trip the cache() guard — a route cache() never stores loader values.
+ * A "use cache" body the loader was entered in still refuses them
+ * (guardIdentityRead); one that reads the value later refuses what the run
+ * recorded (runInsideLoaderRun, cache-tag.ts readStartedLoaderValue).
  */
 export function runInsideLoaderBodyScope<T>(
   fn: () => T,
   loaderId?: string,
   tags?: Set<string>,
 ): T {
-  return loaderBodyScopeALS.run(
-    {
-      active: true,
-      loaderId,
-      parent: loaderBodyScopeALS.getStore(),
-      execScope: getCacheExecScope(),
-      tags,
-    },
-    fn,
+  // A loader a key() starts with ctx.use() runs guarded (runIdentityExempt).
+  return endIdentityExempt(() =>
+    loaderBodyScopeALS.run(
+      {
+        active: true,
+        loaderId,
+        parent: loaderBodyScopeALS.getStore(),
+        tags,
+      },
+      fn,
+    ),
   );
 }
 
@@ -1326,7 +1447,7 @@ export function getLoaderBodyTags(): Set<string> | undefined {
 /**
  * The $$id of the loader whose body is currently executing, or undefined
  * outside any loader body. Used by the shell-capture identity guard
- * (assertNotInsideShellCapture) so its refusal warning can name the loader that read
+ * (guardIdentityRead) so its refusal warning can name the loader that read
  * cookies()/headers() instead of blaming a lane it cannot see — the old
  * hardcoded "bake-lane loader" text misled a live-lane debugging session
  * (issue #672, secondary).
@@ -1335,6 +1456,24 @@ export function getCurrentLoaderBodyId(): string | undefined {
   return loaderBodyScopeALS.getStore()?.loaderId;
 }
 
+/**
+ * The innermost loader body running here, or around it through the
+ * ctx.use(Loader) chain, whose id `match` accepts (HandleStore.push, the
+ * shell capture's push funnel). A body `stop` accepts, and `match` does not,
+ * ends the walk: nothing around it is returned.
+ */
+export function findEnclosingLoaderBody(
+  match: (loaderId: string) => boolean,
+  stop?: (loaderId: string) => boolean,
+): string | undefined {
+  for (let s = loaderBodyScopeALS.getStore(); s; s = s.parent) {
+    if (s.loaderId === undefined) continue;
+    if (match(s.loaderId)) return s.loaderId;
+    if (stop?.(s.loaderId)) return undefined;
+  }
+  return undefined;
+}
+
 /**
  * True while `loaderId`'s body, or a loader it awaits via ctx.use at any
  * depth, is executing. The loader-level cache records these pushes