@rangojs/router 0.0.0-experimental.147 → 0.0.0-experimental.148

package/src/rsc/ssr-setup.ts

@@ -11,6 +11,11 @@ import type { SSRModule } from "./types.js";
 import type { SSRStreamMode } from "../router/router-options.js";
 import type { MetricsStore } from "../server/context.js";
 import { appendMetric } from "../router/metrics.js";
+import {
+  parseAcceptTypes,
+  prefersFlightRepresentation,
+  RSC_WIRE_MIME,
+} from "../router/content-negotiation.js";
 import { _getRequestContext } from "../server/request-context.js";
 
 export type SSRSetup = readonly [SSRModule, SSRStreamMode];
@@ -90,12 +95,42 @@ export function getSSRSetup<TEnv>(
   );
 }
 
+/**
+ * Accept-based flight opt-in: the client explicitly listed the RSC wire
+ * format (text/x-component) in Accept, ranked above the HTML document, and
+ * did not override with __html.
+ *
+ * The flight stream is an internal transport representation — it is served
+ * ONLY on explicit opt-in (this Accept value, or the _rsc_ / __rsc transport
+ * params). Everything else (missing Accept, wildcards, application/json,
+ * browser Accept strings) gets the HTML document, per RFC 9110: a missing
+ * Accept is equivalent to a full wildcard, and a wildcard gets the server's
+ * canonical representation. The old rule ("no text/html substring → flight")
+ * handed the wire format to every generic client — curl, health checks,
+ * link unfurlers.
+ *
+ * The includes() guard is a parse-skipping fast path: the bulk of traffic
+ * (browsers, curl, monitors) never mentions the wire format and pays no
+ * parseAcceptTypes allocation. Ranking lives in prefersFlightRepresentation
+ * (router/content-negotiation.ts), co-located with the candidate MIME set.
+ */
+function acceptsFlightExplicitly(request: Request, url: URL): boolean {
+  if (url.searchParams.has("__html")) return false;
+  const accept = request.headers.get("accept");
+  if (accept === null || !accept.includes(RSC_WIRE_MIME)) return false;
+  return prefersFlightRepresentation(parseAcceptTypes(accept));
+}
+
 /**
  * Classify whether a request may require SSR (HTML rendering).
  *
- * Returns false for requests that are definitively RSC-only, loader fetches,
- * prerender collection, or Accept-based RSC (no text/html). This mirrors
- * the isRscRequest decision in rsc-rendering.ts.
+ * Returns false for requests that are definitively RSC-only: transport
+ * params (partial/action/loader/__rsc), prerender collection, or an explicit
+ * Accept: text/x-component. Must never return false for a request whose
+ * render-time decision (isRscRequest) will be HTML — the two share
+ * acceptsFlightExplicitly so the Accept rule cannot drift. document-cache.ts
+ * keys its HTML/RSC response slots off this function, so any divergence from
+ * the render decision poisons a cache slot with the wrong representation.
  *
  * Note: response/mime routes are excluded by the caller — this function
  * runs after classifyRequest() determines the request mode.
@@ -112,24 +147,21 @@ export function mayNeedSSR(request: Request, url: URL): boolean {
     return false;
   }
 
-  // Mirror the Accept-based RSC decision from rsc-rendering.ts:
-  // if Accept is present and does not include text/html (and no __html override),
-  // the response will be RSC, not HTML.
-  const accept = request.headers.get("accept");
-  if (
-    accept &&
-    !accept.includes("text/html") &&
-    !url.searchParams.has("__html")
-  ) {
-    return false;
-  }
-
-  return true;
+  return !acceptsFlightExplicitly(request, url);
 }
 
-// Final render-time decision: is the response an RSC stream (vs HTML)? Distinct
-// from mayNeedSSR, which is a conservative pre-classifier (it treats a missing
-// Accept header as needing SSR; this treats it as RSC).
+// Final render-time decision: is the response an RSC stream (vs HTML)?
+// Flight requires explicit opt-in: the partial transport param, __rsc, or
+// Accept: text/x-component. mayNeedSSR is the coarse pre-filter over the
+// transport params; both delegate the Accept call to acceptsFlightExplicitly.
+//
+// _rsc_partial is read from the URL in addition to the plan-derived isPartial
+// flag: the 404 fallback plan hardcodes mode "full-render" even for partial
+// navigations (handler.ts RouteNotFoundError catch), so a partial 404 reaches
+// this decision with isPartial=false. The old Accept rule masked that by
+// classifying */* as flight; without the URL check a client-side navigation
+// to a missing route received an HTML 404 it cannot apply, and the
+// navigation never committed (multi-router soft-404, popstate not-found).
 export function isRscRequest(
   request: Request,
   url: URL,
@@ -137,8 +169,8 @@ export function isRscRequest(
 ): boolean {
   return (
     isPartial ||
-    (!request.headers.get("accept")?.includes("text/html") &&
-      !url.searchParams.has("__html")) ||
-    url.searchParams.has("__rsc")
+    url.searchParams.has("_rsc_partial") ||
+    url.searchParams.has("__rsc") ||
+    acceptsFlightExplicitly(request, url)
   );
 }

package/src/server/context.ts

@@ -27,6 +27,7 @@ export interface PerformanceMetric {
   duration: number; // milliseconds
   startTime: number; // relative to request start
   depth?: number; // nesting level for hierarchical display (0 = top-level)
+  desc?: string; // free-form outcome detail, emitted as Server-Timing desc="..."
 }
 
 /**

package/src/urls/pattern-types.ts

@@ -62,6 +62,33 @@ export interface PartialPrerenderProps {
    * capture render auto-collects (the shell's own non-loader request tags).
    */
   tags?: string[];
+  /**
+   * Upper bound (serialized UTF-8 bytes) on the capture data snapshot riding
+   * inside the shell entry. The snapshot duplicates every cache-store value
+   * the capture pinned, so a page over a large cache() segment can push the
+   * entry toward store value limits (Cloudflare KV caps a value at 25 MiB).
+   * Over the cap the snapshot is skipped: the shell is still stored and
+   * served, but pinned reads fall back to the live store, so drifted cached
+   * content can hydration-mismatch and be repaired client-side (the
+   * pre-snapshot behavior). Reported once per key. Defaults to 8 MiB.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * Capture settle budget in MILLISECONDS (default 5000). Bounds the whole
+   * background capture: the wait for deferred shell material — top-level
+   * pushed handle promises (`ctx.use(Meta)(promise.then(...))` and friends)
+   * are AWAITED and their settled values baked into the stored shell — AND
+   * the fizz prerender deadline. Declare it when a route's shell material
+   * takes longer than 5s to settle. A budget that expires with pushes still
+   * pending REFUSES the capture (the route stays MISS with the once-per-key
+   * warning) — a shell with missing head material is never stored. Capture
+   * is background work (waitUntil), so a longer budget costs latency-to-HIT
+   * only, never a served response; the platform waitUntil lifetime (workerd:
+   * ~30s past response completion) is the physical ceiling. Build-time
+   * captures (Prerender+ppr, producer B) honor the same budget with no
+   * platform ceiling. Non-finite or sub-1ms values fall back to the default.
+   */
+  captureTimeout?: number;
 }
 
 export interface PathOptions<

package/src/vite/discovery/shell-prerender-phase.ts

@@ -243,6 +243,8 @@ export async function runShellPrerenderPhase(
             ttl: policy.ttl,
             swr: policy.swr,
             tags: policy.tags,
+            maxSnapshotBytes: policy.maxSnapshotBytes,
+            captureTimeout: policy.captureTimeout,
             buildEnv: s.resolvedBuildEnv,
             buildVersion,
             captureShellHTML,

package/src/vite/discovery/state.ts

@@ -73,7 +73,9 @@ export interface ShellPrerenderCandidate {
   urlPath: string;
   routeName: string;
   paramHash: string;
-  ppr: true | { ttl?: number; swr?: number; tags?: string[] };
+  ppr:
+    | true
+    | { ttl?: number; swr?: number; tags?: string[]; captureTimeout?: number };
 }
 
 export interface DiscoveryState {

package/src/vite/router-discovery.ts

@@ -19,6 +19,10 @@ import {
   createScanFilter,
 } from "../build/generate-route-types.js";
 import { firstCodeMatchIndex } from "../build/route-types/source-scan.js";
+import {
+  DEV_SHELL_PROBE_TIMEOUT_MS,
+  normalizeCaptureTimeout,
+} from "../rsc/shell-serve.js";
 import {
   injectClientDebugFlag,
   internalDebugNoCacheMiddleware,
@@ -1144,6 +1148,18 @@ export function createRouterDiscoveryPlugin(
         const swr = swrRaw === null ? undefined : Number(swrRaw);
         const tagsRaw = url.searchParams.get("tags");
         const tags = tagsRaw ? tagsRaw.split(",") : undefined;
+        const maxSnapshotBytesRaw = url.searchParams.get("maxSnapshotBytes");
+        const maxSnapshotBytes =
+          maxSnapshotBytesRaw === null
+            ? undefined
+            : Number(maxSnapshotBytesRaw);
+        // Boundary revalidation via the SHARED normalizer (shell-serve.ts):
+        // the param crossed an HTTP query string, and a garbage value must
+        // fall back to the capture default, never reach setTimeout as NaN
+        // (which Node clamps to ~1ms — an instant abort).
+        const captureTimeout = normalizeCaptureTimeout(
+          Number(url.searchParams.get("captureTimeout")),
+        );
 
         // Resolve the capture realms: main-server envs (Node preset) or the
         // shared temp Node server (Cloudflare preset — no main RSC runner).
@@ -1205,7 +1221,7 @@ export function createRouterDiscoveryPlugin(
         // (this fetch blocks a foreground document request), and the memoized
         // body needs neither the pre-flight round-trip nor a capture. Keyed
         // per router instance (= HMR generation) like the prerender memo.
-        const cacheKey = `shell|${pathname}|r=${routeName}|t=${ttl}|s=${swr ?? ""}|g=${(tags ?? []).join("+")}|v=${version}`;
+        const cacheKey = `shell|${pathname}|r=${routeName}|t=${ttl}|s=${swr ?? ""}|g=${(tags ?? []).join("+")}|c=${captureTimeout ?? ""}|v=${version}`;
         for (const [, routerInstance] of registry) {
           if (typeof routerInstance.match !== "function") continue;
           const cached = devPrerenderCache.get(routerInstance, cacheKey);
@@ -1224,7 +1240,7 @@ export function createRouterDiscoveryPlugin(
           try {
             const probe = await fetch(
               `${s.devServerOrigin}/__rsc_prerender?pathname=${encodeURIComponent(pathname)}&routeName=${encodeURIComponent(routeName)}`,
-              { signal: AbortSignal.timeout(10_000) },
+              { signal: AbortSignal.timeout(DEV_SHELL_PROBE_TIMEOUT_MS) },
             );
             if (!probe.ok) {
               res.statusCode = 404;
@@ -1258,6 +1274,8 @@ export function createRouterDiscoveryPlugin(
               ttl,
               swr,
               tags,
+              maxSnapshotBytes,
+              captureTimeout,
               buildEnv: s.resolvedBuildEnv,
               buildVersion: version,
               captureShellHTML: ssrModule.captureShellHTML,