@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

package/src/rsc/shell-serve.ts

@@ -17,7 +17,7 @@
  */
 
 import React from "react";
-import type { EntryData } from "../server/context.js";
+import { isPprEntry, type EntryData } from "../server/context.js";
 import { sortedSearchString } from "../cache/cache-key-utils.js";
 import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
 
@@ -30,11 +30,47 @@ export const SHELL_STATUS_HEADER = "x-rango-shell";
  */
 export const DEFAULT_PPR_TTL_SECONDS = 300;
 
+/**
+ * Timeout for the dev /__rsc_shell endpoint's sequential /__rsc_prerender
+ * pre-flight probe (vite/router-discovery.ts). Hoisted here so the client-side
+ * fetch bound (shell-build-manifest.ts devShellFetchTimeoutMs) enumerates the
+ * SAME term of the endpoint's worst-case envelope — the two cannot drift.
+ */
+export const DEV_SHELL_PROBE_TIMEOUT_MS: number = 10_000;
+
 /** The route's ppr option normalized to a concrete policy. */
 export interface ResolvedPprConfig {
   ttl: number;
   swr?: number;
   tags?: string[];
+  /**
+   * Snapshot size cap, passed through undefaulted (like swr/tags): the single
+   * defaulting site is captureAndStoreShell (DEFAULT_PPR_MAX_SNAPSHOT_BYTES in
+   * shell-capture.ts), so direct descriptor callers and resolved configs
+   * cannot drift.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * Capture settle budget in ms (`ppr.captureTimeout`). Undefined = the
+   * capture default (SHELL_CAPTURE_MAX_WAIT_MS, 15_000) — the default's single
+   * owner stays shell-capture.ts so build/runtime producers cannot drift.
+   */
+  captureTimeout?: number;
+}
+
+/**
+ * Validate the raw `ppr.captureTimeout` option: a finite number >= 1ms passes
+ * through; anything else (including 0/negative/NaN/Infinity/non-number)
+ * resolves to undefined, which means "use the capture default" downstream.
+ * Mirrors the prefetch-limit option policy: invalid values silently fall back
+ * to the default rather than throwing at request time. Also the boundary
+ * re-normalizer for the dev /__rsc_shell endpoint (vite/router-discovery.ts),
+ * whose param crossed an HTTP query string.
+ */
+export function normalizeCaptureTimeout(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 1
+    ? value
+    : undefined;
 }
 
 /**
@@ -42,20 +78,29 @@ export interface ResolvedPprConfig {
  * route does not declare `ppr` (or declares `ppr: false`) — the caller then does
  * NOTHING: no store read, no capture, no logs. Pure axis 1, zero cost.
  *
+ * The route's NAME is irrelevant here (and everywhere on the shell lane):
+ * nameless `path()` routes register their EntryData under a synthesized
+ * `$path_*` manifest key with the `ppr` option intact (urls/path-helper.ts),
+ * so a nameless entry resolves exactly like a named one — pinned by the
+ * nameless-ppr e2e in both apps (issue #714).
+ *
  * PPR is a DOCUMENT-level property of the page route; there is no subtree
  * inheritance (declaring it on a layout is not supported — a follow-up).
  */
 export function resolvePprConfig(
   entry: EntryData | undefined | null,
 ): ResolvedPprConfig | null {
-  if (!entry || entry.type !== "route") return null;
+  // isPprEntry (server/context.ts) is the ONE opt-in predicate — shared with
+  // the header-write latch so serve and guard can never drift.
+  if (!entry || !isPprEntry(entry)) return null;
   const ppr = entry.ppr;
-  if (ppr === undefined || ppr === false) return null;
   if (ppr === true) return { ttl: DEFAULT_PPR_TTL_SECONDS };
   return {
     ttl: ppr.ttl ?? DEFAULT_PPR_TTL_SECONDS,
     swr: ppr.swr,
     tags: ppr.tags,
+    maxSnapshotBytes: ppr.maxSnapshotBytes,
+    captureTimeout: normalizeCaptureTimeout(ppr.captureTimeout),
   };
 }
 
@@ -133,6 +178,91 @@ export function hasShellFamily(
   return !!store?.getShell && !!store?.putShell;
 }
 
+/**
+ * Per-stage timing of one shell-HIT tail, all offsets in ms from the response
+ * commit (prelude flush). The HIT commits its 200 + headers BEFORE the live
+ * tail runs, so Server-Timing on the HIT response structurally cannot carry
+ * these numbers — they ride the dev mirror below instead (same doctrine as
+ * the ppr:capture mirror in rsc-rendering.ts, issue #651).
+ */
+export interface ShellTailTiming {
+  key: string;
+  outcome: "complete" | "redirect" | "error";
+  /** Loader-family seed decode (only when the entry carried a snapshot). */
+  seedMs?: number;
+  /** Tail router.match() settled. */
+  matchMs?: number;
+  /** Tail stream (resume output) handed to the response stream. */
+  handoverMs?: number;
+  /** First resumed-HTML byte enqueued on the wire. */
+  firstHtmlMs?: number;
+  /** Tail fully drained (last hole settled and flushed). */
+  completeMs?: number;
+  /** Prelude size flushed at commit (decoded bytes). */
+  preludeBytes?: number;
+  /** Total tail bytes streamed behind the prelude. */
+  tailBytes?: number;
+}
+
+/**
+ * Compact single-line form for the console log and the dev Server-Timing
+ * mirror's `desc`. Plain alphanumerics/`=`/`-` only — no quoted-string
+ * escaping needed.
+ */
+export function describeShellTailTiming(timing: ShellTailTiming): string {
+  const parts: string[] = [timing.outcome];
+  if (timing.seedMs !== undefined) parts.push(`seed=${timing.seedMs}ms`);
+  if (timing.matchMs !== undefined) parts.push(`match=${timing.matchMs}ms`);
+  if (timing.handoverMs !== undefined) {
+    parts.push(`handover=${timing.handoverMs}ms`);
+  }
+  if (timing.firstHtmlMs !== undefined) {
+    parts.push(`first-html=${timing.firstHtmlMs}ms`);
+  }
+  if (timing.completeMs !== undefined) {
+    parts.push(`complete=${timing.completeMs}ms`);
+  }
+  if (timing.preludeBytes !== undefined) {
+    parts.push(`prelude=${timing.preludeBytes}b`);
+  }
+  if (timing.tailBytes !== undefined) parts.push(`tail=${timing.tailBytes}b`);
+  return parts.join(" ");
+}
+
+/**
+ * Dev-only last-tail-per-key buffer backing the `ppr:tail` Server-Timing
+ * mirror: a HIT's tail finishes after its own headers are long gone, so its
+ * per-stage numbers ride the NEXT ppr GET for the key when the metrics
+ * surface is active (debugPerformance). Same shape and FIFO cap as the
+ * capture mirror (shell-capture.ts lastCaptureEventsForTiming); dev-only so
+ * production isolates never grow the map.
+ */
+const lastTailTimingsForServerTiming = new Map<string, ShellTailTiming>();
+const MAX_TAIL_TIMING_KEYS = 100;
+
+/** Buffer one terminal tail timing for the dev Server-Timing mirror. */
+export function publishShellTailTiming(timing: ShellTailTiming): void {
+  if (process.env.NODE_ENV === "production") return;
+  lastTailTimingsForServerTiming.delete(timing.key);
+  if (lastTailTimingsForServerTiming.size >= MAX_TAIL_TIMING_KEYS) {
+    const oldest = lastTailTimingsForServerTiming.keys().next().value;
+    if (oldest !== undefined) lastTailTimingsForServerTiming.delete(oldest);
+  }
+  lastTailTimingsForServerTiming.set(timing.key, timing);
+}
+
+/**
+ * Consume (read-and-clear) the buffered tail timing for `key`, so one tail
+ * reports into exactly one later response's Server-Timing.
+ */
+export function takeShellTailTimingForServerTiming(
+  key: string,
+): ShellTailTiming | undefined {
+  const timing = lastTailTimingsForServerTiming.get(key);
+  if (timing) lastTailTimingsForServerTiming.delete(key);
+  return timing;
+}
+
 /** Keys already warned about a missing shell store family (once per key). */
 const warnedMissingStore = new Set<string>();
 

package/src/rsc/ssr-setup.ts

@@ -7,10 +7,19 @@
  */
 
 import type { HandlerContext } from "./handler-context.js";
-import type { SSRModule } from "./types.js";
+import type { SSRModule, SSRRenderOptions } from "./types.js";
 import type { SSRStreamMode } from "../router/router-options.js";
 import type { MetricsStore } from "../server/context.js";
+import type {
+  RscFlightStage,
+  RscPreparedHtmlRender,
+} from "./render-pipeline.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];
@@ -65,6 +74,49 @@ export function startSSRSetup<TEnv>(
   ]);
 }
 
+export interface SsrHtmlStageOptions<TEnv> {
+  ctx: HandlerContext<TEnv>;
+  request: Request;
+  env: TEnv;
+  url: URL;
+  /** Metrics store for ssr:module-load / ssr:stream-mode timing (per call site). */
+  metricsStore: MetricsStore | undefined;
+  /**
+   * renderHTML options minus streamMode (the stage resolves streamMode). Carries
+   * the per-site nonce and, for the PE action re-render, formState. Spread
+   * verbatim so each call site's exact key set is preserved.
+   */
+  render: Omit<SSRRenderOptions, "streamMode">;
+  /** ResponseInit merged into the prepared render (e.g. content-type). */
+  init?: ResponseInit;
+}
+
+/**
+ * Build the `html` stage callback renderRscResponse drives: await the (possibly
+ * early-kicked-off) SSR setup, then renderHTML over the Flight stream. The four
+ * render paths (rsc-rendering full/partial, 404, PE, PE-error) differ only in
+ * metricsStore, render options (nonce/formState), and init — threaded here so
+ * the getSSRSetup + renderHTML wiring lives in one place.
+ */
+export function createSsrHtmlStage<TEnv>(
+  options: SsrHtmlStageOptions<TEnv>,
+): (flight: RscFlightStage) => Promise<RscPreparedHtmlRender> {
+  return async (flight) => {
+    const [ssrModule, streamMode] = await getSSRSetup(
+      options.ctx,
+      options.request,
+      options.env,
+      options.url,
+      options.metricsStore,
+    );
+    return {
+      render: () =>
+        ssrModule.renderHTML(flight.stream, { ...options.render, streamMode }),
+      ...(options.init && { init: options.init }),
+    };
+  };
+}
+
 /**
  * Retrieve the SSR setup result. Returns the early-kicked-off promise
  * when available (stashed on request variables), otherwise starts a
@@ -90,12 +142,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 +194,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 +216,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/rsc/types.ts

@@ -41,6 +41,8 @@ export interface RscPayload {
     handles?: AsyncGenerator<HandleData, void, unknown>;
     /** RSC version string for cache invalidation */
     version?: string;
+    /** Cloudflare dev worker generation used for stale-document convergence. */
+    devDiscoveryEpoch?: number;
     /** TTL in milliseconds for the client-side in-memory prefetch cache */
     prefetchCacheTTL?: number;
     /** Max entries in the client-side in-memory prefetch cache (FIFO eviction) */

package/src/segment-fragments.ts

@@ -0,0 +1,124 @@
+/**
+ * Segment Flight-fragment envelopes (PPR fast-path payload splice, issue #700).
+ *
+ * On a shell-HIT tail, replayed (baked) segments do NOT round-trip through the
+ * server codec (deserialize -> re-serialize) per request. The stored RSC
+ * 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.
+ *
+ * Envelopes appear ONLY on fields that hold ReactNodes (component / layout /
+ * loading). A plain object is never a valid ReactNode, so the marker cannot
+ * collide with legitimate segment content; loader data fields (consumer data,
+ * any shape) are never enveloped.
+ *
+ * This module is shared client/server code (browser + SSR + RSC import it) —
+ * it must stay dependency-free: no plugin-rsc, no request-context.
+ */
+
+import type { ResolvedSegment } from "./types.js";
+
+/**
+ * One RSC-encoded fragment traveling inside an RscPayload segment field.
+ * `f` is the stored Flight document (segment-codec output) for that field.
+ */
+export interface SegmentFlightFragment {
+  __rangoFragment: 1;
+  f: string;
+}
+
+/** Wrap a stored fragment string for the wire. */
+export function segmentFragment(encoded: string): SegmentFlightFragment {
+  return { __rangoFragment: 1, f: encoded };
+}
+
+/** True iff `value` is a fragment envelope (see collision note in the header). */
+export function isSegmentFragment(
+  value: unknown,
+): value is SegmentFlightFragment {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __rangoFragment?: unknown }).__rangoFragment === 1 &&
+    typeof (value as { f?: unknown }).f === "string"
+  );
+}
+
+/**
+ * A consumer-side Flight deserializer: the browser's or the SSR runtime's
+ * createFromReadableStream (each resolves client references through its own
+ * module map, exactly as it does for the outer payload stream). Non-generic
+ * so both environments' generic createFromReadableStream signatures assign
+ * directly.
+ */
+export type FragmentDecoder = (
+  stream: ReadableStream<Uint8Array>,
+) => Promise<unknown>;
+
+/** One-chunk byte stream over an encoded fragment (local: this module must not
+ *  import segment-codec, which pulls plugin-rsc into client bundles). */
+function fragmentToStream(encoded: string): ReadableStream<Uint8Array> {
+  const bytes = new TextEncoder().encode(encoded);
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+/** The segment fields that may carry an envelope (ReactNode fields only). */
+const FRAGMENT_FIELDS = ["component", "layout", "loading"] as const;
+
+/**
+ * Expand every fragment envelope in `segments` IN PLACE via `decode`,
+ * in parallel. A payload with no envelopes (every non-shell-HIT payload) costs
+ * one synchronous field scan. A failing fragment decode rejects the whole
+ * expansion: the caller's payload promise rejects, which on the SSR side
+ * errors the HIT tail (serveShellHit then schedules the healing recapture) —
+ * the same posture as a parseable-but-mismatched postponed blob.
+ */
+export async function expandSegmentFragments(
+  segments: ResolvedSegment[] | undefined,
+  decode: FragmentDecoder,
+): Promise<void> {
+  if (!segments || segments.length === 0) return;
+  const decodes: Promise<void>[] = [];
+  for (const segment of segments) {
+    for (const field of FRAGMENT_FIELDS) {
+      const value = segment[field];
+      if (isSegmentFragment(value)) {
+        // Promise.resolve() adoption is load-bearing: some deserializers
+        // (react-server-dom's Flight client) return a THENABLE Chunk whose
+        // .then returns undefined — chaining directly would push undefined
+        // into the barrier and Promise.all would not wait for the decode.
+        decodes.push(
+          Promise.resolve(decode(fragmentToStream(value.f))).then((node) => {
+            segment[field] = node as ResolvedSegment[typeof field];
+          }),
+        );
+      }
+    }
+  }
+  if (decodes.length > 0) await Promise.all(decodes);
+}
+
+/**
+ * True when any segment carries an unexpanded envelope. Cheap scan used by
+ * consumers that only need to know whether an expansion pass is required.
+ */
+export function hasSegmentFragments(
+  segments: ResolvedSegment[] | undefined,
+): boolean {
+  if (!segments) return false;
+  for (const segment of segments) {
+    for (const field of FRAGMENT_FIELDS) {
+      if (isSegmentFragment(segment[field])) return true;
+    }
+  }
+  return false;
+}