@rangojs/router 0.0.0-experimental.e9c0b2f2 → 0.0.0-experimental.ea9f40f2

package/src/server/cookie-store.ts

@@ -9,7 +9,11 @@
 
 import type { CookieOptions } from "../router/middleware-types.js";
 import { getRequestContext, _getRequestContext } from "./request-context.js";
-import { isInsideCacheScope } from "./context.js";
+import {
+  isInsideCacheScope,
+  getCurrentLoaderBodyId,
+  isInsideHandlerInvokedLoaderBody,
+} from "./context.js";
 import { INSIDE_CACHE_EXEC } from "../cache/taint.js";
 
 /**
@@ -62,6 +66,7 @@ export interface CookieStore {
 export function cookies(): CookieStore {
   const ctx = getRequestContext();
   assertNotInsideCacheContext(ctx, "cookies");
+  assertNotInsideShellCapture(ctx, "cookies");
   return createCookieStore(ctx);
 }
 
@@ -132,6 +137,72 @@ function assertNotInsideCacheContext(ctx: unknown, fnName: string): void {
   }
 }
 
+/**
+ * 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 prelude is shared across every user
+ * hitting the URL, so a request-scoped read here would bake one user's
+ * cookies/headers 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.
+ *
+ * HANDLER-INVOKED loader bodies (`await ctx.use(Loader)` from a handler) are
+ * EXEMPT — the consumption-lane rule: handler consumption yields a BAKED
+ * shared copy in every artifact tier, and the cache-purity guards above
+ * already permit identity reads there (cache()/"use cache" bake the same
+ * reads today). Guarding only the PPR tier made the same code legal under
+ * cache() but capture-refusing under ppr (issue #672 / #674). The trade is
+ * documented: an identity read in a handler-consumed loader bakes the CAPTURE
+ * request's value into the shared shell; client-side consumption (useLoader)
+ * is the live lane.
+ *
+ * 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`.
+ *
+ * Applies only to the READ surfaces (cookies(), headers()) 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.
+ *
+ * The throw makes such a route PPR-ineligible by construction: the capture
+ * render errors, nothing is stored, and every request keeps getting the
+ * normal axis-1 render.
+ */
+function assertNotInsideShellCapture(ctx: unknown, fnName: string): void {
+  if (
+    ctx !== null &&
+    typeof ctx === "object" &&
+    (ctx as { _shellCaptureRun?: unknown })._shellCaptureRun === true
+  ) {
+    if (isInsideHandlerInvokedLoaderBody()) return;
+    // Flag the capture context BEFORE throwing: inside an executing bake-lane
+    // loader this throw is swallowed by wrapLoaderPromise into per-loader error
+    // UI, which would bake silently into the shared shell. The capture checks
+    // the flag after the render and refuses (shell-capture.ts). Also record
+    // WHICH loader body (if any) made the read, so the refusal warning can
+    // name the real source instead of hardcoding a lane — the read may come
+    // from a bake-lane loader OR from handler/render code (issue #672).
+    (ctx as { _shellCaptureGuardTripped?: string })._shellCaptureGuardTripped =
+      fnName;
+    (
+      ctx as { _shellCaptureGuardTrippedLoaderId?: string }
+    )._shellCaptureGuardTrippedLoaderId = getCurrentLoaderBodyId();
+    throw new Error(
+      `${fnName}() cannot be called while capturing a shared shell ` +
+        `(shell-cache middleware). The captured shell is served to every user ` +
+        `of this URL, so request-scoped data read here would leak one user's ` +
+        `${fnName === "cookies" ? "cookies" : "headers"} to others. Read it ` +
+        `inside a loader instead — loaders are never captured and always run ` +
+        `fresh per request:\n\n` +
+        `  loader("user", () => getUser(cookies().get("session")?.value));`,
+    );
+  }
+}
+
 const HEADERS_MUTATION_METHODS = new Set(["set", "append", "delete"]);
 
 /**
@@ -152,6 +223,7 @@ const HEADERS_MUTATION_METHODS = new Set(["set", "append", "delete"]);
 export function headers(): ReadonlyHeaders {
   const ctx = getRequestContext();
   assertNotInsideCacheContext(ctx, "headers");
+  assertNotInsideShellCapture(ctx, "headers");
   return new Proxy(ctx.request.headers, {
     get(target, prop, receiver) {
       if (typeof prop === "string" && HEADERS_MUTATION_METHODS.has(prop)) {

package/src/server/loader-registry.ts

@@ -67,7 +67,19 @@ export async function getLoaderLazy(
     }
   }
 
-  // Dev fallback: parse ID (format: "src/path/to/file.ts#ExportName") and import
+  // The remaining dev fallback (parse the id as "src/path/file.ts#ExportName"
+  // and import it by path) only makes sense in dev, where ids ARE file paths
+  // and the dev loader manifest is intentionally empty. In production ids are
+  // hashed ("<hash>#ExportName") and every resolvable loader is reached above
+  // via the in-memory registry or the lazy import manifest. The hash is not a
+  // path, so a production fall-through would run import("/<hash>") and throw a
+  // misleading "No such module <hash>" 500 instead of reporting the loader as
+  // unregistered. Return undefined in production so a genuinely unknown loader
+  // is a clean 404 "not found in registry" from handleLoaderFetch.
+  if (process.env.NODE_ENV === "production") {
+    return undefined;
+  }
+
   const hashIndex = id.indexOf("#");
   if (hashIndex !== -1) {
     const filePath = id.slice(0, hashIndex);

package/src/server/request-context.ts

@@ -48,8 +48,8 @@ import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
+import type { TransitionWhenFn } from "../types/segments.js";
 import type { ResolvedTracing } from "../router/tracing.js";
-import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 import {
   THEME_COOKIE,
   isValidTheme,
@@ -161,9 +161,75 @@ export interface RequestContext<
   /** @internal Handle store for tracking handle data across segments */
   _handleStore: HandleStore;
 
+  /**
+   * @internal transition({ when }) predicates for segments matched this request,
+   * keyed by segment id. Collected during resolution (the function is stripped
+   * from the serialized segment config), then evaluated post-handler in
+   * rsc-rendering — outside any cache scope — to drop the transition of any
+   * segment whose predicate returns false.
+   */
+  _transitionWhen?: Array<{ id: string; when: TransitionWhenFn }>;
+
   /** @internal Cache store for segment caching (optional, used by CacheScope) */
   _cacheStore?: SegmentCacheStore;
 
+  /**
+   * @internal PPR shell-capture ACTIVE marker. True ONLY inside the background
+   * capture task's derived request context (built by shell-capture.ts). This is
+   * the switch every capture-specific behavior reads: loader masking
+   * (loader-mask.ts isShellCaptureActive / fresh.ts emitStreaming) and the
+   * cookies()/headers() capture guard (cookie-store.ts
+   * assertNotInsideShellCapture). The foreground render never sets it, so the
+   * served response is byte-identical to axis 1. The capture descriptor itself
+   * (key/ttl/swr/tags/store) is NOT threaded through the request context — the
+   * integrated PPR serve path (rsc/shell-serve.ts + rsc-rendering.ts) builds it
+   * locally and passes it to scheduleShellCapture directly.
+   */
+  _shellCaptureRun?: boolean;
+
+  /**
+   * @internal Bake-lane loader containers collected DURING a shell capture:
+   * segment-key -> the loader's (pre-wrap) result promise. Populated by
+   * resolveLoaderData for loaders on entries with no renderable loading() (the
+   * bake lane — they execute at capture instead of being masked; see
+   * docs/design/loader-container-bake.md). Drained by captureAndStoreShell
+   * after the shell quiesces: settled containers are promise-elided,
+   * Flight-serialized, and pinned into the snapshot's loader family; a
+   * REJECTED container refuses the capture (error UI must never bake into the
+   * shared shell). Own property of the capture's derived context only.
+   */
+  _shellCaptureLoaderRecords?: Map<string, Promise<unknown>>;
+
+  /**
+   * @internal Loader-family snapshot seed for a shell HIT's tail render:
+   * segment-key -> the capture's elided container (already Flight-deserialized
+   * by serveShellHit). resolveLoaderData overlays it onto the fresh run's
+   * container (recorded paths pinned, hole-marker paths keep the fresh nested
+   * promises) so the payload's baked bytes match the frozen prelude. Own
+   * property of the HIT tail's derived context only.
+   */
+  _shellLoaderSeed?: Map<string, unknown>;
+
+  /**
+   * @internal Set (to the offending fn name) by the cookies()/headers()
+   * capture guard when it throws DURING a capture render. Load-bearing for the
+   * bake lane: a guard throw inside an executing loader is swallowed by
+   * wrapLoaderPromise into per-loader error UI, which would otherwise bake
+   * silently into the shared shell — the capture checks this flag after the
+   * render and refuses instead. Deterministic, so the capture does not retry.
+   */
+  _shellCaptureGuardTripped?: string;
+
+  /**
+   * @internal The loader $$id whose BODY was executing when the capture guard
+   * tripped (read off the loader-body ALS scope at trip time), or undefined
+   * when the read came from handler/render code. Only used to make the
+   * once-per-key refusal warning name the real source — the old text
+   * hardcoded "a bake-lane loader", which misattributed handler-land reads
+   * and sent users debugging the wrong lane (issue #672, secondary).
+   */
+  _shellCaptureGuardTrippedLoaderId?: string;
+
   /**
    * @internal Handler-owned registry of explicit per-scope stores from
    * cache({ store }). Created once per createRSCHandler() and threaded into
@@ -211,6 +277,19 @@ export interface RequestContext<
   /** @internal Registered onResponse callbacks */
   _onResponseCallbacks: Array<(response: Response) => Response>;
 
+  /**
+   * @internal Promises of the background tasks scheduled via this context's
+   * waitUntil (deferred cache writes, revalidations, consumer tasks). The PPR
+   * shell capture drains this list BEFORE its match/render as an ORDERING EDGE:
+   * every foreground deferred cache write is scheduled here before the capture
+   * task is, so settling the list first guarantees the capture's cache reads
+   * observe the foreground's generation instead of racing it (see
+   * shell-capture.ts). Tasks whose scheduling fn carries
+   * UNTRACKED_BACKGROUND_TASK are not tracked (the capture task itself —
+   * tracking it would make that drain await its own promise).
+   */
+  _pendingBackgroundTasks?: Array<Promise<unknown>>;
+
   /**
    * Current theme setting (only available when theme is enabled in router config)
    *
@@ -292,6 +371,30 @@ export interface RequestContext<
   /** @internal Previous route key (from the navigation source), used for revalidation */
   _prevRouteKey?: string;
 
+  /**
+   * @internal Navigation/action source data the transition({ when }) gate reads
+   * to build its ShouldRevalidateFn-shaped predicate context. currentUrl/Params
+   * come from the navigation snapshot (set at match time); action* are stashed
+   * at the action-bearing gate call sites. All undefined when there is no source
+   * (initial full load) or no action (plain navigation).
+   */
+  _gateCurrentUrl?: URL;
+  _gateCurrentParams?: Record<string, string>;
+  _gateActionId?: string;
+  _gateActionUrl?: URL;
+  _gateActionResult?: unknown;
+  _gateFormData?: FormData;
+
+  /**
+   * @internal True while the post-action revalidation render is running (set by
+   * revalidateAfterAction). The "use cache" runtime reads this to prefer
+   * freshness over a fast stale response during an action: a stale entry
+   * re-executes in the foreground (so the action response reflects the refreshed
+   * value) with only the store write deferred, instead of serving stale and
+   * revalidating in the background. A plain navigation (flag unset) keeps SWR.
+   */
+  _inActionRevalidation?: boolean;
+
   /**
    * @internal Render barrier for experimental `rendered()` API.
    * Resolves when all non-loader segments have settled and handle data
@@ -375,6 +478,15 @@ export interface RequestContext<
   /** @internal Request-scoped performance metrics store */
   _metricsStore?: MetricsStore;
 
+  /**
+   * @internal True request entry timestamp (performance.now() at handler entry).
+   * Set once at request-context creation (rsc/handler.ts) so a metrics store
+   * created MID-request — ctx.debugPerformance() or the getMetricsStore wrapper —
+   * anchors its timeline to the real request start instead of the opt-in moment,
+   * keeping phases that began before the opt-in at their true (non-negative) offset.
+   */
+  _handlerStart?: number;
+
   /** @internal Resolved platform phase-span tracing for this request (Cloudflare or OTel) */
   _tracing?: ResolvedTracing;
 
@@ -413,7 +525,10 @@ export type PublicRequestContext<
   | "setCookie"
   | "deleteCookie"
   | "_handleStore"
+  | "_transitionWhen"
   | "_cacheStore"
+  | "_shellCaptureRun"
+  | "_shellCaptureGuardTrippedLoaderId"
   | "_explicitTaggedStores"
   | "_requestTags"
   | "_cacheProfiles"
@@ -422,6 +537,13 @@ export type PublicRequestContext<
   | "_locationState"
   | "_routeName"
   | "_prevRouteKey"
+  | "_gateCurrentUrl"
+  | "_gateCurrentParams"
+  | "_gateActionId"
+  | "_gateActionUrl"
+  | "_gateActionResult"
+  | "_gateFormData"
+  | "_inActionRevalidation"
   | "_reportedErrors"
   | "_renderBarrier"
   | "_resolveRenderBarrier"
@@ -434,6 +556,7 @@ export type PublicRequestContext<
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
+  | "_handlerStart"
   | "_basename"
   | "_setStatus"
   | "_rotateStateCookie"
@@ -444,6 +567,17 @@ export type PublicRequestContext<
   | "res"
 >;
 
+/**
+ * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
+ * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:
+ * the capture's pre-render write barrier settles that list, so tracking the
+ * capture itself would make the drain wait on its own (still-running) promise.
+ * @internal
+ */
+export const UNTRACKED_BACKGROUND_TASK: unique symbol = Symbol.for(
+  "rango.untrackedBackgroundTask",
+);
+
 // AsyncLocalStorage instance for request context
 const requestContextStorage = new AsyncLocalStorage<RequestContext<any>>();
 
@@ -527,11 +661,17 @@ export function setRequestContextParams(
  */
 export function setRequestContextPrevRouteKey(
   prevRouteKey: string | undefined,
+  currentUrl?: URL,
+  currentParams?: Record<string, string>,
 ): void {
   const ctx = requestContextStorage.getStore();
-  if (ctx && prevRouteKey !== undefined) {
-    ctx._prevRouteKey = prevRouteKey;
-  }
+  if (!ctx) return;
+  if (prevRouteKey !== undefined) ctx._prevRouteKey = prevRouteKey;
+  // Source URL/params for the transition({ when }) gate (effectiveFromUrl /
+  // effectiveFromMatch.params from the navigation snapshot). Same write point as
+  // _prevRouteKey, which doubles as fromRouteName.
+  if (currentUrl !== undefined) ctx._gateCurrentUrl = currentUrl;
+  if (currentParams !== undefined) ctx._gateCurrentParams = currentParams;
 }
 
 /**
@@ -842,26 +982,44 @@ export function createRequestContext<TEnv>(
     method: request.method,
 
     _handleStore: handleStore,
+    _transitionWhen: [],
     _cacheStore: cacheStore,
     _explicitTaggedStores: explicitTaggedStores,
     _requestTags: new Set<string>(),
     _cacheProfiles: cacheProfiles,
 
     waitUntil(fn: () => Promise<void>): void {
+      // Wrap in Promise.resolve().then(fn) so a SYNCHRONOUS throw in a
+      // non-async callback becomes a rejected promise handed to the host's
+      // waitUntil (logged as a background failure), instead of escaping into
+      // the request flow. Mirrors fireAndForgetWaitUntil's deferral.
+      const task = Promise.resolve().then(fn);
+      // Track the task promise so the PPR shell capture can settle the
+      // foreground's deferred cache writes before its own match/render (the
+      // ordering edge; see _pendingBackgroundTasks). The capture task itself
+      // opts out via the marker — the drain must never await its own promise.
+      if (
+        !(fn as { [UNTRACKED_BACKGROUND_TASK]?: boolean })[
+          UNTRACKED_BACKGROUND_TASK
+        ]
+      ) {
+        ctx._pendingBackgroundTasks?.push(task);
+      }
       if (executionContext?.waitUntil) {
-        // Wrap in Promise.resolve().then(fn) so a SYNCHRONOUS throw in a
-        // non-async callback becomes a rejected promise handed to the host's
-        // waitUntil (logged as a background failure), instead of escaping into
-        // the request flow. Mirrors fireAndForgetWaitUntil's deferral.
-        executionContext.waitUntil(Promise.resolve().then(fn));
+        executionContext.waitUntil(task);
       } else {
-        fireAndForgetWaitUntil(fn);
+        // Node/dev fallback: fire-and-forget with error logging (the same
+        // policy fireAndForgetWaitUntil applies).
+        task.catch((err) =>
+          console.error("[waitUntil] Background task failed:", err),
+        );
       }
     },
 
     executionContext,
 
     _onResponseCallbacks: [],
+    _pendingBackgroundTasks: [],
 
     onResponse(callback: (response: Response) => Response): void {
       assertNotInsideCacheExec(ctx, "onResponse");
@@ -891,6 +1049,7 @@ export function createRequestContext<TEnv>(
 
     _reportedErrors: new WeakSet<object>(),
     _metricsStore: undefined,
+    _handlerStart: undefined,
 
     _renderBarrier: null as any,
     _resolveRenderBarrier: null as any,