@rangojs/router 0.17.0 → 0.19.0

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 {
@@ -13,9 +14,11 @@ import type {
 import { invariant, DslContextError } from "../errors";
 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";
 
 // ============================================================================
@@ -134,6 +137,15 @@ export type LoaderEntry = {
    * appears on navigation-lane entries.
    */
   awaitBeforeFlush?: true;
+  /**
+   * loader(Def, { ssr: false }) on every DSL evaluation, document and
+   * navigation: the loader's PPR bake lane (loader-cache.ts
+   * resolveLoaderData). The bake/seed key rides on it, so a client
+   * navigation's shell replay pins exactly the loaders a document HIT pins,
+   * whatever the entry's loading(). awaitBeforeFlush cannot carry that: a
+   * navigation evaluation never has it.
+   */
+  bake?: true;
 };
 
 /**
@@ -153,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)
 };
 
 /**
@@ -536,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>(
@@ -846,20 +861,17 @@ const loaderScopeALS: AsyncLocalStorage<{ active: true }> = ((
 // Purity-only scope: marks that a loader FUNCTION BODY is executing, regardless
 // of how the loader was invoked (DSL via runInsideLoaderScope, or handler-
 // invoked via ctx.use). Consulted by isInsideCacheScope() to exempt
-// request-scoped reads, by getCurrentLoaderBodyId() for guard-warning
-// attribution, and by isInsideHandlerInvokedLoaderBody() for the
-// consumption-lane rule (the shell-capture guard exemption). It deliberately
-// does NOT affect isInsideLoaderScope(), so rendered()/barrier/deadlock
-// gating (which must distinguish DSL from handler-invoked loaders) is
-// unchanged.
+// request-scoped reads, and by getCurrentLoaderBodyId() for guard-warning
+// attribution. It deliberately does NOT affect isInsideLoaderScope(), so
+// rendered()/barrier/deadlock gating (which must distinguish DSL from
+// handler-invoked loaders) is unchanged.
 interface LoaderBodyScope {
   active: true;
   loaderId?: string;
-  handlerInvoked?: boolean;
   /** 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>;
 }
 const LOADER_BODY_SCOPE_KEY = Symbol.for("rangojs-router:loader-body-scope");
 const loaderBodyScopeALS: AsyncLocalStorage<LoaderBodyScope> = ((
@@ -868,8 +880,9 @@ const loaderBodyScopeALS: AsyncLocalStorage<LoaderBodyScope> = ((
 
 /**
  * Check if the current execution is inside a cache() DSL boundary.
- * Returns false inside loader execution — loaders are always fresh
- * (never cached), so non-cacheable reads are safe.
+ * Returns false inside loader execution: a route cache() does not store
+ * loader values, so non-cacheable reads are safe. A loader bound with its own
+ * cache() stores its value; recordLoaderIdentityRead guards that.
  */
 export function isInsideCacheScope(): boolean {
   if (RangoContext.getStore()?.insideCacheScope !== true) return false;
@@ -886,44 +899,273 @@ export function isInsideCacheScope(): boolean {
 }
 
 /**
- * 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.
+ * 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:
  *
- * 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.
+ * 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.
+ *
+ * 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 assertNonCacheableReadAllowed(
-  keyOrVar: string | ContextVar<unknown>,
+export function guardIdentityRead(
+  ctx: unknown,
+  surface: string,
+  wording: IdentityReadWording,
 ): void {
-  const execScope = getCacheExecScope();
-  if (
-    execScope !== undefined &&
-    loaderBodyScopeALS.getStore()?.execScope !== execScope
-  ) {
-    const name = typeof keyOrVar === "string" ? ` "${keyOrVar}"` : "";
+  if (isInsideIdentityExempt()) return;
+  const { verb, fix } = wording;
+  if (tripShellCaptureGuard(ctx, surface, fix.warning)) {
     throw new Error(
-      `ctx.get() for a non-cacheable variable${name} 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.`,
+      `${surface} cannot be ${verb} while capturing a shared shell ` +
+        `(ppr shell capture). ${fix.capture}`,
+    );
+  }
+  refuseInCacheScope(surface, wording);
+  if (wording.record !== false) recordLoaderIdentityRead(surface, verb);
+}
+
+/**
+ * Steps 2 and 3 of guardIdentityRead: throw when a "use cache" body or a
+ * cache() boundary would store what `surface` produces.
+ */
+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(
-      `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.`,
+      `${surface} cannot be ${verb} inside a cache() boundary. ${fix.cacheScope}`,
     );
   }
 }
 
+/**
+ * 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 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,
+): boolean {
+  if (
+    ctx === null ||
+    typeof ctx !== "object" ||
+    (ctx as { _shellCaptureRun?: unknown })._shellCaptureRun !== true
+  ) {
+    return false;
+  }
+  // Record WHICH loader body (if any) made the read, so the refusal warning
+  // can name the real source instead of hardcoding a lane (issue #672).
+  const flagged = ctx as {
+    _shellCaptureGuardTripped?: { surface: string; fix: string };
+    _shellCaptureGuardTrippedLoaderId?: string;
+  };
+  flagged._shellCaptureGuardTripped = { surface, fix };
+  flagged._shellCaptureGuardTrippedLoaderId = getCurrentLoaderBodyId();
+  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), 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 {
+  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. */
+export type LoaderIdentityReadVerb = "called" | "read";
+
+/** A request-identity read a loader execution made (recordLoaderIdentityRead). */
+export interface LoaderIdentityRead {
+  /**
+   * The read as the error names it: "cookies()", "headers()",
+   * `ctx.get() for a non-cacheable variable "x"`, "ctx.theme" or
+   * "getRequestContext().theme".
+   */
+  surface: string;
+  /** "called" for a function, "read" for a property (the theme getters). */
+  verb: LoaderIdentityReadVerb;
+  /** The loader body that made the read. */
+  bodyId: string | undefined;
+  /**
+   * The cached loader whose value carries a read another loader made
+   * (loader-cache.ts identity mark): its readers read it through `via`.
+   */
+  via?: string;
+}
+
+/**
+ * Where cache-tag.ts installs its recorder at module init (same key there):
+ * it owns the per-execution recorded sets, and importing it here would be a
+ * cycle.
+ */
+const IDENTITY_READ_RECORDER_KEY = Symbol.for(
+  "rangojs-router:identity-read-recorder",
+);
+
+/**
+ * Record a request-identity read (cookies(), headers(), a non-cacheable
+ * ctx.get()) on the current loader execution (#972).
+ *
+ * isInsideCacheScope() exempts loader bodies because a route cache() never
+ * stores their values. A loader bound with its own cache() does: with no key()
+ * and no store keyGenerator its entry is keyed by loader, host, path and
+ * params only, and an enclosing route cache() key does not partition it
+ * (#974). A cookies() read there stored the first visitor's session and served
+ * it to everyone for the TTL. The read is recorded on the execution, not
+ * thrown at the call: a reader that starts the loader before its binding does
+ * runs it outside any fill, and the binding's MISS then reuses that run. The
+ * fill checks what its execution recorded, through the same links as its tags
+ * (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.
+ */
+export function recordLoaderIdentityRead(
+  surface: string,
+  verb: LoaderIdentityReadVerb = "called",
+): void {
+  if (isInsideIdentityExempt()) return;
+  const recorder = (globalThis as Record<symbol, unknown>)[
+    IDENTITY_READ_RECORDER_KEY
+  ] as ((surface: string, verb: LoaderIdentityReadVerb) => void) | undefined;
+  recorder?.(surface, verb);
+}
+
+/** The error a loader cache() fill with no declared key fails with (#972). */
+export function loaderCacheIdentityError(
+  read: LoaderIdentityRead,
+  cachedLoaderId: string,
+): Error {
+  const filling = `while filling its own cache() entry with no key()`;
+  const where =
+    read.via !== undefined && read.via !== cachedLoaderId
+      ? `inside loader "${read.bodyId}", which loader "${cachedLoaderId}" reads through another loader ("${read.via}") ${filling}`
+      : read.bodyId !== undefined && read.bodyId !== cachedLoaderId
+        ? `inside loader "${read.bodyId}", which loader "${cachedLoaderId}" reads ${filling}`
+        : `inside loader "${cachedLoaderId}", whose own cache() has no key()`;
+  return new Error(
+    `${read.surface} cannot be ${read.verb} ${where}. ` +
+      `The entry is keyed by loader, host, path and params only, so it is ` +
+      `shared across users: request-scoped data (cookies, headers, ` +
+      `non-cacheable variables) read here would be stored from one request ` +
+      `and served to everyone. Add a key that includes the value, or drop ` +
+      `the loader's cache():\n\n` +
+      `  cache({ ttl: 60, key: (ctx) => \`session:\${cookies().get("session")?.value}\` })`,
+  );
+}
+
 /**
  * Check if the current execution is inside a DSL loader scope
  * (wrapped by runInsideLoaderScope). Used by rendered() barrier
@@ -952,7 +1194,7 @@ export function latchCachedHeaderScope(
 /** True inside ANY loader execution — DSL loader scope or a loader body
  *  (however invoked). The "loaders always re-run fresh" exemptions key off
  *  this. */
-function isInsideAnyLoaderScope(): boolean {
+export function isInsideAnyLoaderScope(): boolean {
   return (
     loaderScopeALS.getStore()?.active === true ||
     loaderBodyScopeALS.getStore()?.active === true
@@ -1097,32 +1339,41 @@ 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).
  */
 export function runInsideLoaderBodyScope<T>(
   fn: () => T,
   loaderId?: string,
-  handlerInvoked?: boolean,
+  tags?: Set<string>,
 ): T {
-  return loaderBodyScopeALS.run(
-    {
-      active: true,
-      loaderId,
-      handlerInvoked,
-      parent: loaderBodyScopeALS.getStore(),
-      execScope: getCacheExecScope(),
-    },
-    fn,
+  // A loader a key() starts with ctx.use() runs guarded (runIdentityExempt).
+  return endIdentityExempt(() =>
+    loaderBodyScopeALS.run(
+      {
+        active: true,
+        loaderId,
+        parent: loaderBodyScopeALS.getStore(),
+        tags,
+      },
+      fn,
+    ),
   );
 }
 
+/** The innermost loader body's execution tag set (runInsideLoaderBodyScope). */
+export function getLoaderBodyTags(): Set<string> | undefined {
+  return loaderBodyScopeALS.getStore()?.tags;
+}
+
 /**
  * The $$id of the loader whose body is currently executing, or undefined
  * outside any loader body. Used by the shell-capture identity guard
- * (cookie-store.ts) 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).
@@ -1131,6 +1382,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
@@ -1144,19 +1413,6 @@ export function isInsideLoaderBody(loaderId: string): boolean {
   return false;
 }
 
-/**
- * True while a HANDLER-invoked loader body (`await ctx.use(Loader)` from a
- * handler, not the DSL segment funnel) is executing. The consumption-lane
- * rule keys off this: handler consumption yields a BAKED copy in every shared
- * artifact — cache(), "use cache", and the PPR shell — so the shell-capture
- * identity guard (cookie-store.ts) permits cookies()/headers() here, exactly
- * like the cache-purity guards do. DSL segment loaders (live lane masked at
- * capture, bake lane guarded) never set the flag.
- */
-export function isInsideHandlerInvokedLoaderBody(): boolean {
-  return loaderBodyScopeALS.getStore()?.handlerInvoked === true;
-}
-
 // Scope for handle PUSH CALLBACKS (push(() => ...), including async ones).
 // A push callback's value is stored as-is; if it is a promise it is NOT tracked
 // by handleStore.settled and does not block segment resolution, so a