@rangojs/router 0.16.0 → 0.18.0

package/src/router/loader-resolution.ts

@@ -7,7 +7,16 @@
 import type { ReactNode } from "react";
 import type { EntryData } from "../server/context";
 import { observePhase, PHASES } from "./instrument.js";
-import { contextGet } from "../context-var.js";
+import { contextGet, isNonCacheable } from "../context-var.js";
+import { NOCACHE_SYMBOL } from "../cache/taint.js";
+import {
+  linkLoaderTags,
+  linkRecordedTags,
+  linkValueTags,
+  loaderTagSetsArmed,
+  readValueTags,
+  tagLoaderValue,
+} from "../cache/cache-tag.js";
 import type {
   ResolvedSegment,
   HandlerContext,
@@ -43,6 +52,7 @@ import {
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import { _getRequestContext } from "../server/request-context.js";
 import {
+  assertNonCacheableReadAllowed,
   isInsideLoaderScope,
   runInsideLoaderBodyScope,
   isInsidePushCallbackScope,
@@ -386,6 +396,12 @@ function createLoaderExecutor<TEnv>(
      * payload's handle-stream lifetime.
      */
     silentHandles?: boolean;
+    /**
+     * loaderId -> the cache() tags of that loader's binding in this request
+     * (setupLoaderAccess _bindLoaderCacheTags): an execution of it outside
+     * the binding answers for them too (#964).
+     */
+    bindingTags?: ReadonlyMap<string, Set<string>>;
   },
 ): (
   loader: LoaderDefinition<any, any>,
@@ -394,6 +410,7 @@ function createLoaderExecutor<TEnv>(
   // Capture RequestContext eagerly for cookie access (ALS protection on Cloudflare)
   const reqCtxRef = _getRequestContext();
   const silentHandles = executorOptions?.silentHandles === true;
+  const internal = ctx as InternalHandlerContext<any, TEnv>;
 
   // Dependency graph: loaderId -> set of loader IDs it directly depends on.
   const dependsOn = new Map<string, Set<string>>();
@@ -429,9 +446,30 @@ function createLoaderExecutor<TEnv>(
       deps.add(loader.$$id);
     }
 
-    // Return cached promise if already started
-    if (loaderPromises.has(loader.$$id)) {
-      return loaderPromises.get(loader.$$id)!;
+    // Every loader execution funnels here (handler and loader-to-loader
+    // reads, uncached DSL bindings, cache misses): memoized per request, so a
+    // loader runs at most once however many reads, with no store cache. A
+    // loader's cache() read-through lives in loader-cache.ts
+    // (executeLoaderData), whose ctx.use override serves a later handler read
+    // the binding's result.
+    //
+    // A read is a consumption: the value bakes into the reader's output, so
+    // the loader's tags follow the reader onto a cache() record (#957) and
+    // into the reader's own loader-cache entry (#964, readValueTags; armed
+    // only where a loader cache() can read them).
+    const reqCtx = reqCtxRef ?? _getRequestContext();
+    linkLoaderTags(loader.$$id, reqCtx);
+    const recordTags = loaderTagSetsArmed(reqCtx);
+    // A loader body reads a cache()-bound loader through its binding too, so
+    // every reader in the request gets the one value a HIT served. The
+    // binding's own MISS (callerLoaderId null) runs the loader below.
+    const bound =
+      callerLoaderId !== null &&
+      internal._loaderCacheOverrides?.get(loader.$$id);
+    const memo = bound || loaderPromises.get(loader.$$id);
+    if (memo) {
+      if (recordTags) readValueTags(memo);
+      return memo;
     }
 
     // Get loader function - either from loader object or fetchable registry
@@ -452,7 +490,7 @@ function createLoaderExecutor<TEnv>(
     pendingLoaders.add(loader.$$id);
 
     const currentLoaderId = loader.$$id;
-    const variables = (ctx as InternalHandlerContext<any, TEnv>)._variables;
+    const variables = internal._variables;
 
     // Capture whether this loader is being started from a DSL loader scope
     // (runInsideLoaderScope in fresh.ts). Handler-invoked loaders are NOT
@@ -466,18 +504,26 @@ function createLoaderExecutor<TEnv>(
     // stale. Attributing to the owning route/layout segment gives handle
     // pushes the same granularity handler pushes have (segmentOrder-correct
     // for breadcrumb accumulation).
-    const owningSegmentId = (ctx as InternalHandlerContext<any, TEnv>)
-      ._currentSegmentId;
+    const owningSegmentId = internal._currentSegmentId;
 
     let renderedResolved = false;
     let renderedPromise: Promise<void> | null = null;
 
-    // Loader functions are always fresh (never cached), so they get an
-    // unguarded get that bypasses non-cacheable read guards. This applies
-    // to ALL loaders — DSL and handler-called — because the loader
-    // function itself always re-executes. Also handles nested deps
-    // (loaderA → use(loaderB)) since all share this unguarded get.
-    const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
+    // Request-scoped like the handler ctx it derives from (issue #940): the
+    // NOCACHE_SYMBOL brand below makes a "use cache" function taking it key by
+    // the route fields (_routeName, _responseType) and replay its handle
+    // pushes into the owning segment, claimed per loader like a handler ctx
+    // (_claimLoaderPushes, _runLoaderIsolated). Non-cacheable ctx.get reads
+    // run the shared guard; the body itself stays exempt (loader body scope).
+    const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> &
+      Pick<
+        InternalHandlerContext<any, TEnv>,
+        | "_routeName"
+        | "_responseType"
+        | "_currentSegmentId"
+        | "_claimLoaderPushes"
+        | "_runLoaderIsolated"
+      > = {
       params: ctx.params,
       routeParams: (ctx.params ?? {}) as Record<string, string>,
       request: ctx.request,
@@ -517,6 +563,9 @@ function createLoaderExecutor<TEnv>(
             buildHandleSnapshot(reqCtx._handleStore, segmentOrder);
           return collectHandleData(keyOrVar, snapshot, segmentOrder);
         }
+        if (isNonCacheable(variables, keyOrVar)) {
+          assertNonCacheableReadAllowed(keyOrVar, _getRequestContext());
+        }
         return contextGet(variables, keyOrVar);
       }) as typeof ctx.get,
       use: ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
@@ -552,6 +601,11 @@ function createLoaderExecutor<TEnv>(
       method: "GET",
       body: undefined,
       reverse: ctx.reverse as LoaderContext["reverse"],
+      _routeName: internal._routeName,
+      _responseType: internal._responseType,
+      _currentSegmentId: owningSegmentId,
+      _claimLoaderPushes: internal._claimLoaderPushes,
+      _runLoaderIsolated: internal._runLoaderIsolated,
       rendered: (): Promise<void> => {
         // Guard: only DSL loaders may use rendered()
         if (!isDslLoader) {
@@ -639,6 +693,7 @@ function createLoaderExecutor<TEnv>(
         return renderedPromise;
       },
     };
+    (loaderCtx as any)[NOCACHE_SYMBOL] = true;
 
     // Meter this loader once via observePhase (loader:<id> perf metric +
     // rango.loader span); loaderFn runs inside the span callback so its KV/D1/
@@ -655,42 +710,29 @@ function createLoaderExecutor<TEnv>(
     // does not grant rendered() to handler-invoked loaders. Uses a body-only
     // scope, so isInsideLoaderScope() / barrier / deadlock gating is unchanged.
     //
-    // `handlerInvoked` (!isDslLoader) rides on the scope for the CONSUMPTION-
-    // LANE RULE: a handler-consumed loader's value is a BAKED copy in every
-    // shared artifact (cache(), "use cache", the PPR shell), so its identity
-    // reads are exempt from the shell-capture guard — same allowance the
-    // cache-purity guards give it. DSL segment loaders keep their lane
-    // machinery (live = masked at capture, bake = guarded). A DSL loader's
-    // nested deps inherit isDslLoader=false only when the CHAIN started in a
-    // handler; a chain started by the segment funnel stays DSL (the loader
-    // scope ALS survives the body's awaits).
-    // Shell fast path eligibility: a HANDLER-invoked loader executing during a
-    // capture is handler-layer dynamism — on a handler-free (replayed) HIT it
-    // would never re-run, freezing its consumption-lane value (#672's "fresh
-    // per serve" slot shape). Mark the capture; the entry declines the fast
-    // path and keeps the full tail. DSL loaders re-run on every HIT and never
-    // set this.
-    if (!isDslLoader) {
-      const captureCtx = _getRequestContext();
-      if (
-        captureCtx?._shellCaptureRun &&
-        captureCtx._shellCaptureHandleLiveness
-      ) {
-        captureCtx._shellCaptureHandleLiveness.handlerInvokedLoader = true;
-      }
-    }
+    // The CONSUMPTION-LANE RULE: a handler-consumed loader's value is a
+    // BAKED copy in every shared artifact (cache(), "use cache", the PPR
+    // shell). The cache-purity guards permit its identity reads; the PPR
+    // capture guard does not (server/context.ts assertNotInsideShellCapture).
 
+    const recordedTags = recordTags ? new Set<string>() : undefined;
     const promise = observePhase(PHASES.loader(loader.$$id), () =>
       Promise.resolve(
         runInsideLoaderBodyScope(
           () => loaderFn(loaderCtx as LoaderContext<any, TEnv>),
           loader.$$id,
-          !isDslLoader,
+          recordedTags,
         ),
       ).finally(() => {
         pendingLoaders.delete(loader.$$id);
       }),
     );
+    if (recordedTags) {
+      tagLoaderValue(promise, recordedTags);
+      readValueTags(promise);
+      const bindingTags = executorOptions?.bindingTags?.get(loader.$$id);
+      if (bindingTags) linkRecordedTags(recordedTags, bindingTags);
+    }
 
     // Auxiliary-lane tracking: keeps the handle store open for this body's
     // ctx.handle() pushes without joining `settled` (the handler barrier that
@@ -734,7 +776,41 @@ export function setupLoaderAccess<TEnv>(
   const reqCtxRef = _getRequestContext();
   const handleStoreRef = reqCtxRef?._handleStore;
 
-  const useLoader = createLoaderExecutor(ctx, loaderPromises);
+  // Loader-cache HIT replay (loader-cache.ts replayLoaderHandles): a cached
+  // entry records its ctx.use dependencies' pushes too, and a dependency is
+  // memoized here and shared with live readers. A loader that already ran
+  // here keeps its live pushes; otherwise one replay delivers its recorded
+  // pushes, and a later run here replaces them (HandleStore.pushReplayed).
+  const claimed = new Set<string>();
+  const internal = ctx as InternalHandlerContext<any, TEnv>;
+  internal._claimLoaderPushes = (loaderId) => {
+    if (loaderPromises.has(loaderId) || claimed.has(loaderId)) return false;
+    claimed.add(loaderId);
+    return true;
+  };
+  // A loader cache() binding's tags reach every execution of that loader
+  // outside the binding: one a reader started before the binding (linked
+  // here), a later one, or a refresh's (bindingTags).
+  const executor: { bindingTags?: Map<string, Set<string>> } = {};
+  internal._bindLoaderCacheTags = (loaderId, tags) => {
+    (executor.bindingTags ??= new Map()).set(loaderId, tags);
+    const started = loaderPromises.get(loaderId);
+    if (started) linkValueTags(started, tags);
+  };
+  const useLoader = createLoaderExecutor(ctx, loaderPromises, executor);
+  // A refresh's pushes are diverted, so its loader ctxs never claim
+  // (cache-runtime.ts refreshView). It reads each loader fresh, not through
+  // the page's bindings: a stale refresh must not rebuild its entry from
+  // another stale entry.
+  internal._runLoaderIsolated = (loader) =>
+    createLoaderExecutor(
+      Object.create(ctx, {
+        _claimLoaderPushes: { value: undefined },
+        _loaderCacheOverrides: { value: undefined },
+      }),
+      new Map(),
+      executor,
+    )(loader, null);
 
   ctx.use = ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
     if (isHandle(item)) {

package/src/router/match-api.ts

@@ -3,11 +3,15 @@ import {
   createCacheScope,
   resolveShellImplicitCacheScope,
 } from "../cache/cache-scope.js";
+import { armLoaderTagSets, armRecordTagOwners } from "../cache/cache-tag.js";
+import { bindsLoaderCache } from "./segment-resolution/loader-cache.js";
 import { RouteNotFoundError } from "../errors";
 import {
   createErrorInfo,
   createErrorSegment,
+  findInOrphans,
   findNearestErrorBoundary as findErrorBoundary,
+  withErrorBoundary,
 } from "./error-handling.js";
 import {
   createHandlerContext,
@@ -148,6 +152,20 @@ export async function createMatchContextForFull<TEnv>(
     Store.metrics = metricsStore;
   }
 
+  // A shell capture's implicit doc scope, or a document HIT tail's (which
+  // replaces any route-derived scope: the tail replays the shell's doc
+  // record), or else the route's own scope.
+  const cacheScope = resolveShellImplicitCacheScope(snapshot.cacheScope);
+  // A scope means a route cache() record may be written: arm its tag owners
+  // before any handler runs (#957). A document HIT tail writes no record and
+  // runs no handler, so it arms nothing. A loader bound with its own cache()
+  // needs the per-execution loader tag sets before any loader runs (#964):
+  // loaders still run on a HIT.
+  if (cacheScope && !_getRequestContext()?._shellImplicitCache?.docTail) {
+    armRecordTagOwners();
+  }
+  if (bindsLoaderCache(snapshot.entries)) armLoaderTagSets();
+
   return {
     request,
     url: cleanUrl,
@@ -184,9 +202,7 @@ export async function createMatchContextForFull<TEnv>(
     },
     isSameRouteNavigation: false,
     interceptResult: null,
-    // Shell fast path: a capture or an eligible document/navigation HIT may
-    // substitute an implicit doc-level scope (a route-derived scope wins).
-    cacheScope: resolveShellImplicitCacheScope(snapshot.cacheScope),
+    cacheScope,
     isIntercept: false,
     actionContext: undefined,
     isAction: false,
@@ -399,6 +415,16 @@ export async function createMatchContextForPartial<TEnv>(
   }
 
   const isIntercept = !!interceptResult;
+  // A normal-route navigation may replay a PPR shell's canonical segment
+  // snapshot. Intercepts remain source-dependent and always use their normal
+  // cache path.
+  const cacheScope = isIntercept
+    ? snapshot.cacheScope
+    : resolveShellImplicitCacheScope(snapshot.cacheScope);
+  // A scope means a route cache() record may be written: arm its tag owners
+  // before any handler runs (#957); see the full-match site for #964's arm.
+  if (cacheScope) armRecordTagOwners();
+  if (bindsLoaderCache(snapshot.entries)) armLoaderTagSets();
 
   return {
     request,
@@ -425,12 +451,7 @@ export async function createMatchContextForPartial<TEnv>(
     interceptSelectorContext,
     isSameRouteNavigation: nav.isSameRouteNavigation,
     interceptResult,
-    // A normal-route navigation may replay a PPR shell's canonical segment
-    // snapshot. Intercepts remain source-dependent and always use their normal
-    // cache path.
-    cacheScope: isIntercept
-      ? snapshot.cacheScope
-      : resolveShellImplicitCacheScope(snapshot.cacheScope),
+    cacheScope,
     isIntercept,
     actionContext,
     isAction,
@@ -481,24 +502,21 @@ export async function matchError<TEnv>(
     segmentType,
   );
 
+  // Same search order as findNearestErrorBoundary, so the fallback above and
+  // the entry that positions it agree.
   let entryWithBoundary: EntryData | null = null;
   let current: EntryData | null = manifestEntry;
+  let prev: EntryData | null = null;
   while (current) {
     if (current.errorBoundary && current.errorBoundary.length > 0) {
       entryWithBoundary = current;
       break;
     }
 
-    if (current.layout && current.layout.length > 0) {
-      for (const orphan of current.layout) {
-        if (orphan.errorBoundary && orphan.errorBoundary.length > 0) {
-          entryWithBoundary = orphan;
-          break;
-        }
-      }
-      if (entryWithBoundary) break;
-    }
+    entryWithBoundary = findInOrphans(current, withErrorBoundary, prev) ?? null;
+    if (entryWithBoundary) break;
 
+    prev = current;
     current = current.parent;
   }
 
@@ -507,23 +525,19 @@ export async function matchError<TEnv>(
 
   if (entryWithBoundary) {
     boundaryEntry = entryWithBoundary;
+    // The chain entry holding the boundary, itself or in its orphan tree: the
+    // error segment takes the place of its child in the chain.
+    const boundaryOwner = current;
 
     outletEntry = manifestEntry;
     current = manifestEntry;
 
     while (current) {
-      if (current.parent === boundaryEntry) {
+      if (current.parent === boundaryOwner) {
         outletEntry = current;
         break;
       }
 
-      if (current.parent && current.parent.layout) {
-        if (current.parent.layout.includes(boundaryEntry)) {
-          outletEntry = current;
-          break;
-        }
-      }
-
       current = current.parent;
     }
   } else {

package/src/router/match-handlers.ts

@@ -47,6 +47,7 @@ import {
   buildCacheSignalSegments,
 } from "./telemetry.js";
 import { _getRequestContext } from "../server/request-context.js";
+import { ShellRecordUnavailableError } from "../cache/shell-snapshot.js";
 import { evaluatePprTransitionWhen } from "./transition-when.js";
 
 /**
@@ -380,6 +381,10 @@ export function createMatchHandlers<TEnv = any>(
               emitter.end(0, false, error.status);
               throw error;
             }
+            // A document shell HIT tail's doc record could not supply the
+            // handler layer: a serve-path signal serveShellHit degrades, not a
+            // routing error (the record's decode failure was already reported).
+            if (error instanceof ShellRecordUnavailableError) throw error;
             emitter.error(
               error instanceof Error ? error : new Error(String(error)),
               "routing",