@rangojs/router 0.1.1 → 0.4.0

package/src/rsc/rsc-rendering.ts

@@ -40,6 +40,7 @@ import {
   type ShellCaptureDescriptor,
 } from "./shell-capture.js";
 import {
+  PPR_REPLAY_STATUS_HEADER,
   SHELL_STATUS_HEADER,
   resolvePprConfig,
   buildShellKey,
@@ -67,7 +68,84 @@ import {
 import { nonce as nonceToken } from "./nonce.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
-import type { ShellCacheEntry, ShellSnapshotRecord } from "../cache/types.js";
+import type {
+  SegmentCacheStore,
+  ShellCacheEntry,
+  ShellSnapshotRecord,
+} from "../cache/types.js";
+
+type PprReplayBypassReason =
+  | "method"
+  | "dynamic"
+  | "nonce"
+  | "store-unavailable"
+  | "passive-read-unsupported"
+  | "read-error"
+  | "no-entry"
+  | "invalid-version"
+  | "corrupt-entry"
+  | "handler-live-holes"
+  | "transition-when"
+  | "no-segment-snapshot"
+  | "snapshot-miss"
+  | "stale-build-entry";
+
+type PprReplayStatus =
+  | { outcome: "HIT"; freshness: "fresh" | "stale" }
+  | { outcome: "BYPASS"; reason: PprReplayBypassReason };
+
+type ShellReplayDecision =
+  | { snapshot: ShellSnapshotRecord[] }
+  | { reason: PprReplayBypassReason };
+
+function serializePprReplayStatus(status: PprReplayStatus): string {
+  return status.outcome === "HIT"
+    ? `HIT; freshness=${status.freshness}`
+    : `BYPASS; reason=${status.reason}`;
+}
+
+function describePprReplayStatus(status: PprReplayStatus): string {
+  return status.outcome === "HIT"
+    ? status.freshness
+    : `bypass:${status.reason}`;
+}
+
+function buildNavigationShellKey(url: URL): string {
+  return `${buildShellKey(url)}:navigation`;
+}
+
+function createShellCaptureDescriptor(
+  ctx: HandlerContext<any>,
+  key: string,
+  pprConfig: ResolvedPprConfig,
+  store: SegmentCacheStore<any>,
+  navigationOnly?: true,
+): ShellCaptureDescriptor {
+  return {
+    key,
+    buildVersion: ctx.version,
+    ttl: pprConfig.ttl,
+    swr: pprConfig.swr,
+    tags: pprConfig.tags,
+    captureTimeout: pprConfig.captureTimeout,
+    store,
+    debug: INTERNAL_RANGO_DEBUG,
+    maxSnapshotBytes: pprConfig.maxSnapshotBytes,
+    debugSink: resolveShellCaptureDebugSink(ctx.router.debugShellCapture),
+    navigationOnly,
+  };
+}
+
+function shouldHealReplayMiss(
+  reason: PprReplayBypassReason | undefined,
+): boolean {
+  return (
+    reason === undefined ||
+    reason === "invalid-version" ||
+    reason === "corrupt-entry" ||
+    reason === "stale-build-entry"
+  );
+}
 
 function resolveDevShellLookup(
   reqCtx: RequestContext<any>,
@@ -86,17 +164,15 @@ function resolveDevShellLookup(
 }
 
 function replayableShellSnapshot(
-  entry: ShellCacheEntry | undefined,
+  entry: ShellCacheEntry,
   buildVersion: string,
-): ShellSnapshotRecord[] | undefined {
-  if (
-    !entry ||
-    !isValidShellHit(entry, buildVersion) ||
-    entry.handlerLiveHoles ||
-    entry.transitionWhen
-  ) {
-    return undefined;
+): ShellReplayDecision {
+  if (!isValidShellHit(entry, buildVersion)) {
+    return { reason: "invalid-version" };
   }
+  if (!hasIntactShellPayload(entry)) return { reason: "corrupt-entry" };
+  if (entry.handlerLiveHoles) return { reason: "handler-live-holes" };
+  if (entry.transitionWhen) return { reason: "transition-when" };
   const snapshot = entry.snapshot;
   const hasSegments = snapshot?.some((record) => {
     if (
@@ -111,7 +187,9 @@ function replayableShellSnapshot(
     const segments = (record.value as { segments?: unknown }).segments;
     return Array.isArray(segments) && segments.length > 0;
   });
-  return hasSegments ? snapshot : undefined;
+  return hasSegments && snapshot
+    ? { snapshot }
+    : { reason: "no-segment-snapshot" };
 }
 
 export function handleRscRendering<TEnv>(
@@ -156,6 +234,8 @@ async function handleRscRenderingInner<TEnv>(
 
   let payload: RscPayload;
   let hasInterceptSlots = false;
+  let pprReplayStatus: PprReplayStatus | undefined;
+  let partialCaptureNeeded = false;
 
   // --- Axis 2: integrated PPR shell serve (docs/design/ppr-shell-resume.md) ---
   //
@@ -242,23 +322,12 @@ async function handleRscRenderingInner<TEnv>(
           ssrModule.resumeShellHTML &&
           ssrModule.captureShellHTML
         ) {
-          const descriptor: ShellCaptureDescriptor = {
+          const descriptor = createShellCaptureDescriptor(
+            ctx,
             key,
-            buildVersion: ctx.version,
-            ttl: pprConfig.ttl,
-            swr: pprConfig.swr,
-            tags: pprConfig.tags,
-            captureTimeout: pprConfig.captureTimeout,
+            pprConfig,
             store,
-            debug: INTERNAL_RANGO_DEBUG,
-            maxSnapshotBytes: pprConfig.maxSnapshotBytes,
-            // The resolver owns the whole policy: option wins, the
-            // INTERNAL_RANGO_DEBUG env flag lights the events up when no
-            // option is set, an explicit `false` stays off.
-            debugSink: resolveShellCaptureDebugSink(
-              ctx.router.debugShellCapture,
-            ),
-          };
+          );
           // One serve funnel for BOTH entry sources (runtime store hit below,
           // build-manifest hit further down): schedule the background
           // recapture when asked, then commit the composed response.
@@ -309,7 +378,11 @@ async function handleRscRenderingInner<TEnv>(
               cached ? "hit" : "miss",
             );
           }
-          if (cached && isValidShellHit(cached.entry, ctx.version)) {
+          if (
+            cached &&
+            !cached.entry.navigationOnly &&
+            isValidShellHit(cached.entry, ctx.version)
+          ) {
             if (!hasIntactShellPayload(cached.entry)) {
               // Corrupt stored payload (undecodable prelude / unparseable
               // postponed): a store-layer fault worth a diagnostic, unlike the
@@ -359,7 +432,7 @@ async function handleRscRenderingInner<TEnv>(
 
   if (isPartial) {
     // Partial render (navigation)
-    const result = await matchPartialWithPprReplay(
+    const replay = await matchPartialWithPprReplay(
       ctx,
       request,
       env,
@@ -367,6 +440,10 @@ async function handleRscRenderingInner<TEnv>(
       reqCtx,
       nonce,
     );
+    const result = replay.result;
+    pprReplayStatus = replay.status;
+    partialCaptureNeeded =
+      "captureNeeded" in replay && replay.captureNeeded === true;
 
     if (!result) {
       // Fall back to full render
@@ -378,10 +455,17 @@ async function handleRscRenderingInner<TEnv>(
         // perform SPA navigation. A raw 308 would be auto-followed by
         // fetch, hitting the target without _rsc_partial. Resolve the
         // target server-side (same open-redirect policy as 3xx).
-        return createSimpleRedirectResponse(match.redirect, {
+        const redirectResponse = createSimpleRedirectResponse(match.redirect, {
           requestOrigin: url.origin,
           basename: ctx.router.basename,
         });
+        if (pprReplayStatus) {
+          redirectResponse.headers.set(
+            PPR_REPLAY_STATUS_HEADER,
+            serializePprReplayStatus(pprReplayStatus),
+          );
+        }
+        return redirectResponse;
       }
 
       payload = buildFullPayload(match, ctx, url, reqCtx, handleStore);
@@ -415,6 +499,7 @@ async function handleRscRenderingInner<TEnv>(
           prefetchCacheTTL: ctx.router.prefetchCacheTTL,
           prefetchCacheSize: ctx.router.prefetchCacheSize,
           prefetchConcurrency: ctx.router.prefetchConcurrency,
+          defaultPrefetch: ctx.router.defaultPrefetch,
           stateCookieName: ctx.router.resolvedStateCookieName,
         },
       };
@@ -484,6 +569,10 @@ async function handleRscRenderingInner<TEnv>(
     // are deliberately NOT stamped. See browser/response-adapter.ts.
     "X-RSC-Router-Id": ctx.router.id,
   };
+  if (pprReplayStatus) {
+    rscHeaders[PPR_REPLAY_STATUS_HEADER] =
+      serializePprReplayStatus(pprReplayStatus);
+  }
   // Tell the client's prefetch cache to scope this response to its source
   // URL (instead of the default source-agnostic wildcard). Intercept
   // responses depend on the source page matching an intercept rule, so
@@ -556,6 +645,40 @@ async function handleRscRenderingInner<TEnv>(
     response.headers.set(SHELL_STATUS_HEADER, "MISS");
   }
 
+  if (
+    isPartial &&
+    partialCaptureNeeded &&
+    !reqCtx._dynamic &&
+    response.status === 200
+  ) {
+    const pprConfig = resolvePprConfig(reqCtx._classifiedRoute?.manifestEntry)!;
+    const store = reqCtx._cacheStore!;
+    scheduleShellCapture(
+      ctx,
+      request,
+      env,
+      url,
+      reqCtx,
+      async (captureRequest, captureUrl) => {
+        const [ssrModule, streamMode] = await getSSRSetup(
+          ctx,
+          captureRequest,
+          env,
+          captureUrl,
+          undefined,
+        );
+        return streamMode === "allReady" ? null : ssrModule;
+      },
+      createShellCaptureDescriptor(
+        ctx,
+        buildNavigationShellKey(url),
+        pprConfig,
+        store,
+        true,
+      ),
+    );
+  }
+
   return response;
 }
 
@@ -575,57 +698,147 @@ async function matchPartialWithPprReplay<TEnv>(
   reqCtx: RequestContext<any>,
   nonce: string | undefined,
 ) {
-  const runMatch = () => ctx.router.matchPartial(request, { env });
+  const replayStart = reqCtx._metricsStore ? performance.now() : 0;
+  const recordReplayStatus = (status: PprReplayStatus): void => {
+    if (!reqCtx._metricsStore) return;
+    appendMetric(
+      reqCtx._metricsStore,
+      "ppr:navigation-replay",
+      replayStart,
+      performance.now() - replayStart,
+      undefined,
+      describePprReplayStatus(status),
+    );
+  };
+  const runMatch = async (status?: PprReplayStatus) => {
+    const result = await ctx.router.matchPartial(request, { env });
+    if (status) recordReplayStatus(status);
+    return { result, status };
+  };
   const pprConfig = resolvePprConfig(reqCtx._classifiedRoute?.manifestEntry);
   const activeNonce = nonce ?? contextGet(reqCtx._variables, nonceToken);
   const store = reqCtx._cacheStore;
 
-  if (
-    request.method !== "GET" ||
-    !pprConfig ||
-    reqCtx._dynamic ||
-    activeNonce !== undefined ||
-    !hasShellFamily(store) ||
-    store.supportsPassiveShellReads !== true
-  ) {
-    return runMatch();
+  if (!pprConfig) return runMatch();
+  if (request.method !== "GET") {
+    return runMatch({ outcome: "BYPASS", reason: "method" });
+  }
+  if (reqCtx._dynamic) {
+    return runMatch({ outcome: "BYPASS", reason: "dynamic" });
+  }
+  if (activeNonce !== undefined) {
+    return runMatch({ outcome: "BYPASS", reason: "nonce" });
+  }
+  if (!hasShellFamily(store)) {
+    return runMatch({ outcome: "BYPASS", reason: "store-unavailable" });
+  }
+  if (store.supportsPassiveShellReads !== true) {
+    return runMatch({
+      outcome: "BYPASS",
+      reason: "passive-read-unsupported",
+    });
   }
 
   const key = buildShellKey(url);
+  const navigationKey = buildNavigationShellKey(url);
   let cached: Awaited<ReturnType<typeof store.getShell>> = null;
   try {
     cached = await store.getShell(key, { claimRevalidation: false });
   } catch (error) {
     reportCacheError(error, "cache-read", "[NavigationPPR] getShell");
-    return runMatch();
+    return runMatch({ outcome: "BYPASS", reason: "read-error" });
   }
 
-  let snapshot = cached?.shouldRevalidate
-    ? undefined
-    : replayableShellSnapshot(cached?.entry, ctx.version);
+  let bypassReason: PprReplayBypassReason | undefined;
+  let snapshot: ShellSnapshotRecord[] | undefined;
+  let freshness: "fresh" | "stale" = "fresh";
+  if (cached) {
+    const decision = replayableShellSnapshot(cached.entry, ctx.version);
+    if ("snapshot" in decision) {
+      snapshot = decision.snapshot;
+      freshness = cached.shouldRevalidate ? "stale" : "fresh";
+    } else {
+      bypassReason = decision.reason;
+    }
+  }
+
+  if (
+    !snapshot &&
+    bypassReason !== "handler-live-holes" &&
+    bypassReason !== "transition-when"
+  ) {
+    let navigationCached: Awaited<ReturnType<typeof store.getShell>> = null;
+    try {
+      navigationCached = await store.getShell(navigationKey, {
+        claimRevalidation: false,
+      });
+    } catch (error) {
+      reportCacheError(error, "cache-read", "[NavigationPPR] getShell");
+      return runMatch({ outcome: "BYPASS", reason: "read-error" });
+    }
+    if (navigationCached) {
+      const decision = replayableShellSnapshot(
+        navigationCached.entry,
+        ctx.version,
+      );
+      if ("snapshot" in decision) {
+        snapshot = decision.snapshot;
+        freshness = navigationCached.shouldRevalidate ? "stale" : "fresh";
+      } else {
+        bypassReason = decision.reason;
+      }
+    }
+  }
 
   if (!snapshot) {
     // Production build manifests are local module data. In dev, resolving a
     // missing build shell would foreground-fetch /__rsc_shell and block an
     // otherwise ordinary navigation on capture, so replay remains runtime-only.
     const buildHit = await lookupBuildShell(url, ctx.version, store);
-    if (!buildHit?.stale) {
-      snapshot = replayableShellSnapshot(buildHit?.entry, ctx.version);
+    if (buildHit?.stale) {
+      bypassReason ??= "stale-build-entry";
+    } else if (buildHit) {
+      const buildDecision = replayableShellSnapshot(
+        buildHit.entry,
+        ctx.version,
+      );
+      if ("snapshot" in buildDecision) {
+        snapshot = buildDecision.snapshot;
+      } else {
+        bypassReason ??= buildDecision.reason;
+      }
     }
   }
 
-  if (!snapshot) return runMatch();
+  if (!snapshot) {
+    const match = await runMatch({
+      outcome: "BYPASS",
+      reason: bypassReason ?? "no-entry",
+    });
+    return { ...match, captureNeeded: shouldHealReplayMiss(bypassReason) };
+  }
 
   const previousImplicitCache = reqCtx._shellImplicitCache;
+  let segmentReplayHit = false;
   reqCtx._shellImplicitCache = {
     ttl: pprConfig.ttl,
     swr: pprConfig.swr,
-    store: new SeededShellStore(store, snapshot, { segmentsOnly: true }),
+    store: new SeededShellStore(store, snapshot, {
+      segmentsOnly: true,
+    }),
     keyPrefix: "doc",
+    onHit: () => {
+      segmentReplayHit = true;
+    },
   };
 
   try {
-    return await runMatch();
+    const result = await ctx.router.matchPartial(request, { env });
+    const status: PprReplayStatus = segmentReplayHit
+      ? { outcome: "HIT", freshness }
+      : { outcome: "BYPASS", reason: "snapshot-miss" };
+    recordReplayStatus(status);
+    return { result, status };
   } finally {
     reqCtx._shellImplicitCache = previousImplicitCache;
   }