@rangojs/router 0.31.0 → 0.33.0

package/src/rsc/server-action.ts

@@ -22,6 +22,7 @@ import {
   setRequestContextParams,
 } from "../server/request-context.js";
 import { printServerError } from "../server/print-server-error.js";
+import { runActionBody } from "../server/cookie-store.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import { resolveActionRefId } from "../router/is-action.js";
 import { getInterceptSourceHeader } from "../router/navigation-snapshot.js";
@@ -203,7 +204,7 @@ export async function executeServerAction<TEnv>(
 
   try {
     loadedAction = await ctx.loadServerAction(actionId);
-    let data = await loadedAction!.apply(null, args);
+    let data = await runActionBody(() => loadedAction!.apply(null, args));
 
     // Intercept redirect Responses: serializing one as the action returnValue
     // would fail, and revalidation would run needlessly.

package/src/rsc/shell-capture.ts

@@ -552,7 +552,7 @@ const SNAPSHOT_BYTE_ENCODER = new TextEncoder();
 
 /**
  * Warn once per key that the capture's loader pins exceeded the route's
- * `maxSnapshotBytes` cap, so no document shell was stored (dc-t89). Once per
+ * `maxSnapshotBytes` cap, so no document shell was stored. Once per
  * key: the route recaptures every backoff window.
  */
 function warnSnapshotOverCapOnce(
@@ -2603,8 +2603,7 @@ async function captureAndStoreShell(
             throw new Error(`[rango] no shell pin for "${segmentKey}"`);
           }
         } catch (error) {
-          // Unpinned, the loader would run on every HIT over this prelude
-          // (dc-t89): refuse like an encode error.
+          // Unpinned, the loader would run on every HIT over this prelude: refuse like an encode error.
           reqCtx._renderErrors?.push(error);
         }
       }
@@ -2650,7 +2649,7 @@ async function captureAndStoreShell(
     }
 
     // Snapshot size guard: `maxSnapshotBytes` bounds the loader pins, and a
-    // document HIT needs every pin its prelude baked (dc-t89). Over the cap
+    // document HIT needs every pin its prelude baked. Over the cap
     // the entry keeps the navigation half only (the doc record, or nothing:
     // a tombstone that also shadows a build shell) and the attempt refuses.
     // The whole entry is bounded separately below, by the store's limit.
@@ -2897,7 +2896,7 @@ export {
 
 // Exported for unit tests that pin the refused-capture backoff policy directly
 // (dev cap vs production exponential growth, stored-clears, cold-start re-probe),
-// and markCaptureBackoff for serveShellHit (a pin that failed to decode, dc-t89).
+// and markCaptureBackoff for serveShellHit (a pin that failed to decode).
 // These are the same module-level functions the schedule path uses; a test that
 // drove them through a real capture round-trip could not assert the exact window
 // arithmetic without a full cold render.

package/src/rsc/shell-serve.ts

@@ -38,6 +38,7 @@ import {
 import { routerKeyPrefix } from "../cache/cache-key-utils.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { appendMetric } from "../router/metrics.js";
+import { escapeJsonForScript } from "../escape-script.js";
 import type { MetricsStore } from "../server/context.js";
 import { WIRE } from "../wire-params.js";
 
@@ -162,12 +163,22 @@ export function withoutShellMissMarker(request: Request): Request | undefined {
  * the page. window.stop() runs only when it reloads: it keeps the half-sent
  * Flight stream from being closed by DOMContentLoaded, which would throw
  * React's "Connection closed" (#412) before the reload lands.
+ *
+ * `restoreCookie` is the request's `_carriedLocationStateCookie`: the HIT's
+ * headers already cleared the location state cookie a document redirect left
+ * (server/document-location-state.ts), so the script sets it again before it
+ * reloads, and the reload carries the state.
  */
-export function shellReloadScript(): string {
+export function shellReloadScript(restoreCookie?: string): string {
+  const restore =
+    restoreCookie === undefined
+      ? ""
+      : `document.cookie=${escapeJsonForScript(JSON.stringify(restoreCookie))};`;
   return inlineShellScript(
     "(function(){var u=new URL(location.href);" +
       `if(u.searchParams.has(${JSON.stringify(WIRE.shellMiss)}))return;` +
       `u.searchParams.set(${JSON.stringify(WIRE.shellMiss)},"miss");` +
+      restore +
       "try{window.stop()}catch(e){}location.replace(u.href)})()",
   );
 }

package/src/segment-system.tsx

@@ -318,7 +318,7 @@ function wrapDefaultOutletContent(
  * is settled like a flagged one, so the commit shows no fallback. A loader
  * error is left to its read site there, its errorBoundary() fallback riding
  * the throw, as on a navigation: the nearest boundary to the read catches it
- * (#1129, dc-t65). notFound()/redirect() keep their build-time node.
+ * (#1129). notFound()/redirect() keep their build-time node.
  */
 async function buildLoaderStreams(
   loaders: ResolvedSegment[],

package/src/server/context.ts

@@ -126,9 +126,10 @@ export type EntryPropRender = {
   loading?: ReactNode | false;
   /**
    * loading(fallback, { prefetch: false }) with a renderable fallback: a
-   * prefetch defers what the fallback covers while the entry's segment is
-   * new to the client (router/segment-resolution/prefetch-deferral.ts). Set
-   * on both DSL evaluations, whatever `ssr` did to `loading`.
+   * speculative prefetch defers what the fallback covers while the entry's
+   * segment is new to the client
+   * (router/segment-resolution/prefetch-deferral.ts). Set on both DSL
+   * evaluations, whatever `ssr` did to `loading`.
    */
   loadingPrefetch?: false;
   /**
@@ -171,8 +172,8 @@ export type LoaderEntry = {
    */
   bake?: true;
   /**
-   * loader(Def, { prefetch: false }): a prefetch defers this registration
-   * while its segment is new to the client
+   * loader(Def, { prefetch: false }): a speculative prefetch defers this
+   * registration while its segment is new to the client
    * (router/segment-resolution/prefetch-deferral.ts).
    */
   prefetch?: false;
@@ -211,7 +212,10 @@ export type InterceptSegmentsState = {
  * @internal This type is an implementation detail and may change without notice.
  */
 export type InterceptSelectorContext<TEnv = any> = {
-  /** Where the navigation comes from: the intercept source while one is open. */
+  /**
+   * Where the navigation comes from: the intercept source while one is open.
+   * Its `url` never carries a #fragment.
+   */
   from: ServerRouteLocation;
   /** The navigation target. */
   to: ServerRouteLocation;
@@ -1719,6 +1723,33 @@ export function isInsideLoaderBody(loaderId: string): boolean {
   return false;
 }
 
+// The segment of the streamed handler or loader body running here; the
+// walker moves the shared `_currentSegmentId` on without awaiting either.
+const segmentPinALS: AsyncLocalStorage<string | undefined> = ((
+  globalThis as any
+)[Symbol.for("rangojs-router:segment-pin")] ??= new AsyncLocalStorage<
+  string | undefined
+>());
+
+/**
+ * Run `fn` as segment `segmentId`'s code: a handle push, a loader kickoff or
+ * a "use cache" call it makes, before or after an await, files under
+ * `segmentId` (segmentPinOf).
+ */
+export function runAsSegment<R>(segmentId: string | undefined, fn: () => R): R {
+  return segmentPinALS.run(segmentId, fn);
+}
+
+/**
+ * The segment code here runs for: the innermost runAsSegment scope, else
+ * `ctx`'s pin (a handler the walker awaits).
+ */
+export function segmentPinOf(ctx: {
+  _currentSegmentId?: string;
+}): string | undefined {
+  return segmentPinALS.getStore() ?? ctx._currentSegmentId;
+}
+
 // 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

package/src/server/cookie-store.ts

@@ -330,7 +330,8 @@ export function invalidateClientCache(): void {
  *
  * Sets an internal response header the bridge reads. Idempotent within a
  * request. Inert (a dev warning) outside a request context — there is no
- * automatic invalidation to suppress.
+ * automatic invalidation to suppress. It also keeps the state's write part
+ * (runActionBody).
  */
 export function keepClientCache(): void {
   const ctx = _getRequestContext();
@@ -347,6 +348,26 @@ export function keepClientCache(): void {
   ctx._setKeepCacheDirective();
 }
 
+/**
+ * Run a server action's body (the JS call or a no-JS form post), then bump the
+ * rango state's write part for the client that called it: the response's
+ * state `Set-Cookie` keeps the client's timestamp and carries a new write part
+ * (browser/cookie-name.ts). Every later request of every tab and reload sends
+ * the new `X-Rango-State`, so a prefetch or navigation the browser HTTP cache
+ * holds from before the write (a response's own `Cache-Control: max-age`)
+ * misses, while the client's in-memory caches only go stale, as the action
+ * bridge marks them. Bumped however the body ends (returned, threw, or
+ * redirected), since the write may have committed either way, and not after
+ * keepClientCache() or invalidateClientCache() (whose rotation covers it).
+ */
+export async function runActionBody<T>(body: () => T | Promise<T>): Promise<T> {
+  try {
+    return await body();
+  } finally {
+    _getRequestContext()?._rotateStateCookie("write");
+  }
+}
+
 /**
  * Create a CookieStore backed by a RequestContext. Reads go through the
  * context's unguarded `_readCookie()` / `_readCookies()`: cookies() ran the

package/src/server/document-location-state.ts

@@ -0,0 +1,334 @@
+/**
+ * Location state on document responses (#1330).
+ *
+ * A client navigation or an action carries server-set location state in its
+ * Flight payload, and a redirect on either becomes a Flight redirect that
+ * carries it too. A document request has no such channel for a 3xx: the
+ * browser follows it with a plain GET. This module carries the state across
+ * that one hop in a short-lived cookie:
+ *
+ * - `carryLocationStateAcrossRedirect` (rsc/request-stages.ts
+ *   finalizeRequestResponse) writes it on a document request's same-origin
+ *   3xx when the request set location state;
+ * - `consumeDocumentLocationState` (rsc/request-stages.ts runRequestPasses)
+ *   reads it on the next GET document request that navigates to the target
+ *   pathname (`Sec-Fetch-Dest` a browsing context, where sent), seeds
+ *   `_locationState` with its entries (so the render attaches them to the
+ *   bootstrap payload, rsc/rsc-rendering.ts) and clears it. A shell HIT that
+ *   degrades into a reload after its headers cleared the cookie sets it
+ *   again from script first (`_carriedLocationStateCookie`), so the reload
+ *   carries the state.
+ *
+ * A document that carries location state is per visitor: it is marked
+ * `_documentLocationState`, never stored by the document cache or as a PPR
+ * shell, and leaves with `Cache-Control: private, no-store`
+ * (`markDocumentResponsePrivate`).
+ *
+ * The value is JSON, not Flight: a cookie holds text, and the client merges
+ * it as `history.state` would hold it. `Path=/` because the `__Host-` prefix
+ * (https) requires it, which keeps a sibling subdomain from planting state;
+ * the target pathname inside the value decides who consumes it.
+ */
+
+import {
+  isLocationStateKey,
+  resolveLocationStateEntries,
+  type LocationStateEntry,
+} from "../browser/react/location-state-shared.js";
+import { getRawCookieValue } from "../browser/cookie-name.js";
+import { isExternalRedirect } from "../redirect-origin.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
+import { mayNeedSSR } from "../rsc/ssr-setup.js";
+import { requestHeaders } from "./request-headers.js";
+import {
+  serializeCookieValue,
+  type RequestContext,
+} from "./request-context.js";
+
+/** Seconds the cookie lives: one redirect hop, never a later visit. */
+const DOCUMENT_LOCATION_STATE_MAX_AGE = 60;
+
+/**
+ * Upper bound of one serialized `Set-Cookie` (name, value and attributes).
+ * Browsers keep at least 4096 bytes per cookie; the margin covers the
+ * attributes some add.
+ */
+const DOCUMENT_LOCATION_STATE_MAX_BYTES = 4000;
+
+const COOKIE_SUFFIX = "-ls";
+
+const PRIVATE_NO_STORE = "private, no-store";
+
+interface CarriedState {
+  /** The pathname of the redirect target, the only request that reads it. */
+  p: string;
+  /** The resolved entries: slot key to value. */
+  s: Record<string, unknown>;
+}
+
+/** The cookie's name for a router: `__Host-` on https. */
+export function documentLocationStateCookieName(
+  stateCookieName: string,
+  secure: boolean,
+): string {
+  return `${secure ? "__Host-" : ""}${stateCookieName}${COOKIE_SUFFIX}`;
+}
+
+function cookieAttributes(secure: boolean): {
+  path: string;
+  httpOnly: boolean;
+  secure: boolean;
+  sameSite: "lax";
+} {
+  return { path: "/", httpOnly: true, secure, sameSite: "lax" };
+}
+
+/**
+ * A document request: one that renders HTML (mayNeedSSR), not a navigation,
+ * an action, a loader fetch or a Flight fetch. Those carry state in their
+ * Flight payload, or are not what the browser shows.
+ */
+function isDocumentRequest(request: Request, url: URL): boolean {
+  return mayNeedSSR(request, url);
+}
+
+function parseCarriedState(raw: string): CarriedState | undefined {
+  try {
+    const parsed: unknown = JSON.parse(decodeURIComponent(raw));
+    if (parsed === null || typeof parsed !== "object") return undefined;
+    const { p, s } = parsed as Partial<CarriedState>;
+    if (typeof p !== "string" || s === null || typeof s !== "object") {
+      return undefined;
+    }
+    return { p, s };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * `Sec-Fetch-Dest` values of a request that navigates a browsing context: the
+ * one a browser makes when it follows a document redirect.
+ */
+const NAVIGATION_FETCH_DESTS: ReadonlySet<string> = new Set([
+  "document",
+  "iframe",
+  "frame",
+]);
+
+/**
+ * A request that navigates: the browser shows its response. Where the browser
+ * sends `Sec-Fetch-Dest`, it must name a browsing context. A same-path
+ * `fetch()` with a wildcard `Accept` or a `<link rel=prefetch>` passes
+ * mayNeedSSR but sends `empty`, and must not eat the cookie before the
+ * navigation it was left for. A request without the header (an older
+ * browser, a non-browser client) keeps the mayNeedSSR rule alone.
+ */
+function isNavigationRequest(request: Request): boolean {
+  const dest = requestHeaders(request).get("sec-fetch-dest");
+  return dest === null || NAVIGATION_FETCH_DESTS.has(dest);
+}
+
+/**
+ * Read the cookie a document redirect left for this request: seed
+ * `_locationState` with its slots and clear it. Only a GET document request
+ * of the target pathname that navigates consumes it (the request the browser
+ * makes for a 301/302/303, see isNavigationRequest); any other request, a
+ * form POST to that path or a prefetch of it included, leaves it to its
+ * expiry. A malformed value is cleared and ignored, and only `__rsc_ls_*`
+ * slots are taken from it (the value comes from the browser).
+ */
+export function consumeDocumentLocationState(
+  reqCtx: Pick<
+    RequestContext,
+    "_locationState" | "_carriedLocationStateCookie" | "setCookie"
+  >,
+  request: Request,
+  url: URL,
+  stateCookieName: string,
+): void {
+  if (request.method !== "GET") return;
+  if (!isDocumentRequest(request, url)) return;
+  if (!isNavigationRequest(request)) return;
+  const secure = url.protocol === "https:";
+  const name = documentLocationStateCookieName(stateCookieName, secure);
+  const raw = getRawCookieValue(requestHeaders(request).get("cookie"), name);
+  if (raw === null) return;
+  const carried = parseCarriedState(raw);
+  if (carried && carried.p !== url.pathname) return;
+  reqCtx.setCookie(name, "", { ...cookieAttributes(secure), maxAge: 0 });
+  if (!carried) return;
+  const entries: LocationStateEntry[] = [];
+  for (const key of Object.keys(carried.s)) {
+    if (!isLocationStateKey(key)) continue;
+    entries.push({ __rsc_ls_key: key, __rsc_ls_value: carried.s[key] });
+  }
+  if (entries.length === 0) return;
+  reqCtx._locationState = entries;
+  reqCtx._carriedLocationStateCookie = restoreCookieLine(name, raw, secure);
+}
+
+/**
+ * The `document.cookie` line that sets the consumed cookie again, for a
+ * shell HIT that reloads after its headers cleared it (rsc/rsc-rendering.ts
+ * serveShellHit). Script cannot write an `HttpOnly` cookie, so this one is
+ * readable by the page's script for its short life; it carries nothing the
+ * page's payload does not already hold.
+ */
+function restoreCookieLine(name: string, raw: string, secure: boolean): string {
+  return (
+    `${name}=${raw}; Path=/; Max-Age=${DOCUMENT_LOCATION_STATE_MAX_AGE}; ` +
+    `SameSite=Lax${secure ? "; Secure" : ""}`
+  );
+}
+
+/** JSON keeps it as it is: what the cookie can carry without change. */
+function isJsonPlain(value: unknown): boolean {
+  if (value === null) return true;
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return true;
+    case "number":
+      return Number.isFinite(value);
+    case "object": {
+      if (Array.isArray(value)) return value.every(isJsonPlain);
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) return false;
+      return Object.values(value as Record<string, unknown>).every(
+        (member) => member !== undefined && isJsonPlain(member),
+      );
+    }
+    default:
+      return false;
+  }
+}
+
+function slotNames(state: Record<string, unknown>): string {
+  return Object.keys(state).join(", ");
+}
+
+/**
+ * Write the cookie on a document request's redirect that set location state,
+ * and mark the redirect private. Not for a partial or action request (their
+ * redirect is a Flight payload), an external or cross-origin target (the
+ * cookie would never reach it) or a response that is not a 3xx with a
+ * Location. Returns the response to send: a new one when its headers are
+ * immutable.
+ */
+export function carryLocationStateAcrossRedirect(
+  response: Response,
+  reqCtx: Pick<RequestContext, "_locationState">,
+  request: Request,
+  url: URL,
+  stateCookieName: string,
+): Response {
+  const entries = reqCtx._locationState;
+  if (!entries || entries.length === 0) return response;
+  if (!isDocumentRequest(request, url)) return response;
+  if (response.status < 300 || response.status >= 400) return response;
+  if (isExternalRedirect(response)) return response;
+  const location = response.headers.get("Location");
+  if (!location) return response;
+  let target: URL;
+  try {
+    target = new URL(location, url);
+  } catch {
+    return response;
+  }
+  if (target.origin !== url.origin) return response;
+
+  let state: Record<string, unknown>;
+  try {
+    state = resolveLocationStateEntries(entries);
+  } catch (error) {
+    // A lazy entry's getter threw: the redirect still leaves, without state.
+    console.warn(
+      "[rango] Location state was dropped from a document redirect: " +
+        `resolving it threw (${String(error)}).`,
+    );
+    return response;
+  }
+  if (process.env.NODE_ENV !== "production") {
+    for (const [key, value] of Object.entries(state)) {
+      if (!isJsonPlain(value)) {
+        console.warn(
+          `[rango] Location state "${key}" crosses a document redirect as JSON, ` +
+            "which does not keep this value as it is (a Date, Map, Set, bigint, " +
+            "undefined or class instance). Store plain JSON data in state that a " +
+            "document request redirects with.",
+        );
+      }
+    }
+  }
+
+  const secure = url.protocol === "https:";
+  const name = documentLocationStateCookieName(stateCookieName, secure);
+  let cookie: string;
+  try {
+    cookie = serializeCookieValue(
+      name,
+      JSON.stringify({ p: target.pathname, s: state } satisfies CarriedState),
+      { ...cookieAttributes(secure), maxAge: DOCUMENT_LOCATION_STATE_MAX_AGE },
+    );
+  } catch {
+    console.warn(
+      `[rango] Location state (${slotNames(state)}) was dropped from a document ` +
+        "redirect: it cannot be serialized as JSON.",
+    );
+    return response;
+  }
+  if (cookie.length > DOCUMENT_LOCATION_STATE_MAX_BYTES) {
+    console.warn(
+      `[rango] Location state (${slotNames(state)}) was dropped from a document ` +
+        `redirect: its cookie is ${cookie.length} bytes, over the ` +
+        `${DOCUMENT_LOCATION_STATE_MAX_BYTES}-byte limit. Carry less state, or ` +
+        "an id the target page loads the rest by.",
+    );
+    return response;
+  }
+
+  return withHeaders(response, (headers) => {
+    headers.append("Set-Cookie", cookie);
+    headers.set("Cache-Control", PRIVATE_NO_STORE);
+  });
+}
+
+/**
+ * Apply `write` to the response's headers, or to a copy of the response when
+ * they are immutable (a `Response.redirect()`). A WebSocket upgrade is never
+ * rebuilt and never carries location state.
+ */
+function withHeaders(
+  response: Response,
+  write: (headers: Headers) => void,
+): Response {
+  if (isWebSocketUpgradeResponse(response)) return response;
+  try {
+    write(response.headers);
+    return response;
+  } catch {
+    const copy = new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: new Headers(response.headers),
+    });
+    write(copy.headers);
+    return copy;
+  }
+}
+
+/**
+ * `Cache-Control: private, no-store` on a document that carries location
+ * state, after every middleware: a shared cache must never store or replay
+ * one visitor's state. Returns the response to send.
+ */
+export function markDocumentResponsePrivate(
+  response: Response,
+  reqCtx: Pick<RequestContext, "_documentLocationState">,
+): Response {
+  if (!reqCtx._documentLocationState) return response;
+  return withHeaders(response, (headers) =>
+    headers.set("Cache-Control", PRIVATE_NO_STORE),
+  );
+}

package/src/server/handle-store.ts

@@ -302,6 +302,8 @@ export interface HandleStore {
    * so a loader that throws or skips its push shows none rather than the
    * record's. A hole's replays go with them. Any other loader's replays stay
    * (a dependency another entry's HIT replayed), and so do restored copies.
+   * A prefetch that defers the loader calls it too (revalidation.ts
+   * resolveOwnerLoaders): no run is made, so none of its placeholders stand.
    */
   settleLoaderRun(loaderId: string): void;