@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

package/src/router.ts

@@ -5,10 +5,14 @@ import { isCachedFunction } from "./cache/taint.js";
 import { assertClientComponent } from "./component-utils.js";
 import { DefaultDocument } from "./components/DefaultDocument.js";
 import type { SerializedManifest } from "./debug.js";
+import {
+  DEV_DISCOVERY_EPOCH_HEADER,
+  DEV_DISCOVERY_PROBE_HEADER,
+  isValidDevDiscoveryEpoch,
+} from "./dev-discovery-protocol.js";
 import { createReverse, type ReverseFunction } from "./reverse.js";
 import {
   registerRouteMap,
-  getPrecomputedEntries,
   getRouterManifest,
   getRouterPrecomputedEntries,
   ensureRouterManifest,
@@ -158,7 +162,6 @@ export function createRouter<TEnv = any>(
     prefetchConcurrency: prefetchConcurrencyOption,
     stateCookiePrefix: stateCookiePrefixOption,
     warmup: warmupOption,
-    allowDebugManifest: allowDebugManifestOption = false,
     telemetry: telemetrySink,
     tracing: tracingOption,
     ssr: ssrOption,
@@ -168,6 +171,7 @@ export function createRouter<TEnv = any>(
     originCheck: originCheckOption,
     viewTransition: viewTransitionOption = "auto",
     debugCacheSignal: debugCacheSignalOption = false,
+    debugShellCapture: debugShellCaptureOption,
     strictMode: strictModeOption = true,
   } = options;
 
@@ -229,6 +233,14 @@ export function createRouter<TEnv = any>(
   // order (unlike the counter which depends on import order).
   const routerId =
     userProvidedId ?? injectedId ?? `router_${nextRouterAutoId()}`;
+  const rawDevDiscoveryEpoch = (
+    globalThis as typeof globalThis & {
+      __RANGO_DEV_DISCOVERY_EPOCH?: unknown;
+    }
+  ).__RANGO_DEV_DISCOVERY_EPOCH;
+  const devDiscoveryEpoch = isValidDevDiscoveryEpoch(rawDevDiscoveryEpoch)
+    ? rawDevDiscoveryEpoch
+    : undefined;
 
   // Resolve the rango state cookie name once, here, so the two cookie writers
   // (the client document.cookie writer and the server Set-Cookie writer)
@@ -405,8 +417,7 @@ export function createRouter<TEnv = any>(
     string,
     Record<string, string>
   > | null {
-    const current =
-      getRouterPrecomputedEntries(routerId) ?? getPrecomputedEntries();
+    const current = getRouterPrecomputedEntries(routerId);
     if (current !== precomputedSource) {
       precomputedSource = current;
       // buildPrecomputedByPrefix drops any staticPrefix owned by more than one
@@ -669,6 +680,7 @@ export function createRouter<TEnv = any>(
 
   // Prerender/static match deps (bind closure state for extracted functions)
   const prerenderDeps = {
+    routerId,
     findMatch,
     buildRouterContext,
     mergedRouteMap,
@@ -700,6 +712,7 @@ export function createRouter<TEnv = any>(
     routeName?: string,
     buildEnv?: TEnv,
     devMode?: boolean,
+    rootScoped?: boolean,
   ) {
     return _renderStaticSegment<TEnv>(
       handler,
@@ -708,6 +721,8 @@ export function createRouter<TEnv = any>(
       routeName,
       buildEnv,
       devMode,
+      routerId,
+      rootScoped,
     );
   }
 
@@ -788,6 +803,7 @@ export function createRouter<TEnv = any>(
           parent: syntheticMapRoot,
           counters: {},
           mountIndex: currentMountIndex,
+          routerId,
           cacheProfiles: resolvedCacheProfiles,
           // basename sets the initial URL prefix so all path() patterns
           // are registered with the prefix (e.g. "/admin" + "/users" = "/admin/users").
@@ -1007,6 +1023,10 @@ export function createRouter<TEnv = any>(
     // Expose router-wide performance debugging for request-level metrics setup
     debugPerformance,
 
+    // Expose the PPR shell-capture debug sink for the render layer
+    // (rsc-rendering resolves it into the capture descriptor)
+    debugShellCapture: debugShellCaptureOption,
+
     // Expose resolved span tracing for the handler (Cloudflare custom spans)
     tracing: resolvedTracing,
 
@@ -1016,9 +1036,6 @@ export function createRouter<TEnv = any>(
     // undefined when unconfigured and call sites gate on truthiness.
     telemetry: telemetrySink,
 
-    // Expose debug manifest flag for handler
-    allowDebugManifest: allowDebugManifestOption,
-
     // Expose origin check configuration for handler (default: enabled)
     originCheck: originCheckOption ?? true,
 
@@ -1077,6 +1094,9 @@ export function createRouter<TEnv = any>(
     // Expose basename for runtime manifest generation
     __basename: basename,
 
+    // Pin payload metadata to the worker generation that created this router.
+    __devDiscoveryEpoch: devDiscoveryEpoch,
+
     // Expose router-level boundary defaults for build-time clientChunks
     // discovery (so a "use client" default boundary lands in app-fallback).
     // These are createRouter options, never pushed onto EntryData.
@@ -1095,6 +1115,18 @@ export function createRouter<TEnv = any>(
         | null = null;
 
       return async (request: Request, input: RouterRequestInput<TEnv> = {}) => {
+        if (
+          devDiscoveryEpoch !== undefined &&
+          request.headers.get(DEV_DISCOVERY_PROBE_HEADER) ===
+            String(devDiscoveryEpoch)
+        ) {
+          return new Response(null, {
+            headers: {
+              [DEV_DISCOVERY_EPOCH_HEADER]: String(devDiscoveryEpoch),
+            },
+          });
+        }
+
         // Trigger lazy import of per-router manifest data before route matching.
         // No-op if data is already loaded or no loader is registered.
         await ensureRouterManifest(routerId);

package/src/rsc/capture-queue.ts

@@ -0,0 +1,67 @@
+/**
+ * Per-isolate shell-capture serialization.
+ *
+ * Captures are CPU-bound background renders whose quiet detection is
+ * task-quantized (FLIGHT_QUIET_HOPS macrotask hops with zero new bytes). Two
+ * captures running concurrently starve each other: one grinding capture —
+ * e.g. a prerender+ppr route whose capture round-trips the dev
+ * /__rsc_prerender endpoint, whose per-request module re-import can peg a
+ * slow CI runner for seconds — keeps the sibling's render byte-silent past
+ * its abort budget, so the sibling freezes a trivial prelude and stores
+ * nothing. Observed on GH runners as ROTATING eternal-MISS victims (the
+ * warmup on one shard, a composition probe, then /ppr-shell?probe=stream once
+ * the first was quieted) while every local run passed.
+ *
+ * Serializing capture execution removes the cross-talk: each capture's quiet
+ * window observes only its own work. Captures are TTL-scale background work,
+ * so queueing costs latency-to-HIT only — never a served response. On workerd
+ * a queued capture rides the scheduling request's waitUntil, whose lifetime
+ * is bounded; a capture killed mid-queue by that bound simply recaptures on a
+ * later request (the existing best-effort contract).
+ *
+ * The chain link resolves in `finally` and the prior link is awaited with a
+ * swallow, so one rejected capture can never wedge every later one.
+ */
+let captureQueue: Promise<void> = Promise.resolve();
+
+/**
+ * Upper bound on how long one queue link may hold the queue. A capture task
+ * normally settles well inside this (attempt + in-place retry + writes), but
+ * a task wedged on never-settling I/O — a workerd waitUntil fetch that pends
+ * instead of rejecting (seen on GH runners with the dev prerender store
+ * before its fetch was time-bounded) — must not block every later capture in
+ * the isolate. At the cap the QUEUE is released; the wedged task itself stays
+ * detached (its own per-key guards clean up when/if it settles).
+ */
+const QUEUE_LINK_CAP_MS = 60_000;
+
+/**
+ * Run `task` after every previously enqueued capture has settled. Returns a
+ * promise for THIS task's completion (rejections propagate to the caller —
+ * the queue itself is insulated).
+ */
+export function enqueueSerializedCapture(
+  task: () => Promise<void>,
+): Promise<void> {
+  const prior = captureQueue;
+  let releaseQueue!: () => void;
+  captureQueue = new Promise<void>((resolve) => {
+    releaseQueue = resolve;
+  });
+  return (async () => {
+    await prior.catch(() => {});
+    let capTimer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        task(),
+        new Promise<void>((resolve) => {
+          capTimer = setTimeout(resolve, QUEUE_LINK_CAP_MS);
+          (capTimer as { unref?: () => void }).unref?.();
+        }),
+      ]);
+    } finally {
+      if (capTimer) clearTimeout(capTimer);
+      releaseQueue();
+    }
+  })();
+}

package/src/rsc/handler-context.ts

@@ -15,6 +15,7 @@ import type { SSRStreamMode } from "../router/router-options.js";
 export interface HandlerContext<TEnv = unknown> {
   router: RangoInternal<TEnv, any>;
   version: string;
+  devDiscoveryEpoch?: number;
   renderToReadableStream: RSCDependencies["renderToReadableStream"];
   decodeReply: RSCDependencies["decodeReply"];
   createTemporaryReferenceSet: RSCDependencies["createTemporaryReferenceSet"];

package/src/rsc/handler.ts

@@ -30,7 +30,13 @@ import {
   interceptRedirectForPartial,
   buildRouteMiddlewareEntries,
 } from "./helpers.js";
+import { renderRscFlightStage, renderRscResponse } from "./render-pipeline.js";
 import { guardOutgoingRedirect } from "./redirect-guard.js";
+import {
+  resolveSoftRedirectUrl,
+  resolveExternalRedirect,
+  safeSameOriginLanding,
+} from "../redirect-origin.js";
 import { resolvedHandleStream } from "../handles/deferred-resolution.js";
 import {
   isWebSocketUpgradeResponse,
@@ -52,8 +58,6 @@ import {
 import { contextSet } from "../context-var.js";
 import {
   hasCachedManifest,
-  getRouteTrie,
-  getPrecomputedEntries,
   waitForManifestReady,
   getRouterManifest,
   getRouterTrie,
@@ -76,9 +80,11 @@ import {
 import { handleRscRendering } from "./rsc-rendering.js";
 import {
   withTimeout,
+  isTimeoutEnabled,
   RouterTimeoutError,
   createDefaultTimeoutResponse,
   type TimeoutPhase,
+  type RenderTimeoutContext,
 } from "../router/timeout.js";
 import {
   createMetricsStore,
@@ -89,7 +95,7 @@ import { observePhase, PHASES } from "../router/instrument.js";
 import { safeEmit, resolveSink, getRequestId } from "../router/telemetry.js";
 import {
   startSSRSetup,
-  getSSRSetup,
+  createSsrHtmlStage,
   mayNeedSSR,
   isRscRequest,
   SSR_SETUP_VAR,
@@ -236,7 +242,25 @@ export function createRSCHandler<
     actionId?: string,
   ): Promise<Response> {
     const timeoutError = new RouterTimeoutError(phase, durationMs);
+    const cursor = _getRequestContext<TEnv>()?._renderForeground;
+    const render: RenderTimeoutContext | undefined =
+      phase === "render-start" && cursor
+        ? {
+            mode: cursor.mode,
+            phase: cursor.phase,
+            state: cursor.state,
+            completed: cursor.completed,
+            total: cursor.total,
+            ...(cursor.phaseStartedAt !== undefined && {
+              phaseDurationMs: performance.now() - cursor.phaseStartedAt,
+            }),
+          }
+        : undefined;
 
+    // Each surface gets its OWN shallow copy of the snapshot. onError, telemetry,
+    // and onTimeout are independent consumers; a consumer that mutates its
+    // `render` (e.g. an onError redacting metadata) must not corrupt what the
+    // other two observe.
     callOnError(timeoutError, phase === "action" ? "action" : "handler", {
       request,
       url,
@@ -244,7 +268,12 @@ export function createRSCHandler<
       routeKey,
       actionId,
       handledByBoundary: false,
-      metadata: { timeout: true, phase, durationMs },
+      metadata: {
+        timeout: true,
+        phase,
+        durationMs,
+        ...(render && { render: { ...render } }),
+      },
     });
 
     if (router.telemetry) {
@@ -258,6 +287,7 @@ export function createRSCHandler<
         actionId,
         durationMs,
         customHandler: !!router.onTimeout,
+        ...(render && { render: { ...render } }),
       });
     }
 
@@ -271,6 +301,7 @@ export function createRSCHandler<
           routeKey,
           actionId,
           durationMs,
+          ...(render && { render: { ...render } }),
         });
       } catch (e) {
         if (process.env.NODE_ENV !== "production") {
@@ -287,31 +318,66 @@ export function createRSCHandler<
    * Build a 200 Flight response that carries a redirect URL and optional state.
    * Used when a partial/action request results in a redirect -- fetch
    * auto-follows 3xx so we send the redirect as payload metadata instead.
+   *
+   * The redirect URL is resolved with {@link resolveSoftRedirectUrl} against
+   * the current request origin so an unsafe target never leaves as Flight
+   * metadata (client validators remain defense-in-depth).
    */
   function createRedirectFlightResponse(
     redirectUrl: string,
     locationState?: Record<string, unknown>,
     external?: boolean,
   ): Response {
+    const reqCtx = _getRequestContext<TEnv>();
+    const requestOrigin =
+      reqCtx?.url.origin ?? new URL("http://localhost").origin;
+    // Resolve with the same policy as 3xx guardOutgoingRedirect. Keep
+    // external:true only when the external scheme check passed; a neutralized
+    // landing (javascript:/blocked) must not advertise external.
+    let resolvedUrl: string;
+    let resolvedExternal = false;
+    if (external) {
+      const ext = resolveExternalRedirect(redirectUrl, requestOrigin);
+      if (ext !== null) {
+        resolvedUrl = ext;
+        resolvedExternal = true;
+      } else {
+        resolvedUrl = safeSameOriginLanding(router.basename);
+      }
+    } else {
+      resolvedUrl = resolveSoftRedirectUrl(
+        redirectUrl,
+        requestOrigin,
+        router.basename,
+        false,
+      );
+    }
     const redirectPayload: RscPayload = {
       metadata: {
-        pathname: redirectUrl,
+        pathname: resolvedUrl,
         segments: [],
-        redirect: { url: redirectUrl, ...(external && { external: true }) },
+        redirect: {
+          url: resolvedUrl,
+          ...(resolvedExternal && { external: true }),
+        },
         ...(locationState && { locationState }),
       },
     };
-    const rscStream = renderToReadableStream<RscPayload>(redirectPayload, {
-      onError: (error: unknown) => {
-        const reqCtx = _getRequestContext<TEnv>();
-        if (!reqCtx) return;
-        callOnError(error, "rendering", {
+    const rscStream = reqCtx
+      ? renderRscFlightStage({
+          ctx: { renderToReadableStream, callOnError },
           request: reqCtx.request,
           url: reqCtx.url,
           env: reqCtx.env,
-        });
-      },
-    });
+          payload: redirectPayload,
+          tracking: {
+            mode: reqCtx.url.searchParams.has("_rsc_action")
+              ? "action-revalidation"
+              : "partial",
+            routeKey: reqCtx._routeName,
+          },
+        }).stream
+      : renderToReadableStream<RscPayload>(redirectPayload);
     return createResponseWithMergedHeaders(rscStream, {
       status: 200,
       headers: { "content-type": "text/x-component;charset=utf-8" },
@@ -323,6 +389,7 @@ export function createRSCHandler<
   const handlerCtx: HandlerContext<TEnv> = {
     router,
     version,
+    devDiscoveryEpoch: router.__devDiscoveryEpoch,
     renderToReadableStream,
     decodeReply,
     createTemporaryReferenceSet,
@@ -466,6 +533,12 @@ export function createRSCHandler<
       stateCookieName: router.resolvedStateCookieName,
       version,
     });
+    // Gate on the SAME enabled-semantics withTimeout uses (isTimeoutEnabled):
+    // a `renderStartMs: 0` / negative opt-out disables the timeout, so the
+    // driver's cursor bookkeeping (which only the timeout reads) must be off too.
+    requestContext._renderDiagnosticsEnabled = isTimeoutEnabled(
+      router.timeouts.renderStartMs,
+    );
     // Thread the true request entry timestamp onto the context so a metrics
     // store created MID-request (ctx.debugPerformance() / getMetricsStore) anchors
     // to the real start, not the opt-in moment — phases that began earlier then
@@ -511,6 +584,7 @@ export function createRSCHandler<
     // - Streaming
     // Store basename on request context (scoped per-request via existing ALS)
     requestContext._basename = router.basename;
+    requestContext._routerId = router.id;
 
     // Resolved span tracing for this request (read at each traced phase).
     requestContext._tracing = router.tracing;
@@ -554,6 +628,7 @@ export function createRSCHandler<
             const intercepted = interceptRedirectForPartial(
               mwResponse,
               createRedirectFlightResponse,
+              { requestOrigin: url.origin, basename: router.basename },
             );
             response = intercepted ?? finalizeResponse(mwResponse);
           } else {
@@ -632,35 +707,6 @@ export function createRSCHandler<
   ): Promise<Response> {
     const handlerTiming: string[] = variables.__handlerTiming || [];
 
-    // Debug manifest endpoint: handled before classification since it
-    // doesn't need a route match and needs trie access from the closure.
-    const isDev = process.env.NODE_ENV !== "production";
-    if (
-      url.searchParams.has("__debug_manifest") &&
-      (isDev || router.allowDebugManifest)
-    ) {
-      const trie = getRouterTrie(router.id) ?? getRouteTrie();
-      const routeManifest = getRequiredRouteMap();
-      const { extractAncestryFromTrie } =
-        await import("../build/route-trie.js");
-      return new Response(
-        JSON.stringify(
-          {
-            routerId: router.id,
-            routeManifest,
-            routeAncestry: trie ? extractAncestryFromTrie(trie) : {},
-            routeTrie: trie,
-            precomputedEntries: getPrecomputedEntries(),
-          },
-          null,
-          2,
-        ),
-        {
-          headers: { "Content-Type": "application/json" },
-        },
-      );
-    }
-
     // ---- 1. Classify ----
     // classifyRequest may throw RouteNotFoundError for unknown routes.
     // In that case, fall through to a full-render plan so the pipeline
@@ -885,14 +931,16 @@ export function createRSCHandler<
     // submissions always render HTML (handleProgressiveEnhancement renders via
     // getSSRSetup regardless of Accept). For full/partial-render and action,
     // the render-time HTML decision is exactly !isRscRequest — mayNeedSSR is
-    // the coarse transport pre-filter, isRscRequest is the precise Accept call
-    // (it, unlike mayNeedSSR, treats a MISSING Accept as RSC). Both must pass.
+    // the coarse transport pre-filter, isRscRequest adds the partial/__rsc
+    // flags; both share the same Accept rule (acceptsFlightExplicitly in
+    // ssr-setup.ts), so the Accept call cannot drift between them. Both must
+    // pass.
     const willRenderHtml =
       plan.mode === "pe-render" ||
       (mayNeedSSR(request, url) &&
         !isRscRequest(request, url, plan.mode === "partial-render"));
     if (plan.mode !== "loader" && willRenderHtml) {
-      variables[SSR_SETUP_VAR] = startSSRSetup(
+      const ssrSetup = startSSRSetup(
         handlerCtx,
         request,
         env,
@@ -901,6 +949,15 @@ export function createRSCHandler<
           ? () => getRequestContext()._metricsStore
           : undefined,
       );
+      variables[SSR_SETUP_VAR] = ssrSetup;
+
+      // A handler can short-circuit before HTML rendering consumes this promise
+      // (for example, by returning a redirect). Workerd cancels untracked dynamic
+      // imports at the request boundary; retaining that cancelled promise in the
+      // production SSR module memo makes every later document request hang.
+      // Extending the request lifetime lets the shared setup settle without
+      // delaying the short-circuit response.
+      getRequestContext().executionContext?.waitUntil(ssrSetup);
     }
 
     // ---- Loader fetch ----
@@ -1107,6 +1164,7 @@ export function createRSCHandler<
             const intercepted = interceptRedirectForPartial(
               error,
               createRedirectFlightResponse,
+              { requestOrigin: url.origin, basename: router.basename },
             );
             if (intercepted) return intercepted;
           }
@@ -1169,40 +1227,57 @@ export function createRSCHandler<
             },
           };
 
-          const rscStream = renderToReadableStream(payload, {
-            onError: (error: unknown) => {
-              callOnError(error, "rendering", { request, url, env });
-            },
-          });
-
-          if (isRscRequest(request, url, isPartial)) {
-            return createResponseWithMergedHeaders(rscStream, {
-              status: 404,
-              headers: {
-                "content-type": "text/x-component;charset=utf-8",
-                // Router identity for the client's pre-decode integrity check; a
-                // same-app 404 matches and applies in place. See response-adapter.
-                "X-RSC-Router-Id": router.id,
-              },
-            });
-          }
-
-          const [ssrModule, streamMode] = await getSSRSetup(
-            handlerCtx,
+          const isNotFoundFlightResponse = isRscRequest(
             request,
-            env,
             url,
-            getRequestContext()._metricsStore,
+            isPartial,
+          );
+          const notFoundStageTracking = {
+            mode: isPartial ? ("partial" as const) : ("full" as const),
+            routeKey,
+          };
+          return renderRscResponse(
+            {
+              ctx: handlerCtx,
+              request,
+              url,
+              env,
+              payload,
+              // The 404 path historically records no rsc-serialize metric (it
+              // used the standalone Flight constructor, whose gate was opt-in);
+              // opt out explicitly since renderRscResponse defaults the gate on.
+              recordSerializeMetric: false,
+              init: isNotFoundFlightResponse
+                ? {
+                    status: 404,
+                    headers: {
+                      "content-type": "text/x-component;charset=utf-8",
+                      // Router identity for the client's pre-decode integrity
+                      // check; a same-app 404 applies in place.
+                      "X-RSC-Router-Id": router.id,
+                    },
+                  }
+                : {
+                    status: 404,
+                    headers: {
+                      "content-type": "text/html;charset=utf-8",
+                    },
+                  },
+              tracking: notFoundStageTracking,
+            },
+            isNotFoundFlightResponse
+              ? undefined
+              : {
+                  html: createSsrHtmlStage({
+                    ctx: handlerCtx,
+                    request,
+                    env,
+                    url,
+                    metricsStore: getRequestContext()._metricsStore,
+                    render: { nonce },
+                  }),
+                },
           );
-          const htmlStream = await ssrModule.renderHTML(rscStream, {
-            nonce,
-            streamMode,
-          });
-
-          return createResponseWithMergedHeaders(htmlStream, {
-            status: 404,
-            headers: { "content-type": "text/html;charset=utf-8" },
-          });
         }
 
         // Report unhandled errors
@@ -1233,6 +1308,7 @@ export function createRSCHandler<
           const intercepted = interceptRedirectForPartial(
             mwResponse,
             createRedirectFlightResponse,
+            { requestOrigin: url.origin, basename: router.basename },
           );
           if (intercepted) return intercepted;
         }