@rangojs/router 0.27.0 → 0.28.0

package/src/rsc/shell-serve.ts

@@ -36,6 +36,10 @@ import {
   warnOnce,
 } from "./shell-capture-constants.js";
 import { routerKeyPrefix } from "../cache/cache-key-utils.js";
+import { reportCacheError } from "../cache/cache-error.js";
+import { appendMetric } from "../router/metrics.js";
+import type { MetricsStore } from "../server/context.js";
+import { WIRE } from "../wire-params.js";
 
 export {
   PPR_REPLAY_STATUS_HEADER,
@@ -128,19 +132,13 @@ export function resolvePprConfig(
 }
 
 /**
- * The forced-MISS query marker. A document HIT that cannot finish its tail
- * reloads the page with it (shellReloadScript); the serve gate renders a
- * request carrying it on axis 1, with no shell read and no capture, so the
- * reload can never be a HIT that degrades again. The handler drops it from
- * the request on entry (withoutShellMissMarker) and keeps only the flag
- * (RequestContext._shellForcedMiss), so nothing else sees it.
- */
-export const SHELL_MISS_PARAM: string = "_rsc_shell";
-
-/**
- * The request without the forced-MISS marker, or undefined when it carries
- * none. The handler calls it before anything reads the request: left in, the
- * marker reached `ctx.request.url`, `originalUrl`, middleware, and the SSR
+ * The request without the forced-MISS marker (`WIRE.shellMiss`), or
+ * undefined when it carries none. A document HIT that cannot finish its tail
+ * reloads the page with the marker (shellReloadScript); the serve gate
+ * renders a request carrying it on axis 1, with no shell read and no
+ * capture, so the reload can never be a HIT that degrades again. The handler
+ * calls this on entry, before anything reads the request, and keeps only the
+ * flag (RequestContext._shellForcedMiss): left in, the marker reached `ctx.request.url`, `originalUrl`, middleware, and the SSR
  * search seed (so `useSearchParams` rendered it), and a `"use cache"` key
  * built from the request URL was never read again. GET and HEAD only: the
  * reload is a navigation, and a request with a body cannot be re-created
@@ -148,11 +146,11 @@ export const SHELL_MISS_PARAM: string = "_rsc_shell";
  * other request.
  */
 export function withoutShellMissMarker(request: Request): Request | undefined {
-  if (!request.url.includes(SHELL_MISS_PARAM)) return undefined;
+  if (!request.url.includes(WIRE.shellMiss)) return undefined;
   if (request.method !== "GET" && request.method !== "HEAD") return undefined;
   const url = new URL(request.url);
-  if (!url.searchParams.has(SHELL_MISS_PARAM)) return undefined;
-  url.searchParams.delete(SHELL_MISS_PARAM);
+  if (!url.searchParams.has(WIRE.shellMiss)) return undefined;
+  url.searchParams.delete(WIRE.shellMiss);
   return new Request(url, request);
 }
 
@@ -168,8 +166,8 @@ export function withoutShellMissMarker(request: Request): Request | undefined {
 export function shellReloadScript(): string {
   return inlineShellScript(
     "(function(){var u=new URL(location.href);" +
-      `if(u.searchParams.has(${JSON.stringify(SHELL_MISS_PARAM)}))return;` +
-      `u.searchParams.set(${JSON.stringify(SHELL_MISS_PARAM)},"miss");` +
+      `if(u.searchParams.has(${JSON.stringify(WIRE.shellMiss)}))return;` +
+      `u.searchParams.set(${JSON.stringify(WIRE.shellMiss)},"miss");` +
       "try{window.stop()}catch(e){}location.replace(u.href)})()",
   );
 }
@@ -305,6 +303,111 @@ export function openShellDocument(
   };
 }
 
+/**
+ * A document serve's store read: a getShell entry, or a prelude-first read
+ * (readShellDocument) whose entry is the head and whose snapshot arrives on
+ * its own promise.
+ */
+export type ShellRead =
+  | { entry: ShellCacheEntry; shouldRevalidate?: boolean; read?: undefined }
+  | {
+      entry: ShellEntryHead;
+      shouldRevalidate?: boolean;
+      read: ShellDocumentRead;
+    };
+
+/**
+ * The document serve's shell read from `source`, the app cache store, that
+ * degrades to null on failure (axis 1 MISS, never a 500) and records the raw
+ * `ppr:shell-read` outcome (pre-validity-gates, so a version-mismatch
+ * lifecycle miss stays distinguishable from a store miss). A store with a
+ * prelude-first read (readShellDocument) resolves before the snapshot is
+ * read, so the HIT commits without waiting for it. A build shell is read by
+ * shell-build-manifest.ts lookupBuildShell, which imports this module.
+ */
+export async function readShell(
+  source: SegmentCacheStore & {
+    getShell: NonNullable<SegmentCacheStore["getShell"]>;
+  },
+  key: string,
+  opts: { tagHints?: readonly string[]; metrics?: MetricsStore },
+): Promise<ShellRead | null> {
+  const { tagHints, metrics } = opts;
+  let cached: ShellRead | null = null;
+  const shellReadStart = metrics ? performance.now() : 0;
+  try {
+    if (source.readShellDocument) {
+      const read = await source.readShellDocument(
+        key,
+        tagHints ? { tagHints } : undefined,
+      );
+      cached = read
+        ? { entry: read.entry, shouldRevalidate: read.shouldRevalidate, read }
+        : null;
+    } else {
+      cached = await source.getShell(key);
+    }
+  } catch (error) {
+    reportCacheError(error, "cache-read", "[ShellServe] getShell");
+  }
+  if (metrics) {
+    const stats = cached?.read?.stats;
+    appendMetric(
+      metrics,
+      "ppr:shell-read",
+      shellReadStart,
+      performance.now() - shellReadStart,
+      undefined,
+      cached ? (stats ? `hit ${stats.tier}` : "hit") : "miss",
+    );
+    if (stats) recordShellReadStats(metrics, shellReadStart, stats);
+  }
+  return cached;
+}
+
+/**
+ * A prelude-first read's sub-steps as `debugPerformance` rows under
+ * `ppr:shell-read`. The marker row starts with the prelude row because the
+ * two run in parallel; its desc says how long the read still waited on the
+ * marker once the prelude was in. On a deployed worker the clock only
+ * advances on I/O, so the byte counts are the cost signal for the CPU parts.
+ */
+function recordShellReadStats(
+  store: MetricsStore,
+  readStart: number,
+  stats: ShellReadStats,
+): void {
+  let at = readStart;
+  const row = (label: string, ms: number | undefined, desc: string): void => {
+    if (ms !== undefined) appendMetric(store, label, at, ms, 1, desc);
+  };
+  if (stats.memo) {
+    row(
+      "ppr:shell-memo",
+      0,
+      `${stats.memo.hit ? "hit" : "miss"} size=${stats.memo.bytes}b`,
+    );
+  }
+  // A KV hit after an L1 miss: the L1 attempt first, then the KV read.
+  row("ppr:shell-l1-miss", stats.l1MissMs, stats.l1MissReason ?? "miss");
+  at += stats.l1MissMs ?? 0;
+  row("ppr:shell-match", stats.matchMs, stats.tier);
+  at += stats.matchMs ?? 0;
+  row("ppr:shell-head", stats.headMs, `bytes=${stats.headBytes ?? 0}`);
+  at += stats.headMs ?? 0;
+  row("ppr:shell-prelude", stats.preludeMs, `bytes=${stats.preludeBytes ?? 0}`);
+  let marker = `tags=${stats.tags ?? 0} ${stats.markerSerial ? "serial" : "parallel"} commit-wait=${(stats.markerWaitMs ?? 0).toFixed(2)}ms`;
+  if (stats.markerMemo) marker += ` memo=${stats.markerMemo}`;
+  if (stats.markerHinted) {
+    marker += ` hint=${stats.markerHintHits ?? 0}/${stats.markerHinted.length}`;
+    if (stats.markerLeadMs !== undefined) {
+      marker += ` lead=${stats.markerLeadMs.toFixed(2)}ms`;
+    }
+  }
+  if (stats.freshReads) marker += " fresh-reads";
+  row("ppr:shell-marker", stats.markerMs, marker);
+}
+
 /**
  * Prelude enqueue granularity. A streaming compressor in front of the worker
  * emits its first byte only after compressing the whole write it was handed:

package/src/rsc/ssr-setup.ts

@@ -24,6 +24,7 @@ import {
 import { _getRequestContext } from "../server/request-context.js";
 import { renderedLocation } from "./full-payload.js";
 import { markServerErrorPrinted } from "../server/print-server-error.js";
+import { WIRE } from "../wire-params.js";
 
 export type SSRSetup = readonly [SSRModule, SSRStreamMode];
 
@@ -233,10 +234,10 @@ function acceptsFlightExplicitly(request: Request, url: URL): boolean {
  */
 export function mayNeedSSR(request: Request, url: URL): boolean {
   if (
-    url.searchParams.has("_rsc_partial") ||
-    url.searchParams.has("_rsc_action") ||
+    url.searchParams.has(WIRE.partial) ||
+    url.searchParams.has(WIRE.action) ||
     requestHeaders(request).has("rsc-action") ||
-    url.searchParams.has("_rsc_loader") ||
+    url.searchParams.has(WIRE.loader) ||
     url.searchParams.has("__rsc")
   ) {
     return false;
@@ -264,7 +265,7 @@ export function isRscRequest(
 ): boolean {
   return (
     isPartial ||
-    url.searchParams.has("_rsc_partial") ||
+    url.searchParams.has(WIRE.partial) ||
     url.searchParams.has("__rsc") ||
     acceptsFlightExplicitly(request, url)
   );

package/src/segment-system.tsx

@@ -295,7 +295,7 @@ function wrapDefaultOutletContent(
 
 /**
  * Per-loader stream map for read-site suspension. { ssr: false } loaders were
- * awaited before flush (fresh.ts), so deliver the SETTLED result, not the
+ * awaited before flush (resolveOwnerLoaders), so deliver the SETTLED result, not the
  * settled promise: the read site decodes synchronously instead of use()ing a
  * Flight chunk whose fulfilled-at-read-time status is a scheduling race the
  * SSR-completeness contract must not depend on. Unflagged siblings keep the
@@ -1063,8 +1063,8 @@ function* segmentTreeWalk(
     }
   }
 
-  // Segments arrive in root-to-leaf order from the server (resolveSegment
-  // and resolveSegmentWithRevalidation push segments in this order).
+  // Segments arrive in root-to-leaf order from the server
+  // (resolveSegment pushes segments in this order).
   // All consumers (reconcileSegments, cache) preserve this order.
   // No sorting needed — iterate bottom-to-top to process leaf segments first.
   // This processes route/leaf layouts first, then parent layouts

package/src/server/context.ts

@@ -15,6 +15,7 @@ import { invariant, DslContextError } from "../errors";
 import type { DefaultRouteName } from "../types/global-namespace.js";
 import type { ContextVar } from "../context-var.js";
 import { PPR_LANE_HINT } from "../rsc/shell-capture-constants.js";
+import type { ShellCaptureState } from "../rsc/shell-capture.js";
 import {
   noteWarmIdentityRead,
   type WarmContext,
@@ -155,7 +156,7 @@ export type LoaderEntry = {
    * thrown notFound()/redirect() deterministically precede first flush.
    * Resolved at DSL-evaluation time from ctx.isSSR — entries are cached
    * per-isSSR (router/manifest.ts cache key), so the flag is already
-   * request-mode-correct when resolveLoaders (fresh.ts) reads it and never
+   * request-mode-correct when resolveOwnerLoaders reads it and never
    * appears on navigation-lane entries. Set by documentModeLoader, which
    * getDocumentModeEntry also applies to a lazy include's captured ancestors.
    */
@@ -1133,7 +1134,7 @@ export interface IdentityReadWording {
  *    only observed; it is never rendered. A cached body, loader body or
  *    funnel they start is guarded again.
  * 1. A PPR shell capture (`ctx` is the capture's derived context,
- *    `_shellCaptureRun`) trips first: the capture context is flagged (so a
+ *    `_shellCaptureState`) trips first: the capture context is flagged (so a
  *    caught throw still refuses the capture) and the read throws. The shell is
  *    shared per host+URL, and every HIT replays what the capture read. There
  *    is no loader-body exemption here: a bake-lane loader and a loader a
@@ -1219,7 +1220,7 @@ export function requestReadCaptureFix(
 
 /**
  * True when `ctx` is the active capture render: the derived request context
- * shell-capture.ts builds (`_shellCaptureRun`), which only the capture sets,
+ * shell-capture.ts builds (`_shellCaptureState`), which only the capture has,
  * so the foreground render reads identity normally to serve the real user.
  * On true the capture context is flagged with the read (`surface`, e.g.
  * "cookies()", "ctx.theme"), the fix the refusal warning gives, and the loader
@@ -1230,21 +1231,15 @@ function tripShellCaptureGuard(
   surface: string,
   fix: string,
 ): boolean {
-  if (
-    ctx === null ||
-    typeof ctx !== "object" ||
-    (ctx as { _shellCaptureRun?: unknown })._shellCaptureRun !== true
-  ) {
-    return false;
-  }
+  const captureState =
+    ctx !== null && typeof ctx === "object"
+      ? (ctx as { _shellCaptureState?: ShellCaptureState })._shellCaptureState
+      : undefined;
+  if (captureState?.run !== true) return false;
   // Record WHICH loader body (if any) made the read, so the refusal warning
   // can name the real source instead of hardcoding a lane (issue #672).
-  const flagged = ctx as {
-    _shellCaptureGuardTripped?: { surface: string; fix: string };
-    _shellCaptureGuardTrippedLoaderId?: string;
-  };
-  flagged._shellCaptureGuardTripped = { surface, fix };
-  flagged._shellCaptureGuardTrippedLoaderId = getCurrentLoaderBodyId();
+  captureState.guardTripped = { surface, fix };
+  captureState.guardTrippedLoaderId = getCurrentLoaderBodyId();
   return true;
 }
 
@@ -1530,12 +1525,13 @@ export function latchPprHeaderScopeForEntries(
  * ONLY the ppr (shell) axis is dropped — dynamic() does NOT opt off the CACHE
  * axis. Two cases:
  * - Pure ppr funnel (no cache() boundary): clear the latch → writes re-permit.
- * - ppr route nested under a cache() boundary: fresh.ts latches "ppr" at the
- *   funnel top (first-wins), which MASKS the positional cache() latch, but the
- *   handler still runs inside the cache scope (`insideCacheScope`). A cache()
- *   HIT skips that handler, so the write is still non-deterministic — UNMASK to
- *   "cache" instead of clearing, so the guard keeps throwing (accurate cache()
- *   wording). This is why the check keys off `insideCacheScope`, not just kind.
+ * - ppr route nested under a cache() boundary: resolveAllSegments
+ *   latches "ppr" at the funnel top (first-wins), which MASKS the positional
+ *   cache() latch, but the handler still runs inside the cache scope
+ *   (`insideCacheScope`). A cache() HIT skips that handler, so the write is
+ *   still non-deterministic — UNMASK to "cache" instead of clearing, so the
+ *   guard keeps throwing (accurate cache() wording). This is why the check keys
+ *   off `insideCacheScope`, not just kind.
  *
  * A subsequent cache() entered AFTER dynamic() on a pure-ppr funnel re-latches
  * "cache" via latchCachedHeaderScope's `!store.cachedHeaderScope` guard (the
@@ -1568,9 +1564,10 @@ export function assertCachedHeaderWriteAllowed(
   const scope = RangoContext.getStore()?.cachedHeaderScope;
   if (!scope) return;
   // Exempt DSL loaders (loaderScopeALS) ONLY. A registered loader re-runs on
-  // every cache HIT (fresh.ts runInsideLoaderScope -> cache-lookup.ts
-  // resolveLoadersOnly), so its header/cookie writes merge into every response
-  // with no MISS/HIT divergence. A handler-invoked loader body has
+  // every cache HIT (resolveOwnerLoaders runInsideLoaderScope, reached from
+  // cache-lookup.ts resolveLoadersOnly), so its header/cookie
+  // writes merge into every response with no MISS/HIT divergence. A
+  // handler-invoked loader body has
   // loaderBodyScopeALS active but loaderScopeALS unset (loader-resolution.ts
   // derives isDslLoader from isInsideLoaderScope()); on a HIT the handler is
   // skipped so that loader never re-runs and its write would land only on the

package/src/server/handle-store.ts

@@ -89,10 +89,14 @@ interface SlotTag {
    * loader a copy stands for. Unset for a handler's push.
    */
   by?: string;
+  /** A stored value a HIT restored (holdRecordedValues). */
+  record?: true;
 }
 
 // Shared by every plain DSL-loader push; tags are never mutated in place.
 const LOADER_SLOT: SlotTag = Object.freeze({ loader: true });
+// Shared by every held record value that had no tag (holdRecordedValues).
+const RECORD_SLOT: SlotTag = Object.freeze({ record: true });
 
 /**
  * What a restored record is to one loader's handle pushes on this request
@@ -311,6 +315,24 @@ export interface HandleStore {
    */
   replacePlaceholders(loaderIds: readonly string[], deliver: () => void): void;
 
+  /**
+   * A cache() or Prerender() HIT restored its stored values into
+   * `segmentIds` (cache-lookup.ts serveStoredSegments). The MISS ran each
+   * segment's handler after it started the segment's loaders, so a push into
+   * a restored array goes in front of the stored values until
+   * releaseRecordedValues: a loader's push lands where the same loader timing
+   * puts it on the MISS.
+   */
+  holdRecordedValues(segmentIds: readonly string[]): void;
+
+  /**
+   * The HIT's loader walk reached the place where the MISS ran
+   * `segmentId`'s handler (revalidation.ts resolveLoadersOnly,
+   * intercept-resolution.ts resolveInterceptLoadersOnly): later pushes
+   * follow the record's values.
+   */
+  releaseRecordedValues(segmentId: string): void;
+
   /**
    * Get all collected handle data after all handlers have settled.
    * Waits for `settled` (handler lane), then returns the data at that point.
@@ -482,6 +504,8 @@ export function createHandleStore(): HandleStore {
   // it restored placeholders for (pushPlaceholder).
   const restoredLoaders = new Set<string>();
   const placeholderLoaders = new Set<string>();
+  // Segments whose restored record values a push still goes in front of.
+  const held = new Set<string>();
   let authority: ((loaderId: string) => RecordAuthority) | undefined;
   const isRestored = (loaderId: string): boolean =>
     restoredLoaders.has(loaderId) || authority?.(loaderId) === "pin";
@@ -620,6 +644,16 @@ export function createHandleStore(): HandleStore {
     return at;
   }
 
+  // The first restored record value in `values` (holdRecordedValues).
+  function firstRecordSlot(values: unknown[]): number | undefined {
+    const tags = slotTags.get(values);
+    if (!tags) return undefined;
+    for (let i = 0; i < values.length; i++) {
+      if (tags[i]?.record) return i;
+    }
+    return undefined;
+  }
+
   // Where a live push by a loader with copies lands in `values`: its first
   // push removes all of its copies and takes the first one's position in this
   // array; later pushes follow the last push of its run. undefined: no place
@@ -954,6 +988,9 @@ export function createHandleStore(): HandleStore {
         at = restoredInsertIndex(values, restoredBy);
         if (replayOf === undefined) liveOf = restoredBy;
       }
+      if (at === undefined && held.has(segmentId)) {
+        at = firstRecordSlot(values);
+      }
       const by =
         getHandlePushOwner() ??
         replayOf ??
@@ -1058,6 +1095,24 @@ export function createHandleStore(): HandleStore {
       signalEmission();
     },
 
+    holdRecordedValues(segmentIds: readonly string[]): void {
+      for (const segmentId of segmentIds) {
+        held.add(segmentId);
+        for (const handleName in data) {
+          const values = data[handleName][segmentId];
+          if (!values?.length) continue;
+          const tags = tagsFor(values);
+          for (let i = 0; i < values.length; i++) {
+            tags[i] = tags[i] ? { ...tags[i], record: true } : RECORD_SLOT;
+          }
+        }
+      }
+    },
+
+    releaseRecordedValues(segmentId: string): void {
+      held.delete(segmentId);
+    },
+
     replacePlaceholders(
       loaderIds: readonly string[],
       deliver: () => void,