@rangojs/router 0.4.1 → 0.4.2

package/src/cache/document-cache.ts

@@ -24,6 +24,10 @@ import { mayNeedSSR } from "../rsc/ssr-setup.js";
 import { cacheKeyBase } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
 import { reportCacheError } from "./cache-error.js";
+import {
+  SEGMENT_FRAGMENT_CAPABILITY_HEADER,
+  SEGMENT_FRAGMENT_RECOVERY_HEADER,
+} from "../segment-fragments.js";
 
 const CACHE_STATUS_HEADER = "x-document-cache-status";
 
@@ -260,6 +264,8 @@ export function createDocumentCacheMiddleware<TEnv = any>(
     // pipeline (stripInternalParams), so _rsc_partial, _rsc_segments, etc.
     // are not visible on ctx.url in production.
     const rawUrl = new URL(ctx.request.url);
+    const isFragmentRecovery =
+      ctx.request.headers.get(SEGMENT_FRAGMENT_RECOVERY_HEADER) === "1";
 
     // Only cache GET requests — mutations and other methods must not be cached
     if (ctx.request.method !== "GET") {
@@ -317,6 +323,16 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       const clientSegments = rawUrl.searchParams.get("_rsc_segments") || "";
       const segmentHash =
         isPartial && clientSegments ? `:${hashSegmentIds(clientSegments)}` : "";
+      // Fragment envelopes require a capable Rango decoder. Keep that wire
+      // variant out of the context-less/legacy partial slot; this middleware
+      // returns hits before request classification and cannot rely on the
+      // match-time capability gate.
+      const fragmentSuffix =
+        isPartial &&
+        (ctx.request.headers.get(SEGMENT_FRAGMENT_CAPABILITY_HEADER) === "1" ||
+          isFragmentRecovery)
+          ? ":fragments"
+          : "";
       const typeSuffix = isRscRequest ? ":rsc" : ":html";
 
       // Default key rides the shared host-namespaced base (cacheKeyBase) so the
@@ -326,7 +342,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // owns its own namespacing (auto-prefixing host would silently change their
       // existing keys and double any host they already include).
       const cacheKey = keyGenerator
-        ? keyGenerator(url) + segmentHash + typeSuffix
+        ? keyGenerator(url) + segmentHash + fragmentSuffix + typeSuffix
         : cacheKeyBase(
             url.host,
             url.pathname,
@@ -335,9 +351,15 @@ export function createDocumentCacheMiddleware<TEnv = any>(
             requestCtx?._searchParamsFilter,
           ) +
           segmentHash +
+          fragmentSuffix +
           typeSuffix;
       // 1. Check cache
-      const cached = await store.getResponse(cacheKey);
+      // Recovery must reach CacheScope's server decoder so it can evict the bad
+      // segment. Treat it as a miss, then let the ordinary write path replace
+      // the corrupt fragment-capable response with the valid fallback bytes.
+      const cached = isFragmentRecovery
+        ? null
+        : await store.getResponse(cacheKey);
 
       if (cached && cached.response.status === 200) {
         if (!cached.shouldRevalidate) {

package/src/rsc/rsc-rendering.ts

@@ -83,6 +83,10 @@ import type {
   ShellCacheEntry,
   ShellSnapshotRecord,
 } from "../cache/types.js";
+import {
+  SEGMENT_FRAGMENT_CAPABILITY_HEADER,
+  SEGMENT_FRAGMENT_RECOVERY_HEADER,
+} from "../segment-fragments.js";
 
 type PprReplayBypassReason =
   | "method"
@@ -285,6 +289,7 @@ async function handleRscRenderingInner<TEnv>(
   let hasInterceptSlots = false;
   let pprReplayStatus: PprReplayStatus | undefined;
   let partialCaptureNeeded = false;
+  let partialCaptureKey: string | undefined;
 
   // --- Axis 2: integrated PPR shell serve (docs/design/ppr-shell-resume.md) ---
   //
@@ -494,6 +499,7 @@ async function handleRscRenderingInner<TEnv>(
     pprReplayStatus = replay.status;
     partialCaptureNeeded =
       "captureNeeded" in replay && replay.captureNeeded === true;
+    partialCaptureKey = "captureKey" in replay ? replay.captureKey : undefined;
 
     if (!result) {
       // Fall back to full render
@@ -612,7 +618,7 @@ async function handleRscRenderingInner<TEnv>(
 
   const rscHeaders: Record<string, string> = {
     "content-type": "text/x-component;charset=utf-8",
-    vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
+    vary: `accept, X-Rango-State, X-RSC-Router-Client-Path, ${SEGMENT_FRAGMENT_CAPABILITY_HEADER}, ${SEGMENT_FRAGMENT_RECOVERY_HEADER}`,
     // Router identity, so the client can verify pre-decode (before importing
     // chunks) that this content payload belongs to its app and refuse a
     // foreign one (cache/proxy/bug). Control-only reload/redirect responses
@@ -721,7 +727,8 @@ async function handleRscRenderingInner<TEnv>(
       },
       createShellCaptureDescriptor(
         ctx,
-        buildNavigationShellKey(url, reqCtx._searchParamsFilter),
+        partialCaptureKey ??
+          buildNavigationShellKey(url, reqCtx._searchParamsFilter),
         pprConfig,
         store,
         true,
@@ -765,8 +772,30 @@ async function matchPartialWithPprReplay<TEnv>(
     recordReplayStatus(finalStatus);
     return finalStatus;
   };
+  let armFragments = false;
+  /**
+   * Every matchPartial in this function runs through this helper so the
+   * fragment flag (#700 passthrough, armed below the navigation-context gate)
+   * can never outlive a match or miss a lane — a thrown-Response redirect
+   * exit included. Mutate-restore on the SHARED reqCtx, never a derived
+   * context: the pipeline writes ambient state during the match that must
+   * land on reqCtx (_pprReplayPostMatchReason, location state,
+   * _treeHasStreaming read by the render-barrier closure). Assign-back
+   * restore leaves an own `undefined` after the first arm, matching the
+   * _shellImplicitCache idiom.
+   */
+  const matchPartialForReplay = async () => {
+    if (!armFragments) return ctx.router.matchPartial(request, { env });
+    const prevFragmentPayload = reqCtx._shellFragmentPayload;
+    reqCtx._shellFragmentPayload = true;
+    try {
+      return await ctx.router.matchPartial(request, { env });
+    } finally {
+      reqCtx._shellFragmentPayload = prevFragmentPayload;
+    }
+  };
   const runMatch = async (status?: PprReplayStatus) => {
-    const result = await ctx.router.matchPartial(request, { env });
+    const result = await matchPartialForReplay();
     // The match may have settled a fact the pre-match gate could only guess
     // at (prerender serve, intercept resolution) — report the truth.
     const finalStatus = status ? finalizeReplayStatus(status) : undefined;
@@ -803,6 +832,14 @@ async function matchPartialWithPprReplay<TEnv>(
   if (!getNavigationContextHeader(request)) {
     return runMatch({ outcome: "BYPASS", reason: "no-navigation-context" });
   }
+  // Fragment passthrough (#700), extended to partial replay. Navigation
+  // context proves the request can be matched; the separate capability header
+  // proves its payload consumer can expand envelopes. Older clients and the
+  // one-shot corruption recovery request still replay the same segment record,
+  // but through the server decode path.
+  armFragments =
+    request.headers.get(SEGMENT_FRAGMENT_RECOVERY_HEADER) !== "1" &&
+    request.headers.get(SEGMENT_FRAGMENT_CAPABILITY_HEADER) === "1";
   // The prerender probe and the cache-opt-out gate below both need the
   // classified snapshot; resolve (and persist) it once.
   const routeSnapshot = classifiedRouteSnapshot(reqCtx);
@@ -863,11 +900,13 @@ async function matchPartialWithPprReplay<TEnv>(
 
   let bypassReason: PprReplayBypassReason | undefined;
   let snapshot: ShellSnapshotRecord[] | undefined;
+  let snapshotStoreKey: string | undefined;
   let freshness: "fresh" | "stale" = "fresh";
   if (cached) {
     const decision = replayableShellSnapshot(cached.entry, ctx.version);
     if ("snapshot" in decision) {
       snapshot = decision.snapshot;
+      snapshotStoreKey = key;
       freshness = cached.shouldRevalidate ? "stale" : "fresh";
     } else {
       bypassReason = decision.reason;
@@ -895,6 +934,7 @@ async function matchPartialWithPprReplay<TEnv>(
       );
       if ("snapshot" in decision) {
         snapshot = decision.snapshot;
+        snapshotStoreKey = navigationKey;
         freshness = navigationCached.shouldRevalidate ? "stale" : "fresh";
       } else {
         bypassReason = decision.reason;
@@ -954,7 +994,7 @@ async function matchPartialWithPprReplay<TEnv>(
         },
       };
       try {
-        const result = await ctx.router.matchPartial(request, { env });
+        const result = await matchPartialForReplay();
         const provisionalStatus: PprReplayStatus = explicitCacheBypass
           ? { outcome: "BYPASS", reason: "cache-disabled" }
           : explicitCacheHit
@@ -999,6 +1039,7 @@ async function matchPartialWithPprReplay<TEnv>(
 
   const previousImplicitCache = reqCtx._shellImplicitCache;
   let segmentReplayHit = false;
+  let segmentReplayCorrupt = false;
   let explicitCacheHit = false;
   let explicitCacheBypass = false;
   reqCtx._shellImplicitCache = {
@@ -1011,6 +1052,9 @@ async function matchPartialWithPprReplay<TEnv>(
     onHit: () => {
       segmentReplayHit = true;
     },
+    onCorrupt: () => {
+      segmentReplayCorrupt = true;
+    },
     // Arms the explicit-scope composition in withCacheLookup: a route-derived
     // cache() scope stays authoritative, the seeded doc record supplies the
     // match only on its miss. An explicit-tier hit must NOT report a replay
@@ -1027,7 +1071,7 @@ async function matchPartialWithPprReplay<TEnv>(
   };
 
   try {
-    const result = await ctx.router.matchPartial(request, { env });
+    const result = await matchPartialForReplay();
     const provisionalStatus: PprReplayStatus = segmentReplayHit
       ? { outcome: "HIT", freshness }
       : explicitCacheHit
@@ -1040,7 +1084,18 @@ async function matchPartialWithPprReplay<TEnv>(
     // keep snapshot.cacheScope) — the "snapshot-miss" guess would blame the
     // capture for a lane that was never in play.
     const status = finalizeReplayStatus(provisionalStatus);
-    return { result, status };
+    return {
+      result,
+      status,
+      captureNeeded:
+        segmentReplayCorrupt && reqCtx._pprReplayPostMatchReason === undefined,
+      // A corrupt document snapshot must be overwritten at the document key;
+      // writing only the secondary navigation key would leave the preferred
+      // document entry shadowing the repair forever. The capture remains marked
+      // navigationOnly, so a document request ignores it and recaptures a
+      // document-safe shell under the same key.
+      captureKey: segmentReplayCorrupt ? snapshotStoreKey : undefined,
+    };
   } finally {
     reqCtx._shellImplicitCache = previousImplicitCache;
   }

package/src/rsc/shell-capture.ts

@@ -945,8 +945,9 @@ export function scheduleShellCapture(
  *   I/O failure is reported separately and does NOT make the attempt retryable —
  *   the capture itself worked).
  * - `redirect`: the matched route redirects, so there is no shell to capture.
- * - `no-shell`: the prelude came back trivial (no <body>) OR captureShellHTML
- *   rejected with our own abort. This is the only RETRYABLE outcome.
+ * - `no-shell`: captureShellHTML returned null because the prelude was unusable
+ *   or its private capture abort landed before the shell completed. This is the
+ *   only RETRYABLE outcome.
  */
 type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
 
@@ -995,9 +996,9 @@ type CaptureAttemptStats = Pick<
  * when we froze the shell; the attempt itself warmed the module graph, so a second
  * attempt a short beat later usually completes the shell in the SAME background
  * task. That kills the old multi-request warmup where the caller had to re-issue
- * several HTTP requests before a capture stuck. We retry ONLY on `no-shell` (and a
- * defensively-caught abort); a genuine render error is NOT retried — it propagates
- * to scheduleShellCapture's reportCacheError. See docs/design/ppr-shell-resume.md.
+ * several HTTP requests before a capture stuck. We retry ONLY on `no-shell`; a
+ * genuine render error is NOT retried — it propagates to scheduleShellCapture's
+ * reportCacheError. See docs/design/ppr-shell-resume.md.
  *
  * `retryDelayMs` is a parameter (defaulting to the module const) so unit tests can
  * drive the retry without a real 400ms wall-clock wait.
@@ -1329,6 +1330,10 @@ export function deriveShellCaptureContext(
   derivedCtx._explicitTaggedStores = new Set();
   derivedCtx._transitionWhen = [];
   derivedCtx._shellCaptureRun = true;
+  // Own-property reset: an inherited flag would make serializeSegments store
+  // a double-encoded fragment. No current arming site reaches a capture
+  // render (kept as defense-in-depth for a future one).
+  derivedCtx._shellFragmentPayload = false;
   derivedCtx._metricsStore = undefined;
   // Spans, like perf metrics above, are a FOREGROUND surface: the capture
   // re-render must not emit a second rango.render/loader/ssr set after the
@@ -1395,9 +1400,10 @@ export function deriveShellCaptureContext(
  * capture worked; only the store I/O failed). `ssrModule.captureShellHTML` MUST be
  * present (eligibility is checked before scheduling).
  *
- * A `no-shell` result (trivial prelude, or a defensively-caught abort) is the only
- * retryable outcome; a genuine (non-abort) captureShellHTML error propagates so it
- * reaches reportCacheError and is NOT retried.
+ * A `no-shell` result from captureShellHTML is the only retryable outcome. Every
+ * captureShellHTML error propagates to reportCacheError and is NOT retried. The
+ * capture handler converts only its own private abort sentinel to null before this
+ * layer sees it.
  */
 async function captureAndStoreShell(
   ssrModule: SSRModule,
@@ -1504,19 +1510,13 @@ async function captureAndStoreShell(
         }),
       );
     } catch (error) {
-      // Guard-tripped rejection arrives here (not at the drain) — refuse
-      // BEFORE the AbortError-vs-rethrow decision below.
+      // Guard-tripped rejection arrives here (not at the drain), so refuse it
+      // before propagating other capture errors.
       const refused = refuseOnGuardTrip();
       if (refused) return refused;
-      // captureShellHTML normally converts its OWN deliberate abort to a null
-      // return (index.tsx). This catch is defensive: if an AbortError still escapes
-      // (a runtime where the abort surfaces as a stream rejection outside its
-      // guard), treat it as the same retryable "no usable shell" degradation rather
-      // than a failure — do NOT report it as an error. A genuine (non-abort) render
-      // error is a real failure: rethrow so it reaches reportCacheError (no retry).
-      if ((error as { name?: string } | null)?.name === "AbortError") {
-        return "no-shell";
-      }
+      // captureShellHTML converts its OWN deliberate abort to null by sentinel
+      // identity. An escaped AbortError can therefore be a component's real
+      // cancellation and must not be hidden or retried by name.
       throw error;
     }
 

package/src/segment-fragments.ts

@@ -6,10 +6,11 @@
  * fragment STRINGS ride the outgoing payload verbatim inside these envelopes
  * — the outer Flight render copies a string instead of re-serializing a whole
  * element tree — and the CONSUMER expands each envelope through its own Flight
- * deserializer: the SSR resume pass (ssr/ssr-root.tsx) and browser hydration
- * (browser/rsc-router.tsx). Each fragment is its own row space, decoded
- * independently, exactly like the segment codec's per-record decode — so
- * there is no Flight row-id collision or shared-row dedupe hazard.
+ * deserializer: the SSR resume pass (ssr/ssr-root.tsx), browser hydration, and
+ * capability-gated partial navigation/prefetch decoders. Each fragment is its
+ * own row space, decoded independently, exactly like the segment codec's
+ * per-record decode — so there is no Flight row-id collision or shared-row
+ * dedupe hazard.
  *
  * Envelopes appear ONLY on fields that hold ReactNodes (component / layout /
  * loading). A plain object is never a valid ReactNode, so the marker cannot
@@ -22,6 +23,25 @@
 
 import type { ResolvedSegment } from "./types.js";
 
+/** Partial-request capability gate for browser-side fragment expansion. */
+export const SEGMENT_FRAGMENT_CAPABILITY_HEADER: string =
+  "X-Rango-Fragment-Passthrough";
+
+/** One-shot request marker that forces server-side fragment validation. */
+export const SEGMENT_FRAGMENT_RECOVERY_HEADER: string =
+  "X-Rango-Fragment-Recovery";
+
+/** A stored fragment failed in its consumer-side Flight decoder. */
+export class SegmentFragmentDecodeError extends Error {
+  readonly cause: unknown;
+
+  constructor(cause: unknown) {
+    super("Failed to decode a stored RSC segment fragment");
+    this.name = "SegmentFragmentDecodeError";
+    this.cause = cause;
+  }
+}
+
 /**
  * One RSC-encoded fragment traveling inside an RscPayload segment field.
  * `f` is the stored Flight document (segment-codec output) for that field.
@@ -107,6 +127,27 @@ export async function expandSegmentFragments(
   if (decodes.length > 0) await Promise.all(decodes);
 }
 
+/**
+ * Expand every envelope in an RscPayload-shaped object, in place. Decode
+ * failures use a distinct error so partial navigation can retry once through
+ * the server's decode-and-evict path. The
+ * hasSegmentFragments pre-scan keeps envelope-free payloads — every
+ * non-replay response — to one synchronous field walk; this runs on every
+ * navigation and prefetch decode.
+ */
+export async function expandPayloadFragments(
+  payload: { metadata?: { segments?: ResolvedSegment[] } },
+  decode: FragmentDecoder,
+): Promise<void> {
+  const segments = payload.metadata?.segments;
+  if (!hasSegmentFragments(segments)) return;
+  try {
+    await expandSegmentFragments(segments, decode);
+  } catch (error) {
+    throw new SegmentFragmentDecodeError(error);
+  }
+}
+
 /**
  * True when any segment carries an unexpanded envelope. Cheap scan used by
  * consumers that only need to know whether an expansion pass is required.

package/src/server/request-context.ts

@@ -303,6 +303,12 @@ export interface RequestContext<
     keyPrefix?: "doc";
     /** @internal Called only after the implicit cache hit decodes successfully. */
     onHit?: () => void;
+    /**
+     * @internal Called when the seeded document record fails server-side
+     * deserialization. Partial replay uses it to replace the enclosing shell
+     * snapshot after serving the fresh fallback.
+     */
+    onCorrupt?: () => void;
     /**
      * @internal The resolved key of the canonical document segment record.
      * Written during a CAPTURE render by CacheScope.cacheRoute when a
@@ -334,15 +340,22 @@ export interface RequestContext<
   };
 
   /**
-   * @internal Shell-HIT tail marker: cache/prerender-store hits during THIS
-   * render emit stored segment fragments VERBATIM into the payload
+   * @internal Fragment-passthrough marker: cache/prerender-store hits during
+   * THIS render emit stored segment fragments VERBATIM into the payload
    * (segment-codec fragmentSegments) instead of deserialize -> re-serialize
-   * per request; the payload consumers (SSR resume + browser hydration)
-   * expand them (segment-fragments.ts, issue #700). Own property of
-   * serveShellHit's derived tail context ONLY — it must never be visible to a
-   * capture render: the capture SSR-prerenders the payload AND serializes
-   * segments into records (cacheRoute), and an envelope reaching
-   * serializeSegments would store a double-encoded fragment.
+   * per request; the payload consumers (SSR resume, browser hydration, and
+   * the client partial-navigation decode chokepoints) expand them
+   * (segment-fragments.ts, issue #700). Partial requests arm only after the
+   * browser advertises `X-Rango-Fragment-Passthrough: 1`; a decode failure
+   * retries without it so CacheScope can evict the bad record. Two arming sites,
+   * both scoped to a
+   * render/match window: serveShellHit's derived tail context (document
+   * HIT), and matchPartialWithPprReplay's mutate-restore around the partial
+   * match (matchPartialForReplay). It must never be visible to a capture
+   * render: the capture SSR-prerenders the payload AND serializes segments
+   * into records (cacheRoute), and an envelope reaching serializeSegments
+   * would store a double-encoded fragment — deriveShellCaptureContext resets
+   * it as an own property for exactly that reason.
    */
   _shellFragmentPayload?: boolean;