@rangojs/router 0.0.0-experimental.79 → 0.0.0-experimental.7c7e4327

package/src/vite/discovery/gate-state.ts

@@ -0,0 +1,171 @@
+import type { Debugger } from "../debug.js";
+
+/**
+ * Manifest-readiness gate + rediscovery scheduler.
+ *
+ * Owns the four pieces of state that cooperate to keep
+ * `s.discoveryDone` (the promise the manifest virtual module's `load()`
+ * hook awaits) consistent across HMR fan-out:
+ *
+ *   - **gatePending**: a Promise has been issued and not yet resolved.
+ *     Workerd's manifest virtual module load() is blocked on it.
+ *   - **inProgress**: a refresh's work callback is currently executing.
+ *   - **queued**: a refresh was attempted while one was already in
+ *     flight; the active run consumes this in its `finally` and
+ *     recurses.
+ *   - **pendingEvents**: a route-file event has been received (gate
+ *     already reset) but the corresponding refresh's work hasn't started
+ *     yet — i.e. the debounce hasn't fired. Set in `noteRouteEvent`,
+ *     cleared at the start of each refresh cycle. Refresh's finally MUST
+ *     hold the gate if this is true even when `queued` is false,
+ *     otherwise an event whose debounce fires AFTER the active refresh
+ *     completes (the "tail-race" window) would observe a resolved gate.
+ *
+ * The HMR-event flow (cloudflare-stress repro):
+ *
+ *   t=0    Touch 1  → noteRouteEvent  → pendingEvents=true, beginGate
+ *                                      (gate1 pending)
+ *          → debounce 100ms
+ *   t=100  runRefreshCycle(work)      → clear pendingEvents, work starts
+ *   t=750  Touch 2  → noteRouteEvent  → pendingEvents=true (no-op gate)
+ *                                      → debounce fires at t=850
+ *   t=800  refresh A's finally        → queued=false, pendingEvents=true
+ *                                      → HOLD gate (don't resolve)
+ *   t=850  runRefreshCycle (debounce) → clear pendingEvents, work starts
+ *   t=1500 refresh B's finally        → queued=false, pendingEvents=false
+ *                                      → resolveGate (gate1 resolves)
+ *
+ * @internal Exported only for unit tests.
+ */
+export interface DiscoveryGate {
+  /**
+   * Reset the gate to a fresh pending Promise via `s.discoveryDone`.
+   * No-op when a gate is already pending — file watchers can fire
+   * multiple events for one save, and replacing the resolver would
+   * orphan the original promise (workerd's manifest load() would hang).
+   */
+  beginGate(): void;
+  /**
+   * Resolve the current pending gate. No-op when no gate is pending.
+   * Called at the tail of the last refresh cycle in a burst.
+   */
+  resolveGate(): void;
+  /**
+   * Record that a route-file event has arrived. Sets `pendingEvents`
+   * and begins the gate. Idempotent for both flags.
+   */
+  noteRouteEvent(): void;
+  /**
+   * Run one refresh cycle, managing queue + pending state around it.
+   * If a cycle is already in flight, sets `queued=true` and returns.
+   * Otherwise clears `pendingEvents`, runs `work`, and in `finally`:
+   *
+   *   - queued        → recurse, gate stays pending
+   *   - pendingEvents → hold gate (next debounced cycle resolves)
+   *   - neither       → resolveGate
+   */
+  runRefreshCycle(work: () => Promise<void>): Promise<void>;
+  /** Snapshot of internal state. Test-only. */
+  readonly state: () => Readonly<{
+    gatePending: boolean;
+    inProgress: boolean;
+    queued: boolean;
+    pendingEvents: boolean;
+  }>;
+}
+
+/** State container the gate writes `discoveryDone` into. */
+export interface GateOwner {
+  discoveryDone: Promise<void> | null | undefined;
+}
+
+export function createDiscoveryGate(
+  s: GateOwner,
+  debug?: Debugger,
+): DiscoveryGate {
+  let gatePending = false;
+  let gateResolver: () => void = () => {};
+  let inProgress = false;
+  let queued = false;
+  let pendingEvents = false;
+
+  const beginGate = (): void => {
+    if (gatePending) return;
+    s.discoveryDone = new Promise<void>((resolve) => {
+      gateResolver = resolve;
+    });
+    gatePending = true;
+  };
+
+  const resolveGate = (): void => {
+    if (!gatePending) return;
+    // Defer resolution while a refresh cycle is in flight or queued, or
+    // while an unprocessed route-file event is pending its debounce.
+    // Without this guard, cold-start's `discover().then(resolveGate)`
+    // could fire while an HMR-triggered runRefreshCycle is mid-flight,
+    // prematurely unblocking workerd's manifest load() against the
+    // stale cold-start gen. The active cycle's `finally` calls
+    // resolveGate again at the tail and finishes the resolution then.
+    if (inProgress || queued || pendingEvents) {
+      debug?.(
+        "hmr: resolveGate deferred — work in flight (inProgress=%s queued=%s pendingEvents=%s)",
+        inProgress,
+        queued,
+        pendingEvents,
+      );
+      return;
+    }
+    gatePending = false;
+    debug?.("hmr: discoveryDone resolved");
+    gateResolver();
+  };
+
+  const noteRouteEvent = (): void => {
+    pendingEvents = true;
+    beginGate();
+  };
+
+  const runRefreshCycle = async (work: () => Promise<void>): Promise<void> => {
+    if (inProgress) {
+      queued = true;
+      debug?.("hmr: rediscovery in flight — queued for a follow-up cycle");
+      return;
+    }
+    // Snapshot the current pendingEvents into "we're about to process";
+    // events arriving from now on re-set it.
+    pendingEvents = false;
+    inProgress = true;
+    try {
+      await work();
+    } finally {
+      inProgress = false;
+      if (queued) {
+        queued = false;
+        debug?.("hmr: consuming queued rediscovery");
+        runRefreshCycle(work).catch((err: unknown) => {
+          debug?.(
+            "hmr: queued cycle rejected — releasing gate (%s)",
+            err instanceof Error ? err.message : String(err),
+          );
+          // Belt-and-suspenders: even if the queued cycle's own try/catch
+          // missed something, ensure workerd doesn't hang.
+          resolveGate();
+        });
+      } else if (pendingEvents) {
+        debug?.(
+          "hmr: holding gate for pending events (debounce not yet fired)",
+        );
+      } else {
+        resolveGate();
+      }
+    }
+  };
+
+  return {
+    beginGate,
+    resolveGate,
+    noteRouteEvent,
+    runRefreshCycle,
+    state: () => ({ gatePending, inProgress, queued, pendingEvents }),
+  };
+}

package/src/vite/discovery/prerender-collection.ts

@@ -6,16 +6,20 @@
  * generation.
  */
 
-import { contextSet } from "../../context-var.js";
+import { contextSet, hasContextVars } from "../../context-var.js";
 import {
   encodePathParam,
   substituteRouteParams,
   runWithConcurrency,
   groupByConcurrency,
   notifyOnError,
+  resolvePrerenderError,
   stageBuildAssetModule,
 } from "../utils/prerender-utils.js";
 import type { DiscoveryState } from "./state.js";
+import { createRangoDebugger, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.prerender);
 
 /**
  * Expand prerender routes into concrete URLs and render them via the
@@ -30,6 +34,12 @@ export async function expandPrerenderRoutes(
 ): Promise<void> {
   if (!state.opts?.enableBuildPrerender || !state.isBuildMode) return;
 
+  const overallStart = debug ? performance.now() : 0;
+  debug?.(
+    "expandPrerenderRoutes: start (%d router manifest(s))",
+    allManifests.length,
+  );
+
   type PrerenderEntry = {
     urlPath: string;
     routeName: string;
@@ -72,7 +82,7 @@ export async function expandPrerenderRoutes(
       ? setInterval(() => {
           const elapsed = ((performance.now() - paramsStart) / 1000).toFixed(1);
           console.log(
-            `[rsc-router] Resolving prerender params... ${resolvedRoutes}/${totalDynamic} routes (${elapsed}s)`,
+            `[rango] Resolving prerender params... ${resolvedRoutes}/${totalDynamic} routes (${elapsed}s)`,
           );
         }, 5000)
       : undefined;
@@ -99,6 +109,7 @@ export async function expandPrerenderRoutes(
         } else {
           // Dynamic route: call getParams() to enumerate param combinations
           if (def?.getParams) {
+            const getParamsStart = debug ? performance.now() : 0;
             try {
               const buildVars: Record<string, any> = {};
               const buildEnv = state.resolvedBuildEnv;
@@ -112,16 +123,20 @@ export async function expandPrerenderRoutes(
                 get env() {
                   if (buildEnv !== undefined) return buildEnv;
                   throw new Error(
-                    "[rsc-router] ctx.env is not available during build-time getParams(). " +
+                    "[rango] ctx.env is not available during build-time getParams(). " +
                       "Configure buildEnv in your rango() plugin options to enable build-time env access.",
                   );
                 },
               };
               const paramsList = await def.getParams(getParamsCtx);
+              debug?.(
+                "getParams %s -> %d params (%sms)",
+                routeName,
+                paramsList.length,
+                (performance.now() - getParamsStart).toFixed(1),
+              );
               const concurrency = def.options?.concurrency ?? 1;
-              const hasBuildVars =
-                Object.keys(buildVars).length > 0 ||
-                Object.getOwnPropertySymbols(buildVars).length > 0;
+              const hasBuildVars = hasContextVars(buildVars);
               for (const params of paramsList) {
                 let url = substituteRouteParams(
                   pattern,
@@ -154,7 +169,7 @@ export async function expandPrerenderRoutes(
               // Skip in getParams() skips the entire route
               if (err.name === "Skip") {
                 console.log(
-                  `[rsc-router]   SKIP route "${routeName}" - ${err.message}`,
+                  `[rango]   SKIP route "${routeName}" - ${err.message}`,
                 );
                 notifyOnError(
                   registry,
@@ -168,14 +183,14 @@ export async function expandPrerenderRoutes(
               }
               // Regular error: fail the build
               console.error(
-                `[rsc-router] Failed to get params for prerender route "${routeName}": ${err.message}`,
+                `[rango] Failed to get params for prerender route "${routeName}": ${err.message}`,
               );
               notifyOnError(registry, err, "prerender", routeName);
               throw err;
             }
           } else {
             console.warn(
-              `[rsc-router] Dynamic prerender route "${routeName}" has no getParams(), skipping`,
+              `[rango] Dynamic prerender route "${routeName}" has no getParams(), skipping`,
             );
           }
         }
@@ -186,19 +201,30 @@ export async function expandPrerenderRoutes(
       clearInterval(progressInterval);
       const elapsed = ((performance.now() - paramsStart) / 1000).toFixed(1);
       console.log(
-        `[rsc-router] Resolved prerender params: ${resolvedRoutes}/${totalDynamic} routes (${elapsed}s)`,
+        `[rango] Resolved prerender params: ${resolvedRoutes}/${totalDynamic} routes (${elapsed}s)`,
       );
     }
   }
 
-  if (entries.length === 0) return;
+  if (entries.length === 0) {
+    debug?.(
+      "no prerender entries (done in %sms)",
+      (performance.now() - overallStart).toFixed(1),
+    );
+    return;
+  }
 
   // Determine the max concurrency for the log header
   const maxConcurrency = Math.max(...entries.map((e) => e.concurrency));
   const concurrencyNote =
     maxConcurrency > 1 ? ` (concurrency: ${maxConcurrency})` : "";
   console.log(
-    `[rsc-router] Pre-rendering ${entries.length} URL(s)${concurrencyNote}...`,
+    `[rango] Pre-rendering ${entries.length} URL(s)${concurrencyNote}...`,
+  );
+  debug?.(
+    "prerender loop: %d entries, max concurrency %d",
+    entries.length,
+    maxConcurrency,
   );
 
   const { hashParams } = await rscEnv.runner.import("@rangojs/router/build");
@@ -206,6 +232,10 @@ export async function expandPrerenderRoutes(
   const manifestEntries: Record<string, string> = {};
   let doneCount = 0;
   let skipCount = 0;
+  // #587: a render error reaches here (matchForPrerender now re-throws it rather
+  // than baking the error boundary). Default "fail" fails the build; "warn" logs
+  // and skips baking the URL.
+  const prerenderOnError = state.opts?.prerenderOnError ?? "fail";
   const startTotal = performance.now();
 
   // Group entries by concurrency for batched rendering.
@@ -234,7 +264,7 @@ export async function expandPrerenderRoutes(
             if (result.passthrough) {
               const elapsed = (performance.now() - startUrl).toFixed(0);
               console.log(
-                `[rsc-router]   PASS ${entry.urlPath.padEnd(40)} (${elapsed}ms) - live fallback`,
+                `[rango]   PASS ${entry.urlPath.padEnd(40)} (${elapsed}ms) - live fallback`,
               );
               doneCount++;
               break;
@@ -255,10 +285,9 @@ export async function expandPrerenderRoutes(
               const interceptKey = `${result.routeName}/${paramHash}/i`;
               const interceptValue = JSON.stringify({
                 segments: [...result.segments, ...result.interceptSegments],
-                handles: {
-                  ...result.handles,
-                  ...(result.interceptHandles || {}),
-                },
+                // interceptHandles is the pre-encoded MERGED (main + intercept)
+                // handle string (the producer merged before encoding).
+                handles: result.interceptHandles ?? "",
               });
               manifestEntries[interceptKey] = stageBuildAssetModule(
                 state.projectRoot,
@@ -268,40 +297,27 @@ export async function expandPrerenderRoutes(
             }
             const elapsed = (performance.now() - startUrl).toFixed(0);
             console.log(
-              `[rsc-router]   OK   ${entry.urlPath.padEnd(40)} (${elapsed}ms)`,
+              `[rango]   OK   ${entry.urlPath.padEnd(40)} (${elapsed}ms)`,
             );
             doneCount++;
             break;
           } catch (err: any) {
-            if (err.name === "Skip") {
-              const elapsed = (performance.now() - startUrl).toFixed(0);
-              console.log(
-                `[rsc-router]   SKIP ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
-              );
-              skipCount++;
-              notifyOnError(
-                registry,
-                err,
-                "prerender",
-                entry.routeName,
-                entry.urlPath,
-                true,
-              );
-              break;
-            }
-            // Regular error: log, notify, and fail the build
+            // Skip, or a render error under prerender.onError "warn": skip the
+            // URL (never bake the error page, #587). A render error under the
+            // default "fail" re-throws below to fail the build.
             const elapsed = (performance.now() - startUrl).toFixed(0);
-            console.error(
-              `[rsc-router]   FAIL ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
-            );
-            notifyOnError(
+            resolvePrerenderError(
               registry,
               err,
+              prerenderOnError,
+              entry.urlPath.padEnd(40),
+              elapsed,
               "prerender",
               entry.routeName,
               entry.urlPath,
             );
-            throw err;
+            skipCount++;
+            break;
           }
         }
       },
@@ -315,7 +331,14 @@ export async function expandPrerenderRoutes(
   const parts = [`${doneCount} done`];
   if (skipCount > 0) parts.push(`${skipCount} skipped`);
   console.log(
-    `[rsc-router] Pre-render complete: ${parts.join(", ")} (${totalElapsed}ms total)`,
+    `[rango] Pre-render complete: ${parts.join(", ")} (${totalElapsed}ms total)`,
+  );
+  debug?.(
+    "expandPrerenderRoutes done: %d done, %d skipped, %sms (overall %sms)",
+    doneCount,
+    skipCount,
+    totalElapsed,
+    (performance.now() - overallStart).toFixed(1),
   );
 }
 
@@ -337,19 +360,24 @@ export async function renderStaticHandlers(
   )
     return;
 
+  const overallStart = debug ? performance.now() : 0;
+  debug?.(
+    "renderStaticHandlers: start (%d static module(s))",
+    state.resolvedStaticModules.size,
+  );
+
   const manifestEntries: Record<string, string> = {};
   let staticDone = 0;
   let staticSkip = 0;
   let totalStaticCount = 0;
+  const prerenderOnError = state.opts?.prerenderOnError ?? "fail";
 
   // Count handlers for the log header
   for (const [, exportNames] of state.resolvedStaticModules) {
     totalStaticCount += exportNames.length;
   }
   const startStatic = performance.now();
-  console.log(
-    `[rsc-router] Rendering ${totalStaticCount} static handler(s)...`,
-  );
+  console.log(`[rango] Rendering ${totalStaticCount} static handler(s)...`);
 
   for (const [moduleId, exportNames] of state.resolvedStaticModules) {
     let mod: any;
@@ -357,7 +385,7 @@ export async function renderStaticHandlers(
       mod = await rscEnv!.runner.import(moduleId);
     } catch (err: any) {
       console.error(
-        `[rsc-router] Failed to import static module ${moduleId}: ${err.message}`,
+        `[rango] Failed to import static module ${moduleId}: ${err.message}`,
       );
       notifyOnError(registry, err, "static");
       throw err;
@@ -382,7 +410,8 @@ export async function renderStaticHandlers(
             !state.isBuildMode,
           );
           if (result) {
-            const hasHandles = Object.keys(result.handles).length > 0;
+            // result.handles is the pre-encoded handle string ("" when none).
+            const hasHandles = result.handles !== "";
             const exportValue = hasHandles
               ? JSON.stringify(result)
               : JSON.stringify(result.encoded);
@@ -392,37 +421,29 @@ export async function renderStaticHandlers(
               exportValue,
             );
             const elapsed = (performance.now() - startHandler).toFixed(0);
-            console.log(
-              `[rsc-router]   OK   ${name.padEnd(40)} (${elapsed}ms)`,
-            );
+            console.log(`[rango]   OK   ${name.padEnd(40)} (${elapsed}ms)`);
             staticDone++;
             handled = true;
             break;
           }
         } catch (err: any) {
-          if (err.name === "Skip") {
-            const elapsed = (performance.now() - startHandler).toFixed(0);
-            console.log(
-              `[rsc-router]   SKIP ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
-            );
-            staticSkip++;
-            notifyOnError(registry, err, "static", undefined, undefined, true);
-            handled = true;
-            break;
-          }
-          // Regular error: log, notify, and fail the build
+          // Same Skip/warn/fail policy as the prerender loop (shared helper).
           const elapsed = (performance.now() - startHandler).toFixed(0);
-          console.error(
-            `[rsc-router]   FAIL ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+          resolvePrerenderError(
+            registry,
+            err,
+            prerenderOnError,
+            name.padEnd(40),
+            elapsed,
+            "static",
           );
-          notifyOnError(registry, err, "static");
-          throw err;
+          staticSkip++;
+          handled = true;
+          break;
         }
       }
       if (!handled) {
-        console.warn(
-          `[rsc-router] No router could render static handler "${name}"`,
-        );
+        console.warn(`[rango] No router could render static handler "${name}"`);
       }
     }
   }
@@ -434,6 +455,13 @@ export async function renderStaticHandlers(
   const staticParts = [`${staticDone} done`];
   if (staticSkip > 0) staticParts.push(`${staticSkip} skipped`);
   console.log(
-    `[rsc-router] Static render complete: ${staticParts.join(", ")} (${totalStaticElapsed}ms total)`,
+    `[rango] Static render complete: ${staticParts.join(", ")} (${totalStaticElapsed}ms total)`,
+  );
+  debug?.(
+    "renderStaticHandlers done: %d done, %d skipped, %sms (overall %sms)",
+    staticDone,
+    staticSkip,
+    totalStaticElapsed,
+    (performance.now() - overallStart).toFixed(1),
   );
 }