@rangojs/router 0.0.0-experimental.d7eeaa75 → 0.0.0-experimental.d98a8e9d

package/src/vite/discovery/discovery-errors.ts

@@ -0,0 +1,194 @@
+/**
+ * Router discovery error aggregation.
+ *
+ * During host-router discovery the lazy mounts registered by a host router are
+ * invoked to trigger each sub-app's createRouter() registration. Some mount
+ * failures are expected in the temporary discovery server context (a sub-app may
+ * reference runtime-only bindings), so each is invoked defensively and its error
+ * is collected rather than thrown.
+ *
+ * Previously these errors were discarded with an empty `catch {}`. When a real
+ * failure - typically a sub-app whose router module fails to import - left the
+ * registry empty, discovery reported the misleading "No routers found" message
+ * with no trace of the underlying cause. The collected errors are now surfaced
+ * via the `DiscoveryError` thrown at the end of discovery (issue #499).
+ *
+ * Which entries to invoke is taken from the consumer's declared intent, not
+ * inferred from the function's shape. A host route is registered either with
+ * `.map((request) => Response)` (an inline request handler, `kind: "handler"`)
+ * or `.lazy(() => import("./sub-app"))` (a lazy mount, `kind: "lazy"`). Only
+ * `kind === "lazy"` entries are invoked here; inline handlers are never invoked
+ * during discovery (they need a Request and register no routers). Because a lazy
+ * entry is known to be a module loader, ANY failure it produces - a synchronous
+ * throw or a rejected promise - is a genuine discovery failure and is collected.
+ */
+
+/** An error caught (and previously swallowed) while resolving host routers. */
+export interface CaughtDiscoveryError {
+  /** Human-readable description of where the error was caught. */
+  context: string;
+  /** The caught value (an Error or otherwise). */
+  error: unknown;
+}
+
+/**
+ * Minimal shape of a host registry entry needed for mount resolution.
+ * Mirrors the runtime HostRouterRegistry value without coupling to its type.
+ */
+interface HostRegistryRoute {
+  handler?: unknown;
+  kind?: string;
+}
+interface HostRegistryEntry {
+  routes: HostRegistryRoute[];
+  fallback?: HostRegistryRoute | null;
+}
+
+/** Indent every non-empty line of `text` by `pad`. */
+function indent(text: string, pad: string): string {
+  return text
+    .split("\n")
+    .map((line) => (line.length > 0 ? pad + line : line))
+    .join("\n");
+}
+
+/**
+ * Invoke a single lazy mount to trigger its sub-app import (and createRouter()
+ * registration), collecting any failure under `context`. The entry is known to
+ * be a loader (`kind === "lazy"`), so both a synchronous throw and a rejected
+ * promise are genuine failures - no shape heuristics are needed.
+ */
+async function invokeLazyMount(
+  loader: () => unknown,
+  context: string,
+  errors: CaughtDiscoveryError[],
+): Promise<void> {
+  try {
+    await loader();
+  } catch (error) {
+    errors.push({ context, error });
+  }
+}
+
+/** Whether a registry route is a `.lazy()` mount with an invokable loader. */
+function isLazyMount(
+  route: HostRegistryRoute | null | undefined,
+): route is { handler: () => unknown; kind: "lazy" } {
+  return (
+    !!route && route.kind === "lazy" && typeof route.handler === "function"
+  );
+}
+
+/**
+ * Invoke every lazy mount in the host registry to trigger sub-app
+ * createRouter() registration, collecting (not throwing) any failures.
+ *
+ * Only `.lazy()` entries are invoked; `.map()` inline request handlers are
+ * skipped (they need a Request and register no routers). Failures are returned
+ * rather than thrown because some mounts legitimately fail in the temporary
+ * discovery server context; the caller decides whether the failures matter,
+ * which is only when discovery finds no routers at all.
+ */
+export async function resolveHostRouterHandlers(
+  hostRegistry: Map<string, HostRegistryEntry>,
+): Promise<CaughtDiscoveryError[]> {
+  const errors: CaughtDiscoveryError[] = [];
+
+  for (const [hostId, entry] of hostRegistry) {
+    for (const route of entry.routes) {
+      if (isLazyMount(route)) {
+        await invokeLazyMount(
+          route.handler,
+          `host "${hostId}" route handler`,
+          errors,
+        );
+      }
+    }
+    if (isLazyMount(entry.fallback)) {
+      await invokeLazyMount(
+        entry.fallback.handler,
+        `host "${hostId}" fallback handler`,
+        errors,
+      );
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Build the terminal "No routers found" message, appending any errors caught
+ * during host-router discovery so the real cause is visible.
+ *
+ * The aggregated errors are inlined into the message (in addition to being
+ * attached via `cause` on `DiscoveryError`) so they survive every caller: the
+ * dev/HMR paths log `err.message`, and the build path re-throws using
+ * `err.stack`, which begins with the message. None of those callers traverse
+ * `cause`, so the message must carry the detail. Each error includes its stack
+ * when available.
+ */
+export function formatNoRoutersError(
+  entryPath: string | undefined,
+  errors: CaughtDiscoveryError[],
+): string {
+  const base = `[rango] No routers found in registry after importing ${entryPath}`;
+  if (errors.length === 0) {
+    return base;
+  }
+
+  const formatted = errors
+    .map(({ context, error }) => {
+      const err = error instanceof Error ? error : new Error(String(error));
+      const detail = err.stack ?? err.message;
+      return `  - while resolving ${context}:\n${indent(detail, "      ")}`;
+    })
+    .join("\n");
+
+  return (
+    `${base}\n\n` +
+    `${errors.length} error(s) were caught during host-router discovery and ` +
+    `likely explain why no routers were registered:\n${formatted}`
+  );
+}
+
+/**
+ * Reduce the caught errors to an `ErrorOptions.cause`: a single failure becomes
+ * the direct cause; multiple failures are wrapped in an `AggregateError` so
+ * each underlying error remains reachable. No errors -> no cause.
+ */
+function toCause(errors: CaughtDiscoveryError[]): unknown {
+  if (errors.length === 0) return undefined;
+  if (errors.length === 1) return errors[0].error;
+  return new AggregateError(
+    errors.map((e) => e.error),
+    "Multiple host-router handlers failed during discovery",
+  );
+}
+
+/**
+ * Thrown when router discovery completes without finding any routers.
+ *
+ * Carries the entry path and the individual failures caught while resolving
+ * host-router lazy handlers. The formatted detail is embedded in `message` (for
+ * callers that log `err.message`/`err.stack`) and the underlying error(s) are
+ * also attached via `cause` (a single failure directly, multiple wrapped in an
+ * `AggregateError`) for cause-aware tooling such as the Vite error overlay.
+ */
+export class DiscoveryError extends Error {
+  /** The entry file that was imported before discovery gave up. */
+  readonly entryPath: string | undefined;
+  /** Individual failures caught while resolving host-router handlers. */
+  readonly caught: CaughtDiscoveryError[];
+
+  constructor(entryPath: string | undefined, caught: CaughtDiscoveryError[]) {
+    super(formatNoRoutersError(entryPath, caught));
+    const cause = toCause(caught);
+    if (cause !== undefined) {
+      this.cause = cause;
+    }
+    this.name = "DiscoveryError";
+    this.entryPath = entryPath;
+    this.caught = caught;
+    Object.setPrototypeOf(this, DiscoveryError.prototype);
+  }
+}

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

@@ -16,6 +16,9 @@ import {
   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 +33,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 +81,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 +108,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,12 +122,18 @@ 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 ||
@@ -154,7 +170,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 +184,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 +202,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");
@@ -234,7 +261,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;
@@ -268,7 +295,7 @@ 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;
@@ -276,7 +303,7 @@ export async function expandPrerenderRoutes(
             if (err.name === "Skip") {
               const elapsed = (performance.now() - startUrl).toFixed(0);
               console.log(
-                `[rsc-router]   SKIP ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+                `[rango]   SKIP ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
               );
               skipCount++;
               notifyOnError(
@@ -292,7 +319,7 @@ export async function expandPrerenderRoutes(
             // Regular error: log, notify, and fail the build
             const elapsed = (performance.now() - startUrl).toFixed(0);
             console.error(
-              `[rsc-router]   FAIL ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+              `[rango]   FAIL ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
             );
             notifyOnError(
               registry,
@@ -315,7 +342,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,6 +371,12 @@ 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;
@@ -347,9 +387,7 @@ export async function renderStaticHandlers(
     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 +395,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;
@@ -392,9 +430,7 @@ 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;
@@ -403,7 +439,7 @@ export async function renderStaticHandlers(
           if (err.name === "Skip") {
             const elapsed = (performance.now() - startHandler).toFixed(0);
             console.log(
-              `[rsc-router]   SKIP ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+              `[rango]   SKIP ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
             );
             staticSkip++;
             notifyOnError(registry, err, "static", undefined, undefined, true);
@@ -413,16 +449,14 @@ export async function renderStaticHandlers(
           // Regular error: log, notify, and fail the build
           const elapsed = (performance.now() - startHandler).toFixed(0);
           console.error(
-            `[rsc-router]   FAIL ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+            `[rango]   FAIL ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
           );
           notifyOnError(registry, err, "static");
           throw err;
         }
       }
       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 +468,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),
   );
 }