@rangojs/router 0.0.0-experimental.143 → 0.0.0-experimental.144

package/src/ssr/index.tsx

@@ -247,11 +247,22 @@ async function readStreamToUint8Array(
   const reader = stream.getReader();
   const chunks: Uint8Array[] = [];
   let total = 0;
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    chunks.push(value);
-    total += value.length;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      total += value.length;
+    }
+  } catch (error) {
+    // Mid-read abort path (documented): the prelude stream errors with our
+    // abort reason while we are still reading it. Cancel the source before
+    // rethrowing so it is not left uncancelled; releaseLock always runs in
+    // finally. Mirrors src/rsc/rsc-rendering.ts's serve-side reader cleanup.
+    reader.cancel(error).catch(() => {});
+    throw error;
+  } finally {
+    reader.releaseLock();
   }
   const out = new Uint8Array(total);
   let offset = 0;
@@ -434,113 +445,140 @@ export function createShellCaptureHandler<TEnv = unknown>(
   ): Promise<ShellCaptureResult | null> {
     const maxWaitMs = opts.maxWaitMs ?? DEFAULT_SHELL_CAPTURE_MAX_WAIT_MS;
 
-    // No nonce (nonce'd requests never reach capture); no formState.
-    const SsrRoot = createSsrRootComponent({
-      createFromReadableStream,
-      rscStream,
-    });
-
-    const bootstrapScriptContent = await loadBootstrapScriptContent();
-
-    // Start prerender first, then run the abort schedule concurrently. When
-    // holes are pending, prerender's promise settles only after abort(); when
-    // the shell completes with no holes it settles on its own and the later
-    // abort() is a harmless no-op (the DATA variant).
-    const controller = new AbortController();
-    const prerenderPromise = prerender(<SsrRoot />, {
-      signal: controller.signal,
-      bootstrapScriptContent,
-      // Abort is how capture WORKS: once the shell is quiet we abort() to freeze
-      // the prelude and let the still-pending holes postpone. React reports the
-      // abort reason for each pending boundary through onError. Without an onError
-      // here React falls back to console.error, so every capture that still has a
-      // live hole at abort time (the normal case, and every cold-module capture
-      // where the shell is not yet done) dumps a DOMException [AbortError] stack —
-      // once per pending boundary. That is EXPECTED degradation, not a failure, so
-      // swallow the abort here. Genuine shell render errors (a component throwing)
-      // are NOT the abort and still surface through the deps.onError channel, the
-      // same one renderHTML uses. See docs/design/ppr-shell-resume.md.
-      onError: (error: unknown) => {
-        if (
-          controller.signal.aborted &&
-          (error as { name?: string } | null)?.name === "AbortError"
-        ) {
-          return;
-        }
-        reportRenderError(onError, error);
-      },
-    });
-    // Pre-attach a no-op catch: the real await sits AFTER quiesce + the
-    // post-quiesce hops, so an early prerender rejection (e.g. a bake-lane
-    // loader tripping the identity guard within milliseconds) would otherwise
-    // spend several turns handler-less and crash the worker as an unhandled
-    // rejection. The actual rejection handling still happens at the await
-    // below; this parallel handler only keeps the gap crash-free.
-    prerenderPromise.catch(() => {});
-
-    // Wait for the caller's quiesce signal. By the time it resolves the Flight
-    // input is byte-quiet and FROZEN by the capture gate (shell-capture.ts
-    // gateFlightForCapture), so there is no wall-clock debounce here — maxWaitMs
-    // is only the pathological guard for a shell that never goes quiet (a root
-    // postpone / hung handle), and should never fire in tests.
-    const timer = createCancelableTimeout(maxWaitMs);
-    try {
-      await Promise.race([opts.quiesce, timer.promise]);
-    } finally {
-      timer.cancel();
-    }
-    // Fixed task hops before the abort: give React's fizz worker turns to flush
-    // the now-complete shell and mark the still-pending boundaries as POSTPONED
-    // rather than errored. Deterministic (the byte set is already frozen), so a
-    // fixed count of turns suffices — no wall-clock.
-    for (let i = 0; i < POST_QUIESCE_TASK_HOPS; i++) {
-      await macrotask();
-    }
-    controller.abort();
-
-    // A hard prerender rejection (fatal shell error) propagates. Expected
-    // degradation surfaces three ways and all return null: a trivial prelude
-    // (sanity gate below), the prerender REJECTING with an AbortError, or the
-    // prelude STREAM erroring with the abort reason mid-read — both abort
-    // shapes happen when our own abort lands before the shell completed (seen
-    // on dev cold paths, where module transform / first-render latency
-    // outlasts flight quiesce; a later request re-captures against warm
-    // modules and succeeds).
-    let prelude: Uint8Array;
-    let postponed: unknown;
+    // Arm the maxWaitMs deadline BEFORE the first await so it bounds the ENTIRE
+    // capture, the bootstrap-script load included. loadBootstrapScriptContent()
+    // used to run before the timer, so a hung/slow bootstrap load hung
+    // captureShellHTML with no upper bound and held the background capture task
+    // open. One deadline, shared by the bootstrap race below and the quiesce
+    // race, keeps the whole path "bounded by maxWaitMs like every quiesce input".
+    const deadline = createCancelableTimeout(maxWaitMs);
     try {
-      const result = await prerenderPromise;
-      prelude = await readStreamToUint8Array(result.prelude);
-      postponed = result.postponed;
-    } catch (error) {
-      // Name-based match: the rejection is a DOMException on workerd/Node,
-      // which is not an Error subclass there, so instanceof Error would let
-      // the abort escape as a spurious reported error.
-      if (
-        controller.signal.aborted &&
-        (error as { name?: string } | null)?.name === "AbortError"
-      ) {
+      // No nonce (nonce'd requests never reach capture); no formState.
+      const SsrRoot = createSsrRootComponent({
+        createFromReadableStream,
+        rscStream,
+      });
+
+      // Bootstrap load raced against the deadline. A load that never resolves
+      // within maxWaitMs is the same bounded no-shell degrade as a shell that
+      // never goes quiet: return null, do not hang. A load that REJECTS is a
+      // genuine error and still propagates (it is not the deadline). `null` is
+      // the deadline sentinel — disjoint from the load's `Promise<string>`, so
+      // the race narrows to `string | null` with no wrapper. The no-op catch
+      // keeps a late rejection off the unhandledRejection path when the deadline
+      // already won; a rejection that lands first still propagates out.
+      const load = loadBootstrapScriptContent();
+      load.catch(() => {});
+      const bootstrapScriptContent = await Promise.race([
+        load,
+        deadline.promise.then(() => null),
+      ]);
+      if (bootstrapScriptContent === null) {
         return null;
       }
-      throw error;
-    }
 
-    // Sanity gate: a prelude with no `<body` is the no-shell failure mode.
-    // Return null and store nothing; the request falls back to axis 1 and a
-    // later request re-captures. The dominant real-world cause is a loader
-    // route WITHOUT a route-level loading() boundary: renderSegments' loading-
-    // less branch awaits loader data at TREE-BUILD, so the masked loader pins
-    // the whole tree above <body> (root postpone). Root-postponing layouts and
-    // hung handles degrade the same way. shell-capture.ts logs a once-per-key
-    // warning so the eternal-MISS shape is diagnosable.
-    if (!new TextDecoder().decode(prelude).includes("<body")) {
-      return null;
-    }
+      // Start prerender first, then run the abort schedule concurrently. When
+      // holes are pending, prerender's promise settles only after abort(); when
+      // the shell completes with no holes it settles on its own and the later
+      // abort() is a harmless no-op (the DATA variant).
+      const controller = new AbortController();
+      // Private reason object: the deliberate abort is identified by object
+      // IDENTITY in both the onError below and the post-await catch. React
+      // propagates this EXACT object to onError for every still-pending boundary
+      // (verified identity-preserving), and rejects/errors the prelude with it.
+      const abortReason = { rangoShellCaptureAbort: true };
+      const prerenderPromise = prerender(<SsrRoot />, {
+        signal: controller.signal,
+        bootstrapScriptContent,
+        // Abort is how capture WORKS: once the shell is quiet we abort() to
+        // freeze the prelude and let the still-pending holes postpone. React
+        // reports the abort reason for each pending boundary through onError.
+        // Without an onError here React falls back to console.error, so every
+        // capture that still has a live hole at abort time (the normal case)
+        // dumps a stack once per pending boundary. That is EXPECTED degradation,
+        // so swallow OUR abort — matched by IDENTITY (error === abortReason).
+        // Discriminate by identity, NOT error.name: capture aborts before
+        // awaiting, so signal.aborted is unconditionally true and a name check
+        // swallowed genuine AbortError-named throws (a component's own
+        // fetch/AbortController cancellation) as if they were our abort. Genuine
+        // render errors are NOT our sentinel and still surface through
+        // deps.onError, the same channel renderHTML uses. See
+        // docs/design/ppr-shell-resume.md.
+        onError: (error: unknown) => {
+          if (error === abortReason) {
+            return;
+          }
+          reportRenderError(onError, error);
+        },
+      });
+      // Pre-attach a no-op catch: the real await sits AFTER quiesce + the
+      // post-quiesce hops, so an early prerender rejection (e.g. a bake-lane
+      // loader tripping the identity guard within milliseconds) would otherwise
+      // spend several turns handler-less and crash the worker as an unhandled
+      // rejection. The actual rejection handling still happens at the await
+      // below; this parallel handler only keeps the gap crash-free.
+      prerenderPromise.catch(() => {});
+
+      // Wait for the caller's quiesce signal, bounded by the SAME deadline. By
+      // the time it resolves the Flight input is byte-quiet and FROZEN by the
+      // capture gate (shell-capture.ts gateFlightForCapture), so there is no
+      // wall-clock debounce here — maxWaitMs is only the pathological guard for a
+      // shell that never goes quiet (a root postpone / hung handle).
+      await Promise.race([opts.quiesce, deadline.promise]);
+      // Fixed task hops before the abort: give React's fizz worker turns to flush
+      // the now-complete shell and mark the still-pending boundaries as POSTPONED
+      // rather than errored. Deterministic (the byte set is already frozen), so a
+      // fixed count of turns suffices — no wall-clock.
+      for (let i = 0; i < POST_QUIESCE_TASK_HOPS; i++) {
+        await macrotask();
+      }
+      controller.abort(abortReason);
+
+      // A hard prerender rejection (fatal shell error) propagates. Expected
+      // degradation surfaces three ways and all return null: a trivial prelude
+      // (sanity gate below), the prerender REJECTING with our abort reason, or
+      // the prelude STREAM erroring with our abort reason mid-read — both abort
+      // shapes happen when our own abort lands before the shell completed (seen
+      // on dev cold paths, where module transform / first-render latency
+      // outlasts flight quiesce; a later request re-captures against warm
+      // modules and succeeds).
+      let prelude: Uint8Array;
+      let postponed: unknown;
+      try {
+        const result = await prerenderPromise;
+        prelude = await readStreamToUint8Array(result.prelude);
+        postponed = result.postponed;
+      } catch (error) {
+        // Identity match: swallow ONLY our own deliberate abort
+        // (error === abortReason). Not error.name — capture aborts before this
+        // await, so signal.aborted is always true, and a name check let a
+        // genuine AbortError-named throw masquerade as our abort and degrade
+        // into a retryable no-shell, hiding real failures from reportCacheError.
+        if (error === abortReason) {
+          return null;
+        }
+        throw error;
+      }
+
+      // Sanity gate: a prelude with no `<body` is the no-shell failure mode.
+      // Return null and store nothing; the request falls back to axis 1 and a
+      // later request re-captures. The dominant real-world cause is a loader
+      // route WITHOUT a route-level loading() boundary: renderSegments' loading-
+      // less branch awaits loader data at TREE-BUILD, so the masked loader pins
+      // the whole tree above <body> (root postpone). Root-postponing layouts and
+      // hung handles degrade the same way. shell-capture.ts logs a once-per-key
+      // warning so the eternal-MISS shape is diagnosable.
+      if (!new TextDecoder().decode(prelude).includes("<body")) {
+        return null;
+      }
 
-    return {
-      prelude,
-      postponed: postponed == null ? null : JSON.stringify(postponed),
-    };
+      return {
+        prelude,
+        postponed: postponed == null ? null : JSON.stringify(postponed),
+      };
+    } finally {
+      deadline.cancel();
+    }
   };
 }
 

package/src/testing/dispatch.ts

@@ -757,6 +757,10 @@ export async function dispatch<TEnv = any>(
           durationMs: performance.now() - telemetryStart,
           segmentCount: 0,
           cacheHit: false,
+          // dispatch's final response IS built before request.end (unlike
+          // match()/matchPartial(), whose Response is built after), so stamp its
+          // status — the same field a thrown-Response short-circuit carries.
+          status: finalResponse.status,
         });
       }
 
@@ -785,6 +789,9 @@ export async function dispatch<TEnv = any>(
             durationMs: performance.now() - telemetryStart,
             segmentCount: 0,
             cacheHit: false,
+            // Carry the short-circuit Response's status (parity with
+            // match-handlers.ts's thrown-Response request.end).
+            status: error.status,
           });
         } else {
           safeEmit(resolveSink(sink), {

package/src/vite/inject-client-debug.ts

@@ -1,3 +1,5 @@
+import type { Connect } from "vite";
+
 /**
  * Bake the resolved INTERNAL_RANGO_DEBUG value into the router's `internal-debug`
  * module so the flag reaches the CLIENT debug logs by just setting the env var.
@@ -10,27 +12,77 @@
  * runs on the module regardless of how (or whether) the define is delivered, in
  * both dev and build and for every environment, so the discovery plugin uses this
  * to replace the module with the resolved literal.
- *
+ */
+
+/**
+ * Scope to the router's own internal-debug module: the published package
+ * (`/@rangojs/router/`, incl. pnpm's nested layout) or the monorepo workspace
+ * (`/packages/rangojs-router/`). The package-anchored path avoids matching a
+ * consumer file that merely sits under a directory named `rangojs-router`.
+ * Accepts module ids and dev-server URLs (`/@fs/...internal-debug.ts?v=abc`).
+ */
+export function isRouterInternalDebugId(id: string): boolean {
+  if (!id.includes("internal-debug")) return false;
+  const norm = id.replace(/\\/g, "/");
+  return (
+    /\/internal-debug\.[cm]?[jt]sx?(\?|$)/.test(norm) &&
+    (norm.includes("/@rangojs/router/") ||
+      norm.includes("/packages/rangojs-router/"))
+  );
+}
+
+/**
+ * Transform: replace the module with the resolved literal.
  * Returns null for any module that is not the router's internal-debug module.
  */
 export function injectClientDebugFlag(
   id: string,
 ): { code: string; map: null } | null {
   // Cheap early-out: this hook runs on every module in every environment.
-  if (!id.includes("internal-debug")) return null;
-  const norm = id.replace(/\\/g, "/");
-  // Scope to the router's own internal-debug module: the published package
-  // (`/@rangojs/router/`, incl. pnpm's nested layout) or the monorepo workspace
-  // (`/packages/rangojs-router/`). The package-anchored path avoids matching a
-  // consumer file that merely sits under a directory named `rangojs-router`.
-  const isInternalDebug =
-    /\/internal-debug\.[cm]?[jt]sx?(\?|$)/.test(norm) &&
-    (norm.includes("/@rangojs/router/") ||
-      norm.includes("/packages/rangojs-router/"));
-  if (!isInternalDebug) return null;
+  if (!isRouterInternalDebugId(id)) return null;
   // Emit the whole module: internal-debug.ts has a single export, kept in sync.
   return {
     code: `export const INTERNAL_RANGO_DEBUG = ${!!process.env.INTERNAL_RANGO_DEBUG};\n`,
     map: null,
   };
 }
+
+/**
+ * Dev middleware companion: serve the internal-debug module `no-cache` so the
+ * browser revalidates it (etag) instead of trusting an immutable cache entry.
+ *
+ * Why: the transform bakes the flag into module CONTENT, but a published
+ * consumer resolves the module into node_modules, where dev serves it as
+ * `internal-debug.ts?v=<hash>` with `Cache-Control: max-age=31536000,immutable`.
+ * That `?v=` hash does not vary with env vars (verified on Vite 8: getConfigHash
+ * hashes NODE_ENV, resolve, plugin names, optimizeDeps -- not arbitrary env
+ * state), so toggling the flag changed the content under an unchanged immutable
+ * URL: a browser that ever loaded the app with the flag off kept the
+ * baked-`false` module across dev-server restarts, and INTERNAL_RANGO_DEBUG
+ * never reached the FE logs while the server logs worked. The monorepo was
+ * immune -- workspace source is outside node_modules and served no-cache --
+ * which is why this bit only npm consumers.
+ *
+ * internal-debug.ts is the ONLY flag-varying module in the graph (its importers
+ * are byte-identical across flag states), so forcing revalidation for this one
+ * tiny module is sufficient and costs one conditional request per session. The
+ * middleware is unconditional (not gated on the flag) so an already-poisoned
+ * cache heals in both directions. Alternatives that do not work: a plugin
+ * `resolveId` appending a flag query never fires in Vite 8 dev for
+ * fs-resolvable relative imports, and the pre-#621 `define` no longer rotates
+ * the optimizer hash (define contents are not part of getConfigHash).
+ */
+export function internalDebugNoCacheMiddleware(): Connect.NextHandleFunction {
+  return function rangoInternalDebugNoCache(req, res, next) {
+    if (req.url && isRouterInternalDebugId(req.url)) {
+      const setHeader = res.setHeader.bind(res);
+      res.setHeader = (name, value) => {
+        return setHeader(
+          name,
+          name.toLowerCase() === "cache-control" ? "no-cache" : value,
+        );
+      };
+    }
+    next();
+  };
+}

package/src/vite/router-discovery.ts

@@ -19,7 +19,10 @@ import {
   createScanFilter,
 } from "../build/generate-route-types.js";
 import { firstCodeMatchIndex } from "../build/route-types/source-scan.js";
-import { injectClientDebugFlag } from "./inject-client-debug.js";
+import {
+  injectClientDebugFlag,
+  internalDebugNoCacheMiddleware,
+} from "./inject-client-debug.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
 import { createVirtualStubPlugin } from "./plugins/virtual-stub-plugin.js";
 import {
@@ -392,6 +395,11 @@ export function createRouterDiscoveryPlugin(
       if ((globalThis as any).__rscRouterDiscoveryActive) return;
       s.devServer = server;
 
+      // Serve the internal-debug module no-cache: consumers resolve it into
+      // node_modules, where dev's immutable `?v=` caching pinned browsers to a
+      // stale baked INTERNAL_RANGO_DEBUG. See internalDebugNoCacheMiddleware.
+      server.middlewares.use(internalDebugNoCacheMiddleware());
+
       // Discovery promise that the handler can await if requests arrive
       // before discovery completes
       let resolveDiscovery: () => void;