@rangojs/router 0.0.0-experimental.143 → 0.0.0-experimental.144

package/src/rsc/rsc-rendering.ts

@@ -44,6 +44,10 @@ import {
   warnPprNonceActiveOnce,
 } from "./shell-serve.js";
 import { contextGet } from "../context-var.js";
+import {
+  resolveSameOriginRedirect,
+  safeSameOriginLanding,
+} from "../redirect-origin.js";
 import { nonce as nonceToken } from "./nonce.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
@@ -413,6 +417,29 @@ async function handleRscRenderingInner<TEnv>(
   return response;
 }
 
+/**
+ * Neutralize the shell-HIT degradation redirect target.
+ *
+ * The inline `location.replace` emitted by serveShellHit when a shell HIT lands
+ * on a URL whose route became redirecting mid-TTL is a document-native redirect
+ * exit that BYPASSES the 3xx chokepoint (guardOutgoingRedirect acts only on 3xx
+ * + Location responses, never a committed 200 body). So it reuses the ONE
+ * same-origin resolver directly: a cross-origin/unparseable/unsafe target
+ * neutralizes to the same safe same-origin landing as redirect-guard.ts
+ * (basename root, or "/" when unset) rather than navigating the user off-host.
+ * A safe same-origin/relative target passes through as its normalized href.
+ */
+export function resolveShellHitRedirectTarget(
+  rawTarget: string,
+  requestOrigin: string,
+  basename: string | undefined,
+): string {
+  return (
+    resolveSameOriginRedirect(rawTarget, requestOrigin) ??
+    safeSameOriginLanding(basename)
+  );
+}
+
 /**
  * Serve a validated shell HIT: commit the composed response NOW — the stored
  * prelude bytes are the first thing on the wire — and run the live tail
@@ -535,10 +562,16 @@ function serveShellHit(
           // a shell (capture bails on redirects), so a HIT on a redirecting URL
           // requires the route to have BECOME redirecting within the shell TTL.
           // The 200 + prelude are already committed; degrade to a client-side
-          // replace so the user still lands on the target.
+          // replace so the user still lands on the target. The target is
+          // neutralized first (see resolveShellHitRedirectTarget).
+          const safeTarget = resolveShellHitRedirectTarget(
+            tail.redirect,
+            url.origin,
+            ctx.router.basename,
+          );
           controller.enqueue(
             new TextEncoder().encode(
-              `<script>location.replace(${JSON.stringify(tail.redirect)})</script>`,
+              `<script>location.replace(${JSON.stringify(safeTarget)})</script>`,
             ),
           );
         }

package/src/rsc/shell-capture.ts

@@ -327,6 +327,39 @@ function warnCaptureRefusedOnce(key: string, reason: string): void {
   );
 }
 
+/** Keys already warned about untagged bake-lane data baked into the shell. */
+const warnedUntaggedShellBakes = new Set<string>();
+
+/**
+ * Warn once per shell key that a bake-lane loader baked material into the shell
+ * but the capture recorded ZERO tags (no render-collected _requestTags, no
+ * static ppr.tags). Such data is frozen in the shared shell until TTL and is
+ * un-evictable by tag: a server action refreshes the CLIENT only (rotates Rango
+ * state, busts the browser HTTP cache) and never touches the server shell store,
+ * and updateTag()/revalidateTag() cannot drop data that was baked WITHOUT a tag.
+ *
+ * Coarse per-shell-key signal, not per-loader attribution — the tag set is
+ * unioned globally at the write barrier, not tracked per loader, so we cannot
+ * name the offending loader without adding attribution plumbing (deliberately
+ * not done). Dev-only + once-per-key so it never spams production or fires on
+ * every capture.
+ */
+function warnUntaggedShellBakeOnce(key: string): void {
+  if (warnedUntaggedShellBakes.has(key)) return;
+  warnedUntaggedShellBakes.add(key);
+  console.warn(
+    `[rango] Shell capture for "${key}" baked bake-lane loader data into the ` +
+      "shell with NO cache tag. That data is frozen in the shared shell until " +
+      "TTL and cannot be tag-invalidated: a server action refresh touches the " +
+      "client only (not the server shell store), and updateTag() cannot evict " +
+      "data that was baked without a tag.\n" +
+      'Fix: tag the data (cacheTag() / "use cache" / cache({ tags })) so ' +
+      "updateTag() drops the shell, or move the volatile read under a loading() " +
+      "hole so it stays on the live lane and is never baked. See the /ppr skill " +
+      "(node_modules/@rangojs/router/skills/ppr/SKILL.md).",
+  );
+}
+
 export interface FlightCaptureGate {
   /** Identity passthrough of the source stream; feed this to captureShellHTML. */
   stream: ReadableStream<Uint8Array>;
@@ -487,9 +520,12 @@ export function gateFlightForCapture(
  * store, and passed to scheduleShellCapture directly — it is NOT threaded through
  * the request context. `tags` carries the route's OPERATIONAL `ppr.tags`; the
  * capture UNIONS them with the shell's own auto-collected (non-loader) request
- * tags from its derived render (the collected set stays authoritative). `store`
- * is the same store the serve path resolved for its getShell read
- * (requestCtx._cacheStore), so the capture writes where the serve reads.
+ * tags from its derived render (the collected set stays authoritative). That
+ * union happens at the putShell WRITE BARRIER in captureAndStoreShell — after the
+ * capture quiesces — not at stream construction, so a tag recorded after an await
+ * in async shell content is still collected (issue #676). `store` is the same
+ * store the serve path resolved for its getShell read (requestCtx._cacheStore),
+ * so the capture writes where the serve reads.
  */
 export interface ShellCaptureDescriptor {
   key: string;
@@ -776,24 +812,18 @@ async function attemptCapture(
       },
     });
 
-    // Shell tags = the non-loader request tags the capture render recorded on its
-    // own fresh _requestTags (loaders are masked, so loader cache tags — which
-    // belong to the holes, not the shell — are correctly excluded), UNIONED with
-    // the middleware's operational `tags` option (descriptor.tags). The collected
-    // set is authoritative; the option only adds tags the render cannot know.
-    const collected = [...derivedCtx._requestTags];
-    const union = new Set<string>([...(descriptor.tags ?? []), ...collected]);
-    const tags = union.size > 0 ? [...union] : undefined;
-
+    // Pass the descriptor with its STATIC ppr.tags unchanged. The shell's own
+    // render-recorded tags are snapshotted at the putShell WRITE BARRIER inside
+    // captureAndStoreShell, not here: a tag recorded AFTER an await in async shell
+    // content (and tags propagated by async cache()/"use cache" reads) lands after
+    // this synchronous construction point, so snapshotting here dropped it — the
+    // shell-tag snapshot must sit behind the quiesce gate (issue #676).
     return captureAndStoreShell(
       ssrModule,
       rscStream,
       freshHandleStore,
       derivedCtx,
-      {
-        ...descriptor,
-        tags,
-      },
+      descriptor,
     );
   });
 }
@@ -878,11 +908,25 @@ async function captureAndStoreShell(
   const refuseOnGuardTrip = (): "refused" | undefined => {
     const fnName = reqCtx._shellCaptureGuardTripped;
     if (!fnName) return undefined;
+    // Name the recorded source instead of hardcoding a lane. Under the
+    // consumption-lane rule, handler-INVOKED loader bodies are exempt from
+    // the guard (their value is a baked shared copy, mirroring cache()), so a
+    // trip can only come from a bake-lane SEGMENT loader or from non-loader
+    // handler/render code — the old blanket "bake-lane loader" attribution
+    // sent a live-lane debugging session down the wrong lane (issue #672).
+    const loaderId = reqCtx._shellCaptureGuardTrippedLoaderId;
+    const origin = loaderId
+      ? `segment loader "${loaderId}"`
+      : "handler/render code (no loader body was executing)";
     warnCaptureRefusedOnce(
       capture.key,
-      `a bake-lane loader (a loader on an entry with no loading()) called ${fnName}() during capture. ` +
-        "Identity must not bake into a shared shell. Give that loader's entry a loading() boundary " +
-        "(the live lane, exempt from the guard) or move the identity-dependent part into a nested promise.",
+      `${origin} called ${fnName}() during capture. Identity must not bake into a shared shell. ` +
+        "For a segment loader (bake lane, no loading()): give its entry a loading() boundary " +
+        "(the live lane, masked at capture) or move the identity-dependent part into a nested " +
+        "promise. For handler/render code: keep the value live by consuming a loader " +
+        'client-side (useLoader in a "use client" component). Note: `await ctx.use(loader)` ' +
+        "inside a HANDLER is exempt from this guard — its value bakes into the shared shell " +
+        "as a capture-time copy, mirroring cache() semantics (the consumption-lane rule).",
     );
     return "refused";
   };
@@ -981,6 +1025,10 @@ async function captureAndStoreShell(
     // gate above already returned no-shell) or postponed under an ANCESTOR
     // boundary (it is a hole; omitting the record keeps it live).
     const loaderRecords = reqCtx._shellCaptureLoaderRecords;
+    // Set once a bake-lane loader settles with real (non-hole) material: its data
+    // is frozen into the shell prelude regardless of whether snapshot
+    // serialization succeeds. Drives the untagged-bake dev warning below.
+    let bakedLoaderMaterial = false;
     if (loaderRecords && loaderRecords.size > 0) {
       // The codec import is deferred past the elide probes: a rejected record
       // refuses and a never-settled record is omitted WITHOUT touching Flight
@@ -1001,6 +1049,9 @@ async function captureAndStoreShell(
         // The container itself never settled: it is a hole (under an ancestor
         // boundary) or the trivial-prelude gate already fired. Omit — no pin.
         if (isLoaderHoleMarker(elided.value)) continue;
+        // Past the hole check: this container settled with real material that
+        // bakes into the shell prelude (independent of the snapshot pin below).
+        bakedLoaderMaterial = true;
         try {
           // serializeResult (not rscSerialize): null is a valid container and
           // must round-trip; serializeResult preserves it through Flight.
@@ -1021,6 +1072,28 @@ async function captureAndStoreShell(
       }
     }
 
+    // Shell tags snapshot at the WRITE BARRIER, not at stream construction: by
+    // here the capture has quiesced and the deferred cache writes were awaited, so
+    // tags recorded AFTER an await in async shell content (and by async
+    // cache()/"use cache" reads propagating through recordRequestTags) are
+    // included — issue #676. Loaders are masked, so loader cache tags — which
+    // belong to the holes, not the shell — never execute during capture and cannot
+    // contribute. Union with the route's static ppr.tags (capture.tags); the
+    // collected set is authoritative, the option only adds what the render cannot
+    // know.
+    const collected = [...reqCtx._requestTags];
+    const union = new Set<string>([...(capture.tags ?? []), ...collected]);
+    const shellTags = union.size > 0 ? [...union] : undefined;
+
+    // Untagged-bake diagnostic: a bake-lane loader froze mutable data into the
+    // shell but nothing tags the entry, so it is un-invalidatable except by TTL —
+    // a read-your-own-writes gap on the document channel (an action refresh skips
+    // the server shell; updateTag cannot drop untagged data). Coarse per-shell-key
+    // signal; dev-only and once-per-key so it never spams production.
+    if (isDevMode() && bakedLoaderMaterial && shellTags === undefined) {
+      warnUntaggedShellBakeOnce(capture.key);
+    }
+
     const store = capture.store ?? reqCtx._cacheStore;
     if (store?.putShell) {
       try {
@@ -1044,7 +1117,7 @@ async function captureAndStoreShell(
           entry,
           capture.ttl,
           capture.swr,
-          capture.tags,
+          shellTags,
         );
       } catch (error) {
         // Best-effort: a failed put must never throw out of the background task.

package/src/server/context.ts

@@ -770,14 +770,23 @@ 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 ONLY by isInsideCacheScope() to exempt
-// request-scoped reads. It deliberately does NOT affect isInsideLoaderScope(),
-// so rendered()/barrier/deadlock gating (which must distinguish DSL from
-// handler-invoked loaders) is unchanged.
+// 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.
 const LOADER_BODY_SCOPE_KEY = Symbol.for("rangojs-router:loader-body-scope");
-const loaderBodyScopeALS: AsyncLocalStorage<{ active: true }> = ((
-  globalThis as any
-)[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage<{ active: true }>());
+const loaderBodyScopeALS: AsyncLocalStorage<{
+  active: true;
+  loaderId?: string;
+  handlerInvoked?: boolean;
+}> = ((globalThis as any)[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage<{
+  active: true;
+  loaderId?: string;
+  handlerInvoked?: boolean;
+}>());
 
 /**
  * Check if the current execution is inside a cache() DSL boundary.
@@ -822,8 +831,37 @@ export function runInsideLoaderScope<T>(fn: () => T): T {
  * and handler-invoked via ctx.use) so request-scoped reads inside a loader
  * never trip the cache-scope guards — loaders always run fresh.
  */
-export function runInsideLoaderBodyScope<T>(fn: () => T): T {
-  return loaderBodyScopeALS.run({ active: true }, fn);
+export function runInsideLoaderBodyScope<T>(
+  fn: () => T,
+  loaderId?: string,
+  handlerInvoked?: boolean,
+): T {
+  return loaderBodyScopeALS.run({ active: true, loaderId, handlerInvoked }, fn);
+}
+
+/**
+ * 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
+ * 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).
+ */
+export function getCurrentLoaderBodyId(): string | undefined {
+  return loaderBodyScopeALS.getStore()?.loaderId;
+}
+
+/**
+ * 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).

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";
 
 /**
@@ -139,9 +143,19 @@ function assertNotInsideCacheContext(ctx: unknown, fnName: string): void {
  * 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. Loaders need no exemption: they are
- * masked (never executed) during capture and remain the per-request holes of
- * the shell.
+ * 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"),
@@ -164,12 +178,19 @@ function assertNotInsideShellCapture(ctx: unknown, fnName: string): void {
     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).
+    // 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 ` +

package/src/server/request-context.ts

@@ -220,6 +220,16 @@ export interface RequestContext<
    */
   _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
@@ -468,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;
 
@@ -509,6 +528,7 @@ export type PublicRequestContext<
   | "_transitionWhen"
   | "_cacheStore"
   | "_shellCaptureRun"
+  | "_shellCaptureGuardTrippedLoaderId"
   | "_explicitTaggedStores"
   | "_requestTags"
   | "_cacheProfiles"
@@ -536,6 +556,7 @@ export type PublicRequestContext<
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
+  | "_handlerStart"
   | "_basename"
   | "_setStatus"
   | "_rotateStateCookie"
@@ -1028,6 +1049,7 @@ export function createRequestContext<TEnv>(
 
     _reportedErrors: new WeakSet<object>(),
     _metricsStore: undefined,
+    _handlerStart: undefined,
 
     _renderBarrier: null as any,
     _resolveRenderBarrier: null as any,