@rangojs/router 0.23.0 → 0.24.0

package/src/testing/run-middleware.ts

@@ -13,6 +13,10 @@
  *
  * `nextCalled` counts how many times the terminal `next()` (the finalHandler)
  * ran: 0 when the chain short-circuited, 1 when it ran to completion.
+ *
+ * A `throw rewrite(target)` is reported as `result.rewrite` (the resolved
+ * target) instead of failing the run: production re-dispatches the request
+ * there, which this primitive does not do.
  */
 
 import {
@@ -31,6 +35,9 @@ import {
   type StateCookieSeed,
 } from "./internal/context.js";
 import type { ThemeConfig } from "../theme/types.js";
+import { isRewrite } from "../route-definition/rewrite.js";
+import { resolveRewriteTarget } from "../rsc/rewrite-passes.js";
+import { getGlobalRouteMap } from "../route-map-builder.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { CacheProfile } from "../cache/profile-registry.js";
 
@@ -94,6 +101,13 @@ export interface RunMiddlewareOptions<TEnv = any> {
   stateCookie?: StateCookieSeed;
 }
 
+/** A rewrite the chain threw (RunMiddlewareResult.rewrite). */
+export interface RunMiddlewareRewrite {
+  pathname: string;
+  search: string;
+  routeName?: string;
+}
+
 /**
  * Result of runMiddleware.
  */
@@ -109,6 +123,16 @@ export interface RunMiddlewareResult<TEnv = any> {
   ctx: RequestContext<TEnv>;
   /** Number of times the terminal handler ran (0 = short-circuited, 1 = passed through). */
   nextCalled: number;
+  /**
+   * The target of a `throw rewrite(...)` from the chain, resolved as
+   * production resolves it (a path basename-prefixed, a route name through
+   * `routeMap`): `pathname` and `search` of the URL the request would render,
+   * and `routeName` when the rewrite named a route. `undefined` when the chain
+   * did not rewrite. On a rewrite, `response` carries what the chain set
+   * before the throw (status, headers, cookies), which production keeps for
+   * the target's response.
+   */
+  rewrite?: RunMiddlewareRewrite;
   /**
    * Whether the chain called `ctx.dynamic()` (the PPR shell opt-out). The public
    * way to assert the opt-out without reading the `@internal` `ctx._dynamic`.
@@ -192,17 +216,37 @@ export async function runMiddleware<TEnv = any>(
       reverse as RequestContext<TEnv>["reverse"];
   }
 
-  const response = await runWithRequestContext(ctx, () =>
-    executeLoaderMiddleware<TEnv>(
-      mwArray,
-      builtRequest,
-      (opts.env ?? {}) as TEnv,
-      opts.params ?? {},
-      variables,
-      finalHandler,
-      reverse,
-    ),
-  );
+  let rewrite: RunMiddlewareRewrite | undefined;
+  const response = await runWithRequestContext(ctx, async () => {
+    try {
+      return await executeLoaderMiddleware<TEnv>(
+        mwArray,
+        builtRequest,
+        (opts.env ?? {}) as TEnv,
+        opts.params ?? {},
+        variables,
+        finalHandler,
+        reverse,
+      );
+    } catch (error) {
+      if (!isRewrite(error)) throw error;
+      const target = resolveRewriteTarget(
+        error,
+        opts.routeMap ?? getGlobalRouteMap(),
+        new URL(builtRequest.url),
+        ctx._basename,
+      );
+      rewrite = {
+        pathname: target.pathname,
+        search: target.search,
+        ...("name" in error.target && { routeName: error.target.name }),
+      };
+      return new Response(null, {
+        status: ctx.res.status,
+        headers: ctx.res.headers,
+      });
+    }
+  });
 
   const { cookies, locationState } = snapshotRunEffects(ctx);
   const headers = headersToObject(response.headers);
@@ -210,6 +254,7 @@ export async function runMiddleware<TEnv = any>(
     response,
     ctx,
     nextCalled,
+    ...(rewrite && { rewrite }),
     dynamic: ctx._dynamic === true,
     cookies,
     headers,

package/src/testing/serve-shell-request.ts

@@ -29,7 +29,8 @@
  *
  * A `Prerender` route serves its handler layer from the artifact
  * `router.matchForPrerender` bakes for the URL (on its first request, kept
- * until resetShellTestState), through the production prerender store. Its
+ * until resetShellTestState), through the production prerender store; an
+ * intercept of it serves from the intercept variant the bake keeps. Its
  * first `ppr` request is a MISS with a runtime capture, as a URL without a
  * build-time shell is in production; build-time shells are e2e-only. An
  * on-demand route (`Prerender(..., { onDemand })`) bakes nothing here: it
@@ -415,10 +416,22 @@ async function servePrerenderArtifacts(
     const { hashParams } = await import("../prerender/param-hash.js");
     baked.add(pathname);
     if (result && !result.passthrough) {
+      const key = `${result.routeName}/${hashParams(result.params)}`;
       payloads.set(
-        `${result.routeName}/${hashParams(result.params)}`,
+        key,
         JSON.stringify({ segments: result.segments, handles: result.handles }),
       );
+      // The intercept variant, keyed and shaped as the build writes it
+      // (vite/discovery/prerender-collection.ts).
+      if (result.interceptSegments?.length) {
+        payloads.set(
+          `${key}/i`,
+          JSON.stringify({
+            segments: [...result.segments, ...result.interceptSegments],
+            handles: result.interceptHandles ?? "",
+          }),
+        );
+      }
     }
   }
   const [{ createPrerenderStore }, { setPrerenderStoreForTests }] =

package/src/thenable-status.ts

@@ -24,3 +24,14 @@ export const SETTLED_THENABLE: Promise<undefined> = Object.assign(
   Promise.resolve(undefined),
   { status: "fulfilled", value: undefined, _debugInfo: [] },
 );
+
+/**
+ * The value React reads from `value` without suspending: `value` itself when
+ * it is not a promise, a promise's `value` once it carries React's or Flight's
+ * `status: "fulfilled"`. Undefined while it is pending or rejected.
+ */
+export function settledValue<T>(value: T | Promise<T>): T | undefined {
+  if (!(value instanceof Promise)) return value;
+  const thenable = value as Promise<T> & { status?: string; value?: T };
+  return thenable.status === "fulfilled" ? thenable.value : undefined;
+}

package/src/types/request-scope.ts

@@ -63,6 +63,14 @@ export interface RequestScope<TEnv = DefaultEnv> {
    */
   originalUrl: URL;
 
+  /**
+   * The visitor's URL (the address bar, search included) when middleware
+   * rewrote this request with `throw rewrite()`; `undefined` otherwise. `url`,
+   * `pathname` and `searchParams` are the rewrite target's. After several
+   * rewrites this is still the first URL. Each context gets its own copy.
+   */
+  rewrittenFrom?: URL;
+
   /** URL pathname (same as `url.pathname`). */
   pathname: string;
 

package/src/vite/discovery/state.ts

@@ -196,28 +196,36 @@ export interface DiscoveryState {
   buildEnvDispose?: (() => Promise<void> | void) | null;
 
   /**
-   * Set when the most recent discovery threw: an HMR re-discovery, or the
-   * cold dev discovery on a main RSC runner. Cleared on the next successful
-   * discovery. While set, the route-file watcher treats any in-scan source
-   * change as a rediscovery trigger (recovery mode).
+   * Set when the most recent dev discovery failed: an HMR re-discovery, or the
+   * cold discovery on the Node RSC runner or the Cloudflare temp runner.
+   * Cleared on the next successful discovery. While set, the route-file
+   * watcher treats any in-scan source change as a rediscovery trigger
+   * (recovery mode).
    */
   lastDiscoveryError?: { message: string; at: number } | null;
 }
 
+/** Record a failed dev discovery (lastDiscoveryError): recovery mode. */
+export function recordDiscoveryFailure(
+  state: Pick<DiscoveryState, "lastDiscoveryError">,
+  err: unknown,
+): void {
+  state.lastDiscoveryError = {
+    message: (err as { message?: string } | null)?.message ?? String(err),
+    at: Date.now(),
+  };
+}
+
 /**
- * Whether the route-file watcher can re-run runtime discovery. A committed
- * manifest is the usual precondition. A failed cold discovery commits none,
- * so on a main RSC runner its recorded failure qualifies too; without that
- * the dev server stayed broken until a restart.
+ * Whether the route-file watcher can re-run runtime discovery: a committed
+ * manifest, or a recorded failure. A failed cold discovery commits none, and
+ * without its recorded failure the dev server stayed broken until a restart,
+ * on the Node runner and on Cloudflare alike.
  */
 export function canRefreshRuntimeDiscovery(
   state: Pick<DiscoveryState, "perRouterManifests" | "lastDiscoveryError">,
-  hasMainRunner: boolean,
 ): boolean {
-  return (
-    state.perRouterManifests.length > 0 ||
-    (hasMainRunner && !!state.lastDiscoveryError)
-  );
+  return state.perRouterManifests.length > 0 || !!state.lastDiscoveryError;
 }
 
 export function createDiscoveryState(

package/src/vite/plugins/expose-internal-ids.ts

@@ -12,6 +12,7 @@ import {
   transformInlineHandlers,
   type VirtualHandlerEntry,
 } from "../utils/ast-handler-extract.js";
+import { isSkippedSourceScanDir } from "../../build/route-types/scan-filter.js";
 
 import type {
   HandlerTransformConfig,
@@ -297,8 +298,6 @@ ${lazyImports.join(",\n")}
 
       const fs = await import("node:fs/promises");
 
-      const SKIP_DIRS = new Set(["node_modules", "dist", "build", "coverage"]);
-
       async function scanDir(dir: string): Promise<string[]> {
         const results: string[] = [];
         try {
@@ -306,7 +305,7 @@ ${lazyImports.join(",\n")}
           for (const entry of entries) {
             const fullPath = path.join(dir, entry.name);
             if (entry.isDirectory()) {
-              if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith(".")) {
+              if (!isSkippedSourceScanDir(entry.name)) {
                 results.push(...(await scanDir(fullPath)));
               }
             } else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) {

package/src/vite/router-discovery.ts

@@ -53,6 +53,7 @@ import { extractHandlerExportsFromChunk } from "./utils/bundle-analysis.js";
 import {
   canRefreshRuntimeDiscovery,
   createDiscoveryState,
+  recordDiscoveryFailure,
   VIRTUAL_ROUTES_MANIFEST_ID,
   type DiscoveryState,
   type PluginOptions,
@@ -1050,12 +1051,20 @@ export function createRouterDiscoveryPlugin(
               acquireBuildEnv(s, viteCommand, viteMode),
             );
 
-            tempRscEnv = (
-              await timed(debugDiscovery, "getOrCreateTempServer", () =>
-                getOrCreateTempServer(),
-              )
-            ).env;
-            if (tempRscEnv) {
+            const temp = await timed(
+              debugDiscovery,
+              "getOrCreateTempServer",
+              () => getOrCreateTempServer(),
+            );
+            tempRscEnv = temp.env;
+            if (!tempRscEnv) {
+              // Recovery mode, as in the catch below. getOrCreateTempServer
+              // already logged why the temp runner failed.
+              recordDiscoveryFailure(
+                s,
+                temp.error ?? "temp runner unavailable for discovery",
+              );
+            } else {
               optimizerHashBefore =
                 tempRscEnv.depsOptimizer?.metadata?.browserHash;
               await timed(debugDiscovery, "discoverRouters (cloudflare)", () =>
@@ -1070,6 +1079,7 @@ export function createRouterDiscoveryPlugin(
               );
             }
           } catch (err: any) {
+            recordDiscoveryFailure(s, err);
             emitDiscoveryFailure(
               err,
               optimizerHashBefore,
@@ -1140,10 +1150,7 @@ export function createRouterDiscoveryPlugin(
         } catch (err: any) {
           // Recovery mode: the next in-scan source change re-runs discovery
           // (canRefreshRuntimeDiscovery) instead of waiting for a restart.
-          s.lastDiscoveryError = {
-            message: err?.message ?? String(err),
-            at: Date.now(),
-          };
+          recordDiscoveryFailure(s, err);
           emitDiscoveryFailure(
             err,
             optimizerHashBefore,
@@ -1744,13 +1751,6 @@ export function createRouterDiscoveryPlugin(
         const refreshRuntimeDiscovery = async () => {
           const rscEnv = (server.environments as any)?.rsc;
           const hasMainRunner = !!rscEnv?.runner;
-          // Cloudflare HMR has no main RSC runner (workerd is a separate
-          // runtime). When we have a populated runtime manifest from cold
-          // start, we can re-discover via the temp Node runner — the same
-          // mechanism getOrCreateTempServer() uses at startup. Without a
-          // populated manifest there's nothing useful to do, so bail
-          // before involving the gate machine at all.
-          if (!hasMainRunner && s.perRouterManifests.length === 0) return;
           let previousRouteShape = routeShapeSignature();
           await gate.runRefreshCycle(async () => {
             const hmrStart = performance.now();
@@ -1770,11 +1770,16 @@ export function createRouterDiscoveryPlugin(
                 // no gen-file import, so no gen write ever invalidates it.
                 if (recoveringColdStart) invalidateRoutesManifestModule(rscEnv);
               } else {
-                // Cloudflare HMR: invalidate the temp server's RSC module
-                // graph (or close+recreate as a fallback) so the runner
-                // re-reads the freshly edited source. Keeping the same
+                // Cloudflare HMR has no main RSC runner (workerd is a separate
+                // runtime): re-discover on the temp Node runner. Invalidate its
+                // RSC module graph (or close+recreate as a fallback) so the
+                // runner re-reads the freshly edited source. Keeping the same
                 // Vite instance alive avoids disrupting workerd's transport
-                // during the first post-cold-start module-fetch window.
+                // during the first post-cold-start module-fetch window. After
+                // a cold start whose temp runner failed there is none, and
+                // getOrCreateTempServer creates one. A recovering cycle needs
+                // no routes-manifest invalidation here: the worker reload below
+                // invalidates its whole module graph.
                 const tempRscEnv = await timed(
                   debugDiscovery,
                   "hmr refreshTempRscEnv (cloudflare)",
@@ -1830,10 +1835,7 @@ export function createRouterDiscoveryPlugin(
                 forceCloudflareWorkerReload(rscEnv, expectedEpoch);
               }
             } catch (err: any) {
-              s.lastDiscoveryError = {
-                message: err?.message ?? String(err),
-                at: Date.now(),
-              };
+              recordDiscoveryFailure(s, err);
               // An invalid transition({ when }) is a definition error the
               // user must see: terminal error plus the browser's Vite overlay,
               // not a warning while the last-good route tree keeps serving.
@@ -2025,7 +2027,7 @@ export function createRouterDiscoveryPlugin(
             // Async: re-run runtime discovery to refresh factory-generated
             // routes that the static parser cannot resolve. Resolves the
             // discovery gate when complete.
-            if (canRefreshRuntimeDiscovery(s, !!rscEnv?.runner)) {
+            if (canRefreshRuntimeDiscovery(s)) {
               // The cloudflare workerd reload fires inside refreshRuntimeDiscovery
               // on the successful cycle (see forceCloudflareWorkerReload call
               // there) so queued follow-up cycles also trigger it.
@@ -2228,7 +2230,7 @@ export function createRouterDiscoveryPlugin(
             // observe a stale resolved gate from cold-start). Resolved
             // by the trailing refreshRuntimeDiscovery() cycle, which runs
             // under the same predicate.
-            if (canRefreshRuntimeDiscovery(s, !!mainRscEnv?.runner)) {
+            if (canRefreshRuntimeDiscovery(s)) {
               gate.noteRouteEvent();
             }
             scheduleRouteRegeneration();