@rangojs/router 0.24.4 → 0.25.0

package/src/router/navigation-snapshot.ts

@@ -4,6 +4,8 @@ import type { RouteMatchResult } from "./pattern-matching.js";
 
 export interface NavigationSnapshot {
   prevUrl: URL;
+  /** The visitor's URL of the page left, when `prevUrl` is its rewrite target. */
+  prevVisitorUrl: URL | null;
   prevParams: Record<string, string>;
   prevMatch: RouteMatchResult | null;
 
@@ -95,6 +97,35 @@ export function getInterceptSourceHeader(request: Request): string | null {
   return requestHeaders(request).get("X-RSC-Router-Intercept-Source");
 }
 
+/**
+ * The URL the page left rendered, when middleware rewrote it there (#1144):
+ * `_rsc_rt`, the payload's `rewriteTarget` the browser sends back while
+ * `X-RSC-Router-Client-Path` names the visitor's URL. Matching the visitor's
+ * URL would find the rewriting route. Same origin only. It names the page
+ * left, never what renders, so a forged value runs or skips no middleware.
+ */
+function getShownRouteUrl(url: URL): URL | null {
+  const shown = url.searchParams.get("_rsc_rt");
+  if (!shown) return null;
+  try {
+    const parsed = new URL(shown, url.origin);
+    return parsed.origin === url.origin ? formSearch(parsed) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `url` with its query as URLSearchParams writes it, as the request's own URL
+ * has it: setting and stripping `_rsc*` params rewrote that one (`?q=a%2Cb`),
+ * while a URL the browser names keeps the address bar's (`?q=a,b`). Compared
+ * as sent, every navigation from such a page was a search change.
+ */
+function formSearch(url: URL): URL {
+  url.search = String(url.searchParams);
+  return url;
+}
+
 export async function resolveNavigation(
   request: Request,
   url: URL,
@@ -112,12 +143,15 @@ export async function resolveNavigation(
     return null;
   }
 
-  let prevUrl: URL;
+  let visitor: URL;
   try {
-    prevUrl = new URL(previousUrl, url.origin);
+    visitor = formSearch(new URL(previousUrl, url.origin));
   } catch {
     return null;
   }
+  // An intercept's request diffs from its source, which _rsc_rt does not name.
+  const shown = interceptSourceUrl ? null : getShownRouteUrl(url);
+  const prevUrl = shown ?? visitor;
 
   let interceptContextUrl: URL;
   try {
@@ -154,6 +188,7 @@ export async function resolveNavigation(
 
   return {
     prevUrl,
+    prevVisitorUrl: shown && visitor,
     prevParams,
     prevMatch,
     interceptContextUrl,
@@ -176,6 +211,7 @@ export function createNavigationSnapshot(
   const defaultUrl = new URL("http://localhost/");
   return {
     prevUrl: defaultUrl,
+    prevVisitorUrl: null,
     prevParams: {},
     prevMatch: null,
     interceptContextUrl: defaultUrl,

package/src/router/prefetch-cache-ttl.ts

@@ -1,15 +1,14 @@
 /**
- * Resolve the prefetch cache TTL once, at router init, into the three derived
- * values the rest of the router consumes: seconds (for the Cache-Control
- * max-age), milliseconds (for the client-side in-memory cache), and the
- * Cache-Control header string (or false when caching is disabled).
+ * Resolve the prefetch cache TTL once, at router init, into the values the
+ * rest of the router consumes: seconds, and milliseconds for the client-side
+ * in-memory prefetch cache (shipped in payload metadata). Prefetch responses
+ * carry no Cache-Control: the browser HTTP cache would keep a prefetch whose
+ * render failed after its 200 went out (#1170).
  *
  * `false` disables prefetch caching (seconds 0). A non-finite input
  * (NaN/Infinity, e.g. from an env-derived number that failed to parse) is
- * treated as the default rather than producing a malformed
- * `Cache-Control: max-age=NaN` header; CDNs/browsers ignore such a directive,
- * which would silently disable caching on EVERY prefetch response. Negative
- * finite values clamp to 0 (disabled).
+ * treated as the default rather than disabling the cache. Negative finite
+ * values clamp to 0 (disabled).
  *
  * Policy note: this is the prefetch-TTL policy specifically. Other finite-number
  * guards in the codebase deliberately differ — defer.ts treats Infinity as an
@@ -17,12 +16,10 @@
  * at config time. They are NOT the same guard, so don't unify them.
  */
 export interface ResolvedPrefetchCacheTTL {
-  /** TTL in seconds for the Cache-Control max-age directive. */
+  /** TTL in seconds. */
   seconds: number;
   /** TTL in milliseconds for the client-side in-memory prefetch cache. */
   ms: number;
-  /** Cache-Control header value, or false when caching is disabled. */
-  cacheControl: string | false;
 }
 
 const DEFAULT_PREFETCH_CACHE_TTL_SECONDS = 300;
@@ -38,14 +35,9 @@ export function resolvePrefetchCacheTTL(
   } else if (typeof rawTTL === "number" && Number.isFinite(rawTTL)) {
     seconds = Math.max(0, Math.floor(rawTTL));
   } else {
-    // Non-finite (NaN/Infinity): fall back to the default rather than emit a
-    // malformed max-age=NaN/Infinity that CDNs and browsers reject.
+    // Non-finite (NaN/Infinity): fall back to the default.
     seconds = DEFAULT_PREFETCH_CACHE_TTL_SECONDS;
   }
 
-  return {
-    seconds,
-    ms: seconds * 1000,
-    cacheControl: seconds === 0 ? false : `private, max-age=${seconds}`,
-  };
+  return { seconds, ms: seconds * 1000 };
 }

package/src/router/prerender-match.ts

@@ -16,6 +16,7 @@ import { detectPrerenderPassthrough } from "../prerender.js";
 import { isRouteRootScoped } from "../route-map-builder.js";
 import { setupBuildUse } from "./loader-resolution.js";
 import { findInOrphans } from "./error-handling.js";
+import { interceptSlotId } from "./intercept-resolution.js";
 import { loadManifest } from "./manifest.js";
 import { traverseBack } from "./pattern-matching.js";
 import type { RouterContext } from "./router-context.js";
@@ -487,7 +488,7 @@ export async function matchForPrerender<TEnv = any>(
             // artifact. Re-pinned per iteration so multiple intercepts targeting
             // the same route each get their own id (mirrors fresh.ts parallel-slot
             // pinning).
-            const interceptSegmentId = `${parentEntry.shortCode}.${intercept.slotName}`;
+            const interceptSegmentId = interceptSlotId(parentEntry, intercept);
             (buildCtx as InternalHandlerContext<any, TEnv>)._currentSegmentId =
               interceptSegmentId;
 

package/src/router/revalidation.ts

@@ -4,7 +4,11 @@
  * Evaluates whether segments should revalidate based on params, actions, and custom functions.
  */
 
-import type { ResolvedSegment, HandlerContext } from "../types";
+import type {
+  ResolvedSegment,
+  HandlerContext,
+  ShouldRevalidateFn,
+} from "../types";
 import type { ActionContext } from "./types";
 import {
   debugLog,
@@ -17,6 +21,22 @@ import { isAutoGeneratedRouteName } from "../route-name.js";
 import { paramsEqual } from "./params-util.js";
 import { makeIsAction } from "./is-action.js";
 
+const REVALIDATE_ALWAYS: ShouldRevalidateFn<any, any> = () => true;
+const REVALIDATE_NEVER: ShouldRevalidateFn<any, any> = () => false;
+
+/**
+ * The predicate `revalidate(true)` / `revalidate(false)` stands for: the
+ * constant hard decision of `revalidate(() => true)` / `() => false`.
+ * Booleans are converted where they enter (the urls() helper, clientUrls()
+ * materialization, runRevalidate), so evaluation only ever sees functions.
+ */
+export function toShouldRevalidateFn(
+  fn: ShouldRevalidateFn<any, any> | boolean,
+): ShouldRevalidateFn<any, any> {
+  if (typeof fn !== "boolean") return fn;
+  return fn ? REVALIDATE_ALWAYS : REVALIDATE_NEVER;
+}
+
 /**
  * Options for revalidation evaluation
  */
@@ -85,7 +105,9 @@ export async function evaluateRevalidation<TEnv>(
   } = options;
   const nextParams = segment.params || {};
   const paramsChanged = !paramsEqual(nextParams, prevParams);
-  const searchChanged = prevUrl.search !== nextUrl.search;
+  const reqCtx = _getRequestContext();
+  const searchChanged =
+    prevUrl.search !== nextUrl.search || reqCtx?._visitorMoved === true;
 
   function pushTrace(
     defaultVal: boolean,
@@ -197,7 +219,6 @@ export async function evaluateRevalidation<TEnv>(
 
   const toRouteName =
     routeKey && !isAutoGeneratedRouteName(routeKey) ? routeKey : undefined;
-  const reqCtx = _getRequestContext();
   const prevRouteKey = reqCtx?._prevRouteKey;
   const fromRouteName =
     prevRouteKey && !isAutoGeneratedRouteName(prevRouteKey)

package/src/router/router-context.ts

@@ -25,7 +25,7 @@ import type { ResolveSegmentOptions } from "./segment-resolution.js";
  * Revalidation context passed to segment resolution
  */
 export interface RevalidationContext {
-  clientSegmentIds: Set<string>;
+  clientSegmentIds: ReadonlySet<string>;
   prevParams: Record<string, string>;
   request: Request;
   prevUrl: URL;
@@ -37,7 +37,7 @@ export interface RevalidationContext {
     actionResult?: any;
     formData?: FormData;
   };
-  stale: boolean;
+  stale?: boolean;
 }
 
 /**
@@ -159,7 +159,7 @@ export interface RouterContext<TEnv = any> {
     handlerContext: HandlerContext<any, TEnv>,
     belongsToRoute: boolean,
     revalidationContext?: RevalidationContext,
-    options?: { skipMiddleware?: boolean },
+    options?: { background?: boolean },
   ) => Promise<ResolvedSegment[]>;
 
   collectWithMarkers?: <T>(
@@ -250,23 +250,10 @@ export interface RouterContext<TEnv = any> {
   resolveInterceptLoadersOnly?: (
     intercept: InterceptEntry,
     entry: EntryData,
-    params: Record<string, string>,
     handlerContext: HandlerContext<any, TEnv>,
     belongsToRoute: boolean,
-    revalidationContext: {
-      clientSegmentIds: Set<string>;
-      prevParams: Record<string, string>;
-      request: Request;
-      prevUrl: URL;
-      nextUrl: URL;
-      routeKey: string;
-      actionContext?: any;
-      stale?: boolean;
-    },
-  ) => Promise<{
-    loaderDataPromise: Promise<any[]> | any[];
-    loaderIds: string[];
-  } | null>;
+    revalidationContext: RevalidationContext,
+  ) => Promise<ResolvedSegment[]>;
 }
 
 const routerContext = new AsyncLocalStorage<RouterContext<any>>();

package/src/router/router-interfaces.ts

@@ -382,13 +382,6 @@ export interface RangoInternal<
     import("../cache/profile-registry.js").CacheProfile
   >;
 
-  /**
-   * Cache-Control header value for prefetch responses.
-   * False means no caching of prefetch responses.
-   * Derived from prefetchCacheTTL.
-   */
-  readonly prefetchCacheControl: string | false;
-
   /**
    * TTL in milliseconds for the client-side in-memory prefetch cache.
    * 0 means caching is disabled.

package/src/router/router-options.ts

@@ -553,15 +553,12 @@ export interface RangoOptions<TEnv = any> {
   version?: string;
 
   /**
-   * TTL (in seconds) for the in-memory prefetch cache and the
-   * Cache-Control header on prefetch responses.
+   * TTL (in seconds) for the client-side in-memory prefetch cache.
    *
    * Controls how long prefetch responses are kept in the client-side
-   * in-memory cache and sets `Cache-Control: private, max-age=<ttl>`
-   * on prefetch responses, so the browser's HTTP cache may reuse them
-   * (`private`: shared caches such as a CDN do not store them). A route an
-   * intercept targets gets no prefetch `Cache-Control`: whether its
-   * response is the modal or the full page depends on the source page.
+   * in-memory cache. Prefetch responses carry no `Cache-Control`, so the
+   * browser's HTTP cache does not keep them: a prefetch whose render failed
+   * after its 200 went out would otherwise answer later requests.
    *
    * The cache is automatically invalidated on server actions regardless
    * of TTL, so this is primarily a staleness safety net.

package/src/router/segment-resolution/fresh.ts

@@ -38,6 +38,7 @@ import { _getRequestContext } from "../../server/request-context.js";
 import { getRouterContext } from "../router-context.js";
 import { trackStreamedHandler } from "./streamed-handler-boundary.js";
 import { observeSegmentHandler } from "../instrument.js";
+import { withReverseScope } from "../handler-context.js";
 import {
   track,
   RangoContext,
@@ -177,6 +178,7 @@ export async function resolveLoaders<TEnv>(
                 bakeLane || loaderEntry.bake === true ? segmentId : null,
               ),
             loader.$$id,
+            loaderEntry.reverseScope,
           ),
           entry,
           segmentId,
@@ -227,6 +229,7 @@ export async function resolveLoaders<TEnv>(
             bakeLane || loaderEntry.bake === true ? segmentId : null,
           ),
         loader.$$id,
+        loaderEntry.reverseScope,
       ),
       entry,
       segmentId,
@@ -646,6 +649,7 @@ export async function resolveParallelEntry<TEnv>(
   >;
 
   const slotsToResolve = slotNames ?? (Object.keys(slots) as `@${string}`[]);
+  const slotContext = withReverseScope(context, parallelEntry.reverseScope);
 
   for (const slot of slotsToResolve) {
     // Try static lookup first — in production, handler bodies are evicted
@@ -683,7 +687,7 @@ export async function resolveParallelEntry<TEnv>(
                 `${parentShortCode}.${slot}`,
                 `${parallelEntry.id}.${slot}`,
                 handler,
-                context,
+                slotContext,
               )
             : handler;
         if (result instanceof Promise) {
@@ -708,7 +712,7 @@ export async function resolveParallelEntry<TEnv>(
                 `${parentShortCode}.${slot}`,
                 `${parallelEntry.id}.${slot}`,
                 handler,
-                context,
+                slotContext,
               )
             : handler;
         doneParallelHandler();

package/src/router/segment-resolution/helpers.ts

@@ -30,6 +30,7 @@ import type { SegmentResolutionDeps } from "../types.js";
 import { debugLog } from "../logging.js";
 import { tryStaticLookup } from "./static-store.js";
 import { observeSegmentHandler } from "../instrument.js";
+import { withReverseScope } from "../handler-context.js";
 import type { TelemetrySink } from "../telemetry.js";
 import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
 
@@ -176,7 +177,12 @@ export async function resolveLayoutComponent<TEnv>(
   // the span so a handler that returns a Response (redirect control flow, which it
   // rethrows) is not recorded as a span error — mirrors the route-handler sites.
   return handleHandlerResult(
-    await observeSegmentHandler(entry.shortCode, entry.id, handler, context),
+    await observeSegmentHandler(
+      entry.shortCode,
+      entry.id,
+      handler,
+      withReverseScope(context, entry.reverseScope),
+    ),
   );
 }
 

package/src/router/segment-resolution/prefetch-deferral.ts

@@ -30,12 +30,14 @@ import {
   getParallelSlotEntries,
   isPprEntry,
   type EntryData,
+  type InterceptEntry,
   type LoaderEntry,
 } from "../../server/context.js";
 import { requestHeaders } from "../../server/request-headers.js";
 import type { HandlerContext, InternalHandlerContext } from "../../types.js";
 import type { CacheScope } from "../../cache/cache-scope.js";
 import { FILL_PARAM, PREFETCH_HEADER } from "../../prefetch-markers.js";
+import { isInterceptSegment } from "../../browser/intercept-utils.js";
 
 /**
  * What a request says it is, read once when its context is created
@@ -271,40 +273,64 @@ export function resolveDeferralScope(
   return scope;
 }
 
+const interceptScopes = new WeakMap<InterceptEntry, DeferralScope>();
+
+/**
+ * The deferral scope of a request that resolves `intercept`: its own flagged
+ * loaders, nothing of the target chain. The chain's layouts below the
+ * declaring entry render in that request and its `matched` leaves them out
+ * (match-result.ts), so a hole there would stand for a segment outside the
+ * page. A flagged loading() inside intercept() defers nothing: the slot is
+ * never a unit. Memoized on the entry (replaced with its manifest on HMR).
+ */
+export function resolveInterceptDeferralScope(
+  intercept: InterceptEntry,
+): DeferralScope {
+  const cached = interceptScopes.get(intercept);
+  if (cached) return cached;
+  const flagged = intercept.loader.filter((l) => l.prefetch === false);
+  const scope: DeferralScope =
+    flagged.length === 0
+      ? EMPTY_SCOPE
+      : {
+          loaders: new Map(flagged.map((l) => [l, true as const])),
+          loaderIds: new Set(flagged.map((l) => l.loader.$$id)),
+          units: new Map(),
+        };
+  interceptScopes.set(intercept, scope);
+  return scope;
+}
+
 /**
  * Which half of the feature a partial request is, if either (`fill` and
  * `prefetch` are requestKind's answer). Both halves are GETs: a request of
  * another method that carries either marker is a normal request. A prefetch
  * defers only on a plain GET navigation: an action re-renders what it
- * changed, an intercept resolves its loaders outside the shared funnel, and a
- * shell capture is never a prefetch whatever the request that scheduled it
- * sent. The four conditions overlap today (an action is a POST, a capture
- * runs the full match): each one states its own reason.
+ * changed, and a shell capture is never a prefetch whatever the request that
+ * scheduled it sent. The conditions overlap today (an action is a POST, a
+ * capture runs the full match): each one states its own reason.
  */
 export function partialDeferralMode(request: {
   fill: boolean;
   prefetch: boolean;
   method: string;
   isAction: boolean;
-  isIntercept: boolean;
   isShellCapture: boolean;
 }): PrefetchDeferral["mode"] {
   if (request.method !== "GET") return undefined;
   if (request.fill) return "fill";
-  return request.prefetch &&
-    !request.isAction &&
-    !request.isIntercept &&
-    !request.isShellCapture
+  return request.prefetch && !request.isAction && !request.isShellCapture
     ? "prefetch"
     : undefined;
 }
 
-const NOTHING_HELD: ReadonlySet<string> = new Set();
+export const NOTHING_HELD: ReadonlySet<string> = new Set();
 
 /**
  * The plan for one match, or undefined when the tree declares no flag and the
  * request is not a fill (the common case: nothing to carry). `held` is the
- * client's segment ids as the request listed them.
+ * client's segment ids as the request listed them. `scope` is the chain's
+ * unless the request resolves an intercept (resolveInterceptDeferralScope).
  */
 export function planPrefetchDeferral(
   entries: readonly EntryData[],
@@ -312,8 +338,8 @@ export function planPrefetchDeferral(
   matched: { pr?: boolean; od?: boolean },
   cacheScope: CacheScope | null | undefined,
   held: ReadonlySet<string> = NOTHING_HELD,
+  scope: DeferralScope = resolveDeferralScope(entries),
 ): PrefetchDeferral | undefined {
-  const scope = resolveDeferralScope(entries);
   if (scope === EMPTY_SCOPE && mode !== "fill") return undefined;
 
   const leaf = entries[entries.length - 1];
@@ -386,6 +412,30 @@ export function fillSends(
   return isFillRequest(ctx) ? !held.has(segmentId) : undefined;
 }
 
+/**
+ * A fill that resolves an intercept sends only what the client lacks of the
+ * intercept: a target-chain entry (by id) or stored segment it does not hold
+ * lies outside the intercept's `matched` (match-result.ts), so the fill skips
+ * it. The intercept's own segments are never skipped.
+ */
+export function interceptFillSkips(
+  match: {
+    handlerContext: HandlerContext<any, any>;
+    isIntercept: boolean;
+    clientSegmentSet: ReadonlySet<string>;
+  },
+  segment: string | { id: string; namespace?: string },
+): boolean {
+  if (!match.isIntercept) return false;
+  if (typeof segment !== "string") {
+    if (isInterceptSegment(segment)) return false;
+    segment = segment.id;
+  }
+  return (
+    fillSends(match.handlerContext, segment, match.clientSegmentSet) === true
+  );
+}
+
 const RECORD_OPEN: RecordUse = { read: true, write: true, refresh: true };
 
 /** PrefetchDeferral.record, or all of it open when the match has no plan. */