@rangojs/router 0.17.0 → 0.19.0

package/src/rsc/server-action.ts

@@ -15,6 +15,7 @@
  * wraps revalidation inside route middleware — identical to a normal render.
  */
 
+import { requestHeaders } from "../server/request-headers.js";
 import {
   getRequestContext,
   setRequestContextParams,
@@ -22,7 +23,8 @@ import {
 import { observePhase, PHASES } from "../router/instrument.js";
 import { resolveActionRefId } from "../router/is-action.js";
 import type { TraceSpan } from "../router/tracing.js";
-import { gateTransitions } from "./transition-gate.js";
+import { attachTransitionWhen } from "./attach-transition-when.js";
+import { publicRouteName } from "../route-name.js";
 import type { RscPayload } from "./types.js";
 import {
   hasBodyContent,
@@ -93,7 +95,7 @@ export async function executeServerAction<TEnv>(
   const temporaryReferences = ctx.createTemporaryReferenceSet();
 
   // Decode action arguments from request body
-  const contentType = request.headers.get("content-type") || "";
+  const contentType = requestHeaders(request).get("content-type") || "";
   let args: unknown[] = [];
   let actionFormData: FormData | undefined;
 
@@ -381,14 +383,6 @@ async function revalidateAfterActionInner<TEnv>(
 ): Promise<Response> {
   const reqCtx = getRequestContext();
   const { actionContext } = continuation;
-  // Expose the action that triggered this revalidation to the transition({ when })
-  // gate (covers both the error-boundary and success gate calls below). Mirrors
-  // the action fields a revalidate() predicate sees.
-  reqCtx._gateActionId = actionContext?.actionId;
-  reqCtx._gateActionUrl = actionContext?.actionUrl;
-  reqCtx._gateActionResult = actionContext?.actionResult;
-  reqCtx._gateFormData = actionContext?.formData;
-
   // Mark the rest of this request as an action revalidation render. The "use
   // cache" runtime reads this to re-execute a stale entry in the foreground
   // (fresh data in the action response) rather than serving stale + revalidating
@@ -523,16 +517,13 @@ function renderActionBoundaryResponse<TEnv>(
       // routerId exposed for the frontend (current app identity); see
       // rsc-rendering.ts partial branch.
       routerId: ctx.router.id,
-      segments: gateTransitions(
-        errorBoundary.segments,
-        reqCtx,
-        ctx.router.onError,
-      ),
+      segments: attachTransitionWhen(errorBoundary.segments, reqCtx),
       isPartial: true,
       matched: errorBoundary.matched,
       diff: errorBoundary.diff,
       resolvedIds: errorBoundary.resolvedIds,
       params: errorBoundary.params,
+      routeName: publicRouteName(errorBoundary.routeName),
       isError: true,
       handles: handleStore.stream(),
       version: ctx.version,
@@ -589,16 +580,13 @@ function renderRevalidationResponse<TEnv>(
       // routerId exposed for the frontend (current app identity); see
       // rsc-rendering.ts partial branch.
       routerId: ctx.router.id,
-      segments: gateTransitions(
-        matchResult.segments,
-        reqCtx,
-        ctx.router.onError,
-      ),
+      segments: attachTransitionWhen(matchResult.segments, reqCtx),
       isPartial: true,
       matched: matchResult.matched,
       diff: matchResult.diff,
       resolvedIds: matchResult.resolvedIds,
       params: matchResult.params,
+      routeName: publicRouteName(matchResult.routeName),
       slots: matchResult.slots,
       handles: handleStore.stream(),
       version: ctx.version,

package/src/rsc/shell-build-manifest.ts

@@ -37,7 +37,11 @@ import {
   hasIntactShellPayload,
   isValidShellHit,
 } from "./shell-serve.js";
-import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture.js";
+import {
+  SHELL_CAPTURE_MAX_WAIT_MS,
+  resetShellWarningsForTests,
+  warnOnce,
+} from "./shell-capture-constants.js";
 import { buildShellManifestKey } from "../prerender/shell-manifest-key.js";
 
 /** One baked manifest record (the __ps asset module's default export). */
@@ -45,10 +49,8 @@ export interface BuildShellEntry {
   entry: ShellCacheEntry;
   /** Resolved ppr ttl (seconds) — drives staleness/recapture, never expiry. */
   ttl: number;
-  swr?: number;
   /** The putShell-barrier tag union baked at build (static + recorded). */
   tags?: string[];
-  routeName: string;
 }
 
 interface ShellManifestModule {
@@ -81,16 +83,16 @@ function loadManifest(): Promise<ShellManifestModule | null> {
 }
 
 /**
- * Per-spec verdict memo for the version + integrity gates. A manifest record
+ * Per-spec verdict memo for the version + structural gates. A manifest record
  * is immutable for the process lifetime (content-hashed asset module), so its
- * gate verdict is constant — without this, EVERY request to a baked ppr route
- * re-decodes the full prelude base64 (hasIntactShellPayload) on the hot path:
- * a fresh build hit never populates the runtime store, so the store MISS +
- * read-through is the steady state, not a warm-up. Only the per-request
- * gates (tag markers, staleness) stay outside the memo. `null` memoizes a
- * failed verdict — deterministically invalid, don't re-pay the decode.
- * Spec-only keying is sound because buildVersion is process-constant on the
- * manifest path (folded into the shipped worker; dev never loads a manifest).
+ * gate verdict is constant: a fresh build hit never populates the runtime
+ * store, so the store MISS + read-through is the steady state, not a warm-up.
+ * Only the per-request gates (tag markers, staleness) stay outside the memo;
+ * the document HIT decodes the prelude once per serve (openShellDocument),
+ * partial replay never does. `null` memoizes a failed verdict —
+ * deterministically invalid. Spec-only keying is sound because buildVersion is
+ * process-constant on the manifest path (folded into the shipped worker; dev
+ * never loads a manifest).
  */
 const validatedSpecs = new Map<string, ValidatedBuildShellEntry | null>();
 
@@ -121,15 +123,16 @@ async function validatedManifestRecord(
   return verdict ?? undefined;
 }
 
-/** Reset the memoized manifest (unit tests swap the global loader). */
+/**
+ * Reset the memoized manifest (unit tests swap the global loader) and the
+ * shell path's once-per-key warnings, the tag-check one included.
+ */
 export function resetBuildShellManifestForTests(): void {
   manifestPromise = null;
   validatedSpecs.clear();
+  resetShellWarningsForTests();
 }
 
-/** Keys already warned about a tag-check-incapable store (once per key). */
-const warnedTagCheckUnsupported = new Set<string>();
-
 export interface BuildShellHit {
   entry: DocumentShellCacheEntry;
   /** Past createdAt + ttl: serve, but schedule the runtime recapture. */
@@ -259,6 +262,24 @@ async function fetchDevShellEntry(
   }
 }
 
+/**
+ * Whether a build-time shell exists for `pathname` (the caller checks the
+ * request is search-less, like the entries lookupBuildShell serves): a
+ * manifest entry for the path in production, a Prerender route in dev. No
+ * asset load and no dev capture: it only decides whether a request that
+ * cannot read the build shell deserves a warning.
+ */
+export async function hasBuildShell(
+  pathname: string,
+  dev?: DevShellLookup,
+): Promise<boolean> {
+  if (globalThis.__loadShellManifestModule === undefined) {
+    return dev?.isPrerenderRoute === true;
+  }
+  const mod = await loadManifest();
+  return mod?.default[buildShellManifestKey(pathname)] !== undefined;
+}
+
 /**
  * Look up the baked shell entry for a request, applying every serve gate:
  * search-less requests only (the build captured the bare pathname; a
@@ -315,20 +336,19 @@ export async function lookupBuildShell(
         // memo-only answers would let the immutable asset resurrect on the
         // next request). Declared intent that cannot be honored deserves a
         // diagnostic; the route keeps runtime-capture semantics.
-        const key = buildShellManifestKey(url.pathname);
-        if (!warnedTagCheckUnsupported.has(key)) {
-          warnedTagCheckUnsupported.add(key);
-          console.warn(
+        warnOnce(
+          "build-shell-tag-check",
+          buildShellManifestKey(url.pathname),
+          () =>
             `[rango] Build-time shell for "${url.pathname}" carries cache tags, but ` +
-              "the app cache store cannot answer tag-invalidation history durably " +
-              (typeof check !== "function"
-                ? "(isTagsInvalidatedSince() is not implemented), "
-                : "(no durable tag history — a CFCacheStore without a KV namespace), ") +
-              "so updateTag() could not evict it. The entry is not served; the route " +
-              "keeps runtime shell capture. Use MemorySegmentCacheStore, a KV-backed " +
-              "CFCacheStore, or VercelCacheStore (or add the method to your custom store).",
-          );
-        }
+            "the app cache store cannot answer tag-invalidation history durably " +
+            (typeof check !== "function"
+              ? "(isTagsInvalidatedSince() is not implemented), "
+              : "(no durable tag history — a CFCacheStore without a KV namespace), ") +
+            "so updateTag() could not evict it. The entry is not served; the route " +
+            "keeps runtime shell capture. Use MemorySegmentCacheStore, a KV-backed " +
+            "CFCacheStore, or VercelCacheStore (or add the method to your custom store).",
+        );
         return null;
       }
       if (await check.call(store, record.tags, entry.createdAt)) return null;

package/src/rsc/shell-capture-constants.ts

@@ -1,31 +1,160 @@
+/**
+ * React-free leaf of the PPR shell path: its constants, the shell key
+ * builders, the status header names and bypass reasons, and the once-per-key
+ * warning registry. The ssr graph (ssr/index.tsx), the testing barrels
+ * (testing/shell-status.ts) and cookie-store.ts import from here without
+ * pulling the capture orchestration module or shell-serve.ts (React).
+ */
+
+import { sortedSearchString } from "../cache/cache-key-utils.js";
+import type { SearchParamsFilter } from "../cache/search-params-filter.js";
+
 /**
  * Default upper bound on the capture prerender wait before forcing the abort
  * that freezes the shell — the ONLY wall-clock on the capture path, and a
  * pathological guard: it should never fire once the caller's `quiesce` is a
  * task-quantized, frozen-byte signal (the capture gate in shell-capture.ts).
- *
- * Leaf module on purpose (imports nothing): shell-capture.ts re-exports it
- * (single import site for the rsc graph — shell-build-manifest.ts sizes the
- * dev fetch envelope from that re-export) and ssr/index.tsx uses it as
- * captureShellHTML's own fallback; the ssr graph must not pull the capture
- * orchestration module for one number.
+ * ssr/index.tsx uses it as captureShellHTML's own fallback.
  *
  * 15s, raised from 5s: captures are background work (waitUntil), so the budget
  * costs latency-to-HIT only — never a served response — and 5s spuriously
  * refused legitimately-slow deferred shell material (a real storefront's meta
  * chains settle at ~7s). Ceiling math: workerd's waitUntil lifetime is ~30s
- * past response completion, and a guaranteed two-attempt envelope needs
- * 2x budget + the in-place retry delay + store I/O, i.e. budget <= ~14s. The
- * 15s default deliberately sits just past that: attempt 1 always gets its
- * full 15s, but when it consumed the whole budget the in-place RETRY may be
- * truncated by the platform kill on workerd — degrading to the existing
- * best-effort contract (the key stays MISS; a later request re-captures).
+ * past response completion. An attempt that consumed the whole budget is not
+ * retried in place (shell-capture.ts CaptureAttemptStats.noShellCause), so
+ * the envelope is one budget plus store I/O; the retry follows only an
+ * attempt that ended early (a cold-module abort). Past the ceiling the
+ * platform kill degrades to the existing best-effort contract (the key stays
+ * MISS; a later request re-captures).
  * Node/dev and build-time captures have no waitUntil ceiling. The per-route
  * `ppr.captureTimeout` knob remains for tightening below the default. See
  * docs/design/ppr-shell-resume.md (Cost model).
  */
 export const SHELL_CAPTURE_MAX_WAIT_MS = 15_000;
 
+/** Debug/status header on a ppr document response: `HIT` | `MISS`. */
+export const SHELL_STATUS_HEADER: string = "x-rango-shell";
+
+/**
+ * Partial-navigation replay status header, set only after the captured
+ * segment record was consumed (`HIT`) or with the reason it was not.
+ */
+export const PPR_REPLAY_STATUS_HEADER: string = "x-rango-ppr-replay";
+
+/**
+ * Bounded reasons a partial request to a ppr route falls open to the ordinary
+ * match (`x-rango-ppr-replay: BYPASS; reason=<reason>`). One list for the
+ * producer (rsc-rendering.ts) and the parser (testing/shell-status.ts): a
+ * reason the parser does not list parses as null.
+ */
+export const PPR_REPLAY_BYPASS_REASONS = [
+  "method",
+  "dynamic",
+  "nonce",
+  "store-unavailable",
+  "passive-read-unsupported",
+  "no-navigation-context",
+  "prerender-store",
+  "intercept",
+  "cache-disabled",
+  "read-error",
+  "no-entry",
+  "invalid-version",
+  "corrupt-entry",
+  "no-segment-snapshot",
+  "snapshot-miss",
+  "explicit-cache-hit",
+] as const;
+
+/** One of {@link PPR_REPLAY_BYPASS_REASONS}. */
+export type PprReplayBypassReason = (typeof PPR_REPLAY_BYPASS_REASONS)[number];
+
+/**
+ * The shell key's search portion (`?`-prefixed sorted search with the
+ * cache.searchParams filter applied, or "") — ALSO the string the capture and
+ * resume SSR renders seed their store location with (SSRRenderOptions.search
+ * / ShellCaptureOptions.search / ShellResumeOptions.search). Search is part
+ * of shell identity, so static-part `useSearchParams` reads render exactly
+ * what the key names; deriving seed and key from this one helper is what
+ * keeps capture, resume, and lookup byte-agreed (drift = replay mismatch or
+ * permanent MISS).
+ */
+export function shellSearchSeed(url: URL, filter?: SearchParamsFilter): string {
+  const sorted = sortedSearchString(url.searchParams, filter);
+  return sorted ? `?${sorted}` : "";
+}
+
+/**
+ * Shell cache key: host + pathname + sorted search + a `:shell` namespace suffix
+ * (so it can never collide with a document-cache key; the store further isolates
+ * the shell family internally).
+ *
+ * The key includes the request HOST: in a multi-tenant host-router deployment
+ * (one worker, one shared KV/runtime-cache store) a host-less key would serve
+ * tenant A's captured shell to tenant B's users.
+ *
+ * `filter` is the request's compiled `cache.searchParams` config
+ * (ctx._searchParamsFilter): excluded params collapse onto one shell slot.
+ * Callers on the serve/capture path MUST pass it -- key drift between capture
+ * and lookup makes every shell request a permanent miss. The testing helper
+ * `shellCacheKey` (testing/shell-status.ts) builds its key with it too.
+ */
+export function buildShellKey(url: URL, filter?: SearchParamsFilter): string {
+  return `${url.host}${url.pathname}${shellSearchSeed(url, filter)}:shell`;
+}
+
+/**
+ * The shell key for one request partition (cache-scope.ts
+ * resolveShellPartition): the route cache() `key()` or store keyGenerator
+ * result that partitions the route's record partitions its shell too, so
+ * each partition captures and serves its own.
+ *
+ * The partition is URI-encoded: it is request-derived, and raw it could end
+ * in a suffix another key is built with (navigationShellKey), so a partition
+ * `gold:navigation` named gold's navigation entry and its document shell
+ * replayed to gold's navigations. Encoded, it holds no `:` or `|`.
+ */
+export function partitionShellKey(key: string, partition: string): string {
+  return `${key}|${encodeURIComponent(partition)}`;
+}
+
+/**
+ * The navigation-only entry beside a document shell key (a cold partial
+ * request's capture, rsc-rendering.ts). A suffix after the (encoded)
+ * partition: partitionShellKey keeps the two unambiguous.
+ */
+export function navigationShellKey(key: string): string {
+  return `${key}:navigation`;
+}
+
+/**
+ * Fixed number of macrotask hops between `quiesce` resolving and the abort. These
+ * give React's fizz worker turns to flush the settled shell into the prelude and
+ * mark still-pending boundaries as POSTPONED (rather than errored) before
+ * controller.abort() lands. Not a wall-clock wait. Taken by captureShellHTML
+ * (ssr/index.tsx) and by the testing SSR stub (testing/serve-shell-request.ts),
+ * so the stub freezes the same Flight the real capture would.
+ *
+ * Why 16 and not 2: the capture's Flight input is the doc record's stored
+ * fragments (settleCaptureRecord, shell-capture.ts), already serialized, so the
+ * render emits the whole shell payload in the first tick and the gate declares
+ * quiesce within a few ms, before fizz has rendered the shell to <body>. When
+ * the capture Flight dribbled out as handlers ran, Flight-quiet meant "the shell
+ * has rendered" and 2 hops sufficed.
+ *
+ * Hops alone are NOT render-readiness: fizz cannot emit even <html> until the
+ * payload root settles, nor complete a shell whose client components are
+ * still loading — real module-runner I/O in dev (100ms+ cold), which no fixed
+ * count of near-zero-cost task hops can buy. captureShellHTML therefore
+ * awaits the payload-settled signal (SsrRootOptions.onPayloadSettled) and
+ * then the client-reference loads in flight in the isolate (captureClientLoads),
+ * deadline-bounded, between quiesce and these hops; the hops then only flush
+ * the settled tree and mark pending boundaries POSTPONED. Still task-based
+ * (masked loaders never emit, so more hops never lets a hole settle). Bounded
+ * by maxWaitMs end to end.
+ */
+export const POST_QUIESCE_TASK_HOPS = 16;
+
 /**
  * Hard cap on one capture TASK — runShellCapture end to end (both attempts +
  * the in-place retry delay). SHELL_CAPTURE_MAX_WAIT_MS arms only inside
@@ -56,3 +185,44 @@ export const PPR_LANE_HINT: string =
   "non-promise data; every other loader is live (masked at capture, fresh per " +
   "request) and needs loading() or an inline <Suspense> above its reader. See the " +
   '/ppr skill, "The loader lane rule" (node_modules/@rangojs/router/skills/ppr/SKILL.md).';
+
+/**
+ * Once-per-key console warnings of the PPR shell path (the capture, the serve
+ * gates, the build-shell read-through), per isolate. One registry, so one
+ * reset clears them all ({@link resetShellWarningsForTests}).
+ */
+const warnedShellKeys = new Set<string>();
+
+function shellWarningId(scope: string, key: string): string {
+  return `${scope}\u0000${key}`;
+}
+
+/** Whether {@link warnOnce} already warned for `scope` and `key`. */
+export function hasWarnedOnce(scope: string, key: string): boolean {
+  return warnedShellKeys.has(shellWarningId(scope, key));
+}
+
+/**
+ * `console.warn(message())` once per `scope` and `key`; `message` is built only
+ * when it prints. Returns true when it warned.
+ */
+export function warnOnce(
+  scope: string,
+  key: string,
+  message: () => string,
+): boolean {
+  const id = shellWarningId(scope, key);
+  if (warnedShellKeys.has(id)) return false;
+  warnedShellKeys.add(id);
+  console.warn(message());
+  return true;
+}
+
+/**
+ * @internal Forget every once-per-key shell warning. Tests only: the capture,
+ * serve and build-shell resets (testing/serve-shell-request.ts
+ * resetShellTestState) call it.
+ */
+export function resetShellWarningsForTests(): void {
+  warnedShellKeys.clear();
+}