@rangojs/router 0.31.0 → 0.33.0

package/src/server/request-context.ts

@@ -17,6 +17,7 @@ import type { CacheErrorCategory } from "../cache/cache-error.js";
 import type { CookieOptions } from "../router/middleware.js";
 import {
   KEEP_CACHE_HEADER,
+  bumpStateWrite,
   getRawCookieValue,
   freshReadsCookieName,
   mintStateValue,
@@ -83,7 +84,10 @@ import {
   readGuardedTheme,
 } from "./cookie-store.js";
 import { requestHeaders } from "./request-headers.js";
-import { requestKind } from "../router/segment-resolution/prefetch-deferral.js";
+import {
+  requestKind,
+  type RequestKind,
+} from "../router/segment-resolution/prefetch-deferral.js";
 import {
   createReverseFunction,
   stripInternalParams,
@@ -203,8 +207,12 @@ export interface RequestContext<
   setStatus(status: number): void;
   /** @internal Set status bypassing cache-exec guard (for framework error handling) */
   _setStatus(status: number): void;
-  /** @internal Rotate the rango state cookie (server seat of invalidateClientCache). */
-  _rotateStateCookie(): void;
+  /**
+   * @internal Rotate the rango state cookie: its timestamp (the server seat of
+   * invalidateClientCache), or with `"write"` only its write part (a server
+   * action without a directive, cookie-store.ts runActionBody).
+   */
+  _rotateStateCookie(part?: "write"): void;
   /** @internal Set the keepClientCache() directive header on the response. */
   _setKeepCacheDirective(): void;
   /**
@@ -663,11 +671,30 @@ export interface RequestContext<
   _payloadDeferred?: boolean;
 
   /**
-   * @internal What the request says it is: a `<Link>` prefetch or a fill
-   * (`prefetch: false`), read once at creation
-   * (segment-resolution/prefetch-deferral.ts requestKind).
+   * @internal Set by the RSC handler when a partial response carries an
+   * `x-rsc-prefetch-scope` (router/source-reads.ts prefetchScopeOf): its diff
+   * is right for its source page, or a group of them, only. The document
+   * cache keys a partial without its source, so it does not store that
+   * response, whatever Cache-Control it ends up with.
+   */
+  _payloadSourceScoped?: boolean;
+
+  /**
+   * @internal Set when the answer has nothing live in it, so nothing in it can
+   * fail after the 200's headers left: the document cache middleware on a
+   * fresh HIT, and the RSC handler when the partial match came from storage
+   * (MatchResult.fromStorage). finalizeRequestResponse (rsc/request-stages.ts)
+   * sends such a prefetch the router's prefetch Cache-Control.
    */
-  _requestKind?: "prefetch" | "fill";
+  _servedFromStorage?: boolean;
+
+  /**
+   * @internal What the request says it is: a speculative `<Link>` prefetch,
+   * an intent prefetch (hover, `prefetch()`) or a fill (`prefetch: false`),
+   * read once at creation (segment-resolution/prefetch-deferral.ts
+   * requestKind).
+   */
+  _requestKind?: RequestKind;
 
   /**
    * @internal Set when a render shows the visitor's URL of a rewritten
@@ -680,12 +707,27 @@ export interface RequestContext<
   /**
    * Attach location state entries to the current response.
    *
-   * For partial (SPA) requests, the state is included in the RSC payload
-   * metadata and merged into history.pushState on the client. For redirect
-   * responses, the state travels through the redirect payload so the target
-   * page can read it via useLocationState.
+   * For a client navigation or an action, the state is included in the RSC
+   * payload metadata and merged into the entry's history.state on the
+   * client. For a document request (a page load, a no-JS form post), it rides
+   * the document's bootstrap payload and is merged into the entry when the
+   * client starts; readers get it once the page has hydrated. For a redirect,
+   * the state travels with the redirect: in its Flight payload on a
+   * navigation or action, in a one-shot cookie the target's document request
+   * reads on a document request. A document that carries state is sent
+   * `Cache-Control: private, no-store` and never stored by the document cache
+   * or as a PPR shell.
    *
-   * Multiple calls accumulate entries.
+   * Call it from middleware, a handler or an action. A loader's call
+   * (through `getRequestContext()`) is not supported: the payload takes the
+   * state before loaders settle, so the write may be dropped, and a PPR
+   * shell HIT never sends it.
+   *
+   * Multiple calls accumulate entries across definitions. For one definition
+   * the last write wins: two entries of the same definition share its slot
+   * in history.state, so a later call (or a later entry in one array)
+   * replaces an earlier one. To combine writes, make the state an array and
+   * write it once.
    *
    * @example
    * ```typescript
@@ -697,6 +739,24 @@ export interface RequestContext<
   /** @internal Accumulated location state entries */
   _locationState?: LocationStateEntry[];
 
+  /**
+   * @internal Set when a document's payload carries location state
+   * (rsc/rsc-rendering.ts, rsc/progressive-enhancement.ts), a shell HIT's
+   * included. The document is per visitor: the document cache refuses it,
+   * and it leaves `private, no-store` (server/document-location-state.ts).
+   */
+  _documentLocationState?: boolean;
+
+  /**
+   * @internal The `document.cookie` line that re-creates the location state
+   * cookie this request consumed (server/document-location-state.ts). The
+   * consuming response clears the cookie in its headers; a shell HIT that
+   * degrades into a reload after those headers left writes this line first
+   * (rsc/shell-serve.ts shellReloadScript), so the reload reads the state
+   * again.
+   */
+  _carriedLocationStateCookie?: string;
+
   /**
    * The matched route name, if the route has an explicit name.
    * Undefined before route matching or for unnamed routes.
@@ -1003,9 +1063,13 @@ export type PublicRequestContext<
   | "_documentCacheRender"
   | "_payloadVisitorTheme"
   | "_payloadDeferred"
+  | "_payloadSourceScoped"
+  | "_servedFromStorage"
   | "_requestKind"
   | "_payloadVisitorLocation"
   | "_locationState"
+  | "_documentLocationState"
+  | "_carriedLocationStateCookie"
   | "_routeName"
   | "_prevRouteKey"
   | "_visitorMoved"
@@ -1358,7 +1422,12 @@ export function createRequestContext<TEnv>(
   // of this request's headers goes through requestHeaders().
   guardRequestHeaders(request);
   const cookieHeader = requestHeaders(request).get("Cookie");
-  let rangoStateRotated = false;
+  // What this response's state Set-Cookie changed: nothing yet, the write
+  // part only, or the timestamp (which covers a write).
+  let rangoStateRotated: "write" | "timestamp" | null = null;
+  // The state Set-Cookie line written, replaced when a timestamp rotation
+  // follows a write bump in the same request.
+  let stateCookieLine: string | null = null;
   const freshCookie = stateCookieName
     ? freshReadsCookieName(stateCookieName)
     : undefined;
@@ -1438,6 +1507,17 @@ export function createRequestContext<TEnv>(
     rawStubHeaders = stubResponse.headers;
     shadowStubHeaders(stubResponse);
   };
+  // Remove one Set-Cookie line an internal writer appended earlier in this
+  // request (Headers has no per-value delete): the state cookie when a later
+  // write replaces or withdraws it, the fresh-reads cookie when a longer
+  // Max-Age replaces it.
+  const dropSetCookieLine = (line: string): void => {
+    const kept = rawStubHeaders
+      .getSetCookie()
+      .filter((cookie) => cookie !== line);
+    rawStubHeaders.delete("Set-Cookie");
+    for (const cookie of kept) rawStubHeaders.append("Set-Cookie", cookie);
+  };
 
   const handleStore = createHandleStore();
   const loaderPromises = new Map<string, Promise<any>>();
@@ -1613,16 +1693,29 @@ export function createRequestContext<TEnv>(
       stubResponse.headers.set(name, value);
     },
 
-    // Rotate the rango state cookie for the responding client (the server seat
-    // of invalidateClientCache). Writes ONE Set-Cookie per request with the
-    // value {version}:{timestamp}; the `:` stays raw (the cookie-name.ts
+    // Rotate the rango state cookie for the responding client. Writes ONE
+    // Set-Cookie per request; the `:` stays raw (the cookie-name.ts
     // serializer), not the URL-encoded form serializeCookieValue would produce.
-    // The timestamp is strictly greater than the client's current one (inbound
-    // X-Rango-State), so a same-millisecond server rotation still differs from
-    // the client value and the divergence observer fires.
-    _rotateStateCookie(): void {
-      if (rangoStateRotated) return;
-      rangoStateRotated = true;
+    // - No part (the server seat of invalidateClientCache): a new timestamp,
+    //   {version}:{timestamp}. It is strictly greater than the client's current
+    //   one (inbound X-Rango-State), so a same-millisecond server rotation
+    //   still differs from the client value and the divergence observer fires.
+    // - "write" (a server action without a directive, after its body ran): the
+    //   client's version and timestamp kept and the write part bumped,
+    //   {version}:{timestamp}:{write}, so the browser HTTP cache misses on
+    //   every response it holds from before the write while the client's
+    //   in-memory caches (keyed by {version}:{timestamp}) only go stale.
+    //   Skipped after keepClientCache() (and withdrawn by a later one, below),
+    //   and when the request carries no state.
+    // A timestamp rotation covers a write bump: the later one of the two
+    // replaces the bump's line, and a bump after a rotation adds nothing.
+    _rotateStateCookie(part?: "write"): void {
+      const kind = part === "write" ? "write" : "timestamp";
+      if (rangoStateRotated === "timestamp" || rangoStateRotated === kind) {
+        return;
+      }
+      if (kind === "write" && rawStubHeaders.has(KEEP_CACHE_HEADER)) return;
+      rangoStateRotated = kind;
       if (!stateCookieName) return;
       // The client's current value, for the monotonic guard: prefer the
       // X-Rango-State header (router navigation/prefetch fetches send it), but
@@ -1637,22 +1730,38 @@ export function createRequestContext<TEnv>(
       const prevRaw =
         (requestHeaders(request).get("x-rango-state") || null) ??
         getRawCookieValue(cookieHeader, stateCookieName);
-      const value = mintStateValue(versions?.document ?? "0", prevRaw);
+      const value =
+        kind === "write"
+          ? bumpStateWrite(prevRaw)
+          : mintStateValue(versions?.document ?? "0", prevRaw);
+      // No state on the request: nothing is cached under one to miss.
+      if (value === null) return;
       // rawStubHeaders: guard-exempt internal writer — invalidateClientCache()
       // is documented callable from loaders and during shell capture.
-      rawStubHeaders.append(
-        "Set-Cookie",
-        serializeStateCookie(stateCookieName, value, url.protocol === "https:"),
+      if (stateCookieLine !== null) dropSetCookieLine(stateCookieLine);
+      stateCookieLine = serializeStateCookie(
+        stateCookieName,
+        value,
+        url.protocol === "https:",
       );
+      rawStubHeaders.append("Set-Cookie", stateCookieLine);
       invalidateResponseCookieCache();
     },
 
     // Set the keepClientCache() directive header. The action bridge reads it on
     // the response and suppresses its automatic invalidation. `.set` makes this
     // idempotent (one header regardless of call count). rawStubHeaders:
-    // guard-exempt internal writer.
+    // guard-exempt internal writer. A write bump already written (the action
+    // body ended, then global middleware after next() or a loader of the
+    // revalidation called it) is withdrawn: keepClientCache() bumps nothing.
     _setKeepCacheDirective(): void {
       rawStubHeaders.set(KEEP_CACHE_HEADER, "1");
+      if (rangoStateRotated === "write" && stateCookieLine !== null) {
+        dropSetCookieLine(stateCookieLine);
+        stateCookieLine = null;
+        rangoStateRotated = null;
+        invalidateResponseCookieCache();
+      }
     },
 
     // The fresh-reads cookie (browser/cookie-name.ts): one Set-Cookie per
@@ -1685,12 +1794,7 @@ export function createRequestContext<TEnv>(
         `${freshCookie}=1; Max-Age=${age}; Path=/; HttpOnly; SameSite=Lax` +
         (url.protocol === "https:" ? "; Secure" : "");
       if (freshCookieMaxAge > 0) {
-        const prior = serialized(freshCookieMaxAge);
-        const kept = rawStubHeaders
-          .getSetCookie()
-          .filter((cookie) => cookie !== prior);
-        rawStubHeaders.delete("Set-Cookie");
-        for (const cookie of kept) rawStubHeaders.append("Set-Cookie", cookie);
+        dropSetCookieLine(serialized(freshCookieMaxAge));
       }
       freshCookieMaxAge = maxAge;
       rawStubHeaders.append("Set-Cookie", serialized(maxAge));

package/src/testing/dispatch.ts

@@ -177,6 +177,10 @@ interface DispatchableRouter<TEnv> {
   onTimeout?: OnTimeoutCallback<TEnv>;
   findMatch: ClassifyRequestDeps<TEnv>["findMatch"];
   basename?: string;
+  /** The rango state cookie name (RangoInternal field). */
+  resolvedStateCookieName: string;
+  /** The in-memory prefetch TTL in ms (RangoInternal field). */
+  prefetchCacheTTL: number;
   cache?:
     | {
         enabled?: boolean;
@@ -292,6 +296,8 @@ export async function dispatch<TEnv = any>(
       telemetry: router.telemetry,
       timeouts: router.timeouts,
       onTimeout: router.onTimeout,
+      resolvedStateCookieName: router.resolvedStateCookieName,
+      prefetchCacheTTL: router.prefetchCacheTTL,
     },
     callOnError: stages.createErrorReporter<TEnv>(router),
     // A response-route handler's own throw is serialized into the same typed

package/src/testing/e2e/fixture.ts

@@ -10,6 +10,7 @@ import {
   runCli,
   type RunCliHandle,
   type SpawnOptions,
+  stopServer,
   waitForReady,
   warmupDevServer,
 } from "./server.js";
@@ -93,10 +94,7 @@ export function createUseFixture(
         // throw (findPort/waitForReady). Otherwise a beforeAll failure leaves
         // afterAll's cleanup a no-op and orphans the dev server (plus workerd
         // children) for the rest of the run.
-        cleanup = async () => {
-          proc!.kill();
-          await proc!.done;
-        };
+        cleanup = () => stopServer(proc!);
         const port = await proc.findPort();
         baseURL = `http://localhost:${port}`;
         const readyUrl = options.readyPath
@@ -128,10 +126,7 @@ export function createUseFixture(
           });
           // The build is a finite process, but assign cleanup before the await
           // so a hung build is still killed if beforeAll is torn down.
-          cleanup = async () => {
-            buildProc.kill();
-            await buildProc.done;
-          };
+          cleanup = () => stopServer(buildProc);
           // Fail loudly on a nonzero build exit. Without this a failed build is
           // swallowed and preview serves the previous stale dist/ (green
           // production tests against old code), or times out with "Server not
@@ -155,10 +150,7 @@ export function createUseFixture(
         });
         // Switch cleanup to the preview process immediately after spawn, before
         // findPort/waitForReady can throw and orphan it.
-        cleanup = async () => {
-          proc!.kill();
-          await proc!.done;
-        };
+        cleanup = () => stopServer(proc!);
         const port = await proc.findPort();
         baseURL = `http://localhost:${port}`;
         const buildReadyUrl = options.readyPath

package/src/testing/e2e/server.ts

@@ -19,7 +19,13 @@ export interface RunCliHandle {
    */
   exitCode: Promise<number | null>;
   findPort: (timeoutMs?: number) => Promise<number>;
-  kill: () => void;
+  /**
+   * Stop the process and what it spawned (the whole process group). SIGTERM by
+   * default; `stopServer` escalates to SIGKILL for a process that outlives the
+   * wait.
+   */
+  kill: (signal?: NodeJS.Signals) => void;
+  readonly pid: number | undefined;
   stdout: () => string;
   stderr: () => string;
 }
@@ -34,9 +40,16 @@ export function runCli(
   // hits EOF immediately, so without CI=true the dev/preview server shuts itself
   // down before it finishes starting. Real CI runners set CI=true; mirror that for
   // locally-spawned servers so they stay alive for the duration of the tests.
+  // detached makes the child a process-group leader (pgid === pid), so kill()
+  // can signal the whole tree. `pnpm dev` spawns vite as a grandchild; without
+  // it process.kill(-pid) throws ESRCH, the fallback child.kill() stops only
+  // pnpm, and vite keeps running after the suite. Not on Windows: there
+  // detached opens a console window per server, and kill() already ends the
+  // tree with `taskkill /t`.
   const child = x(name!, args, {
     nodeOptions: {
       ...options,
+      detached: process.platform !== "win32",
       env: { ...process.env, CI: "true", ...options.env },
     },
   }).process!;
@@ -100,16 +113,16 @@ export function runCli(
     });
   }
 
-  function kill() {
+  function kill(signal: NodeJS.Signals = "SIGTERM") {
     if (process.platform === "win32") {
       spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"]);
     } else {
       // Kill entire process group (Vite spawns child processes like workerd).
       // Falls back to direct kill if process group kill fails.
       try {
-        process.kill(-child.pid!, "SIGTERM");
+        process.kill(-child.pid!, signal);
       } catch {
-        child.kill();
+        child.kill(signal);
       }
     }
   }
@@ -120,11 +133,85 @@ export function runCli(
     exitCode,
     findPort,
     kill,
+    get pid() {
+      return child.pid;
+    },
     stdout: () => stdout,
     stderr: () => stderr,
   };
 }
 
+/** How long `stopServer` waits for SIGTERM to take effect before SIGKILL. */
+const STOP_WAIT_MS = 10_000;
+/** How long `stopServer` waits for the SIGKILL to take effect. */
+const KILL_WAIT_MS = 2_000;
+
+/** Resolves true when `done` settled within `ms`, false when the timer won. */
+async function exitedWithin(done: Promise<unknown>, ms: number) {
+  let timer: NodeJS.Timeout | undefined;
+  const timedOut = new Promise<false>((resolve) => {
+    timer = setTimeout(() => resolve(false), ms);
+  });
+  try {
+    return await Promise.race([done.then(() => true as const), timedOut]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** True while a process of the group led by `pgid` exists (not on Windows). */
+function groupAlive(pgid: number): boolean {
+  if (process.platform === "win32") return false;
+  try {
+    process.kill(-pgid, 0);
+    return true;
+  } catch (error) {
+    // EPERM: the group exists but belongs to someone else. Only ESRCH is gone.
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * Resolves true once `server.done` settled and no process of its group is left,
+ * false when `ms` ran out first. The leader (`pnpm`) exiting says nothing about
+ * the vite it spawned, which can outlive it, so the group is polled too.
+ */
+async function groupExitedWithin(
+  server: RunCliHandle,
+  ms: number,
+): Promise<boolean> {
+  const deadline = Date.now() + ms;
+  if (!(await exitedWithin(server.done, ms))) return false;
+  const pgid = server.pid;
+  if (pgid === undefined) return true;
+  while (groupAlive(pgid)) {
+    if (Date.now() >= deadline) return false;
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  return true;
+}
+
+/**
+ * Stop a server started by `runCli` and wait for its whole process group to
+ * exit: SIGTERM to the group, then SIGKILL (and a log naming the pid) for a
+ * process that outlives the wait, so a leaked server is visible rather than
+ * left holding its port.
+ */
+export async function stopServer(
+  server: RunCliHandle,
+  options: { exitWaitMs?: number } = {},
+): Promise<void> {
+  const exitWaitMs = options.exitWaitMs ?? STOP_WAIT_MS;
+  server.kill();
+  if (await groupExitedWithin(server, exitWaitMs)) return;
+  console.error(
+    `[rango e2e] server (pid ${server.pid ?? "unknown"}) ignored SIGTERM for ` +
+      `${exitWaitMs} ms and was sent SIGKILL`,
+  );
+  server.kill("SIGKILL");
+  await groupExitedWithin(server, KILL_WAIT_MS);
+}
+
 export function tailOutput(text: string, maxChars = 4000): string {
   if (!text) return "(empty)";
   if (text.length <= maxChars) return text;