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

package/src/vite/discovery/discover-routers.ts

@@ -11,6 +11,16 @@ import {
   formatNestedRouterConflictError,
   findNestedRouterConflict,
 } from "../../build/generate-route-types.js";
+// Pure data transforms over generateManifestFull's output. Imported directly
+// from source (not the public ./build barrel, and not the runner) because they
+// are realm-independent: buildRouteTrie/buildPerRouterTrie operate on plain
+// manifest data, and collectFallbackClientRefs keys on the global-registry
+// Symbol.for("react.client.reference"), so it detects client references in a
+// boundary tree regardless of which realm imported the walker. Only
+// generateManifestFull must stay on the runner (it invokes user handlers via
+// RangoContext from the runner realm) — see the runner.import below.
+import { buildRouteTrie, buildPerRouterTrie } from "../../build/route-trie.js";
+import { collectFallbackClientRefs } from "../../build/collect-fallback-refs.js";
 import {
   flattenLeafEntries,
   buildRouteToStaticPrefix,
@@ -20,6 +30,15 @@ import {
   expandPrerenderRoutes,
   renderStaticHandlers,
 } from "./prerender-collection.js";
+import {
+  resolveHostRouterHandlers,
+  DiscoveryError,
+  type CaughtDiscoveryError,
+} from "./discovery-errors.js";
+import { createRangoDebugger, timed, NS } from "../debug.js";
+import { computeProductionHash } from "../plugins/client-ref-hashing.js";
+
+const debug = createRangoDebugger(NS.discovery);
 
 /**
  * Import the user's entry via RSC runner, generate manifests for each
@@ -38,41 +57,40 @@ export async function discoverRouters(
   // Import the entry file via RSC environment.
   // For node preset: this is the router file (createRouter() registers in RouterRegistry).
   // For cloudflare preset: this is the worker entry (which imports the router).
-  await rscEnv.runner.import(state.resolvedEntryPath);
+  await timed(debug, "inner: import entry", () =>
+    rscEnv.runner.import(state.resolvedEntryPath),
+  );
 
   // Import the router package to access the registry
-  const serverMod = await rscEnv.runner.import("@rangojs/router/server");
+  const serverMod = await timed(
+    debug,
+    "inner: import @rangojs/router/server",
+    () => rscEnv.runner.import("@rangojs/router/server"),
+  );
   let registry: Map<string, any> = serverMod.RouterRegistry;
 
   if (!registry || registry.size === 0) {
     // No RSC routers found directly. Check for host routers with lazy handlers
     // that need to be resolved to trigger sub-app createRouter() calls.
+    //
+    // Handler failures are collected rather than swallowed: when the registry
+    // is still empty afterwards, these errors (typically a sub-app whose router
+    // module failed to import) are the most likely cause and are surfaced in
+    // the terminal "No routers found" error below.
+    const discoveryErrors: CaughtDiscoveryError[] = [];
     try {
       const hostRegistry: Map<string, any> | undefined =
         serverMod.HostRouterRegistry;
 
       if (hostRegistry && hostRegistry.size > 0) {
         console.log(
-          `[rsc-router] Found ${hostRegistry.size} host router(s), resolving lazy handlers...`,
+          `[rango] Found ${hostRegistry.size} host router(s), resolving lazy handlers...`,
         );
 
-        for (const [, entry] of hostRegistry) {
-          for (const route of entry.routes) {
-            if (typeof route.handler === "function") {
-              try {
-                await route.handler();
-              } catch {
-                // Lazy handler may fail in temp server context, that's OK
-              }
-            }
-          }
-          if (entry.fallback && typeof entry.fallback.handler === "function") {
-            try {
-              await entry.fallback.handler();
-            } catch {
-              // Fallback handler may fail in temp server context
-            }
-          }
+        const handlerErrors = await resolveHostRouterHandlers(hostRegistry);
+        discoveryErrors.push(...handlerErrors);
+        for (const { context, error } of handlerErrors) {
+          debug?.("caught error while resolving %s: %O", context, error);
         }
 
         // Re-read RouterRegistry - sub-app createRouter() calls should have populated it
@@ -87,22 +105,31 @@ export async function discoverRouters(
           registry = freshRegistry;
         }
       }
-    } catch {
-      // Host-router discovery is best-effort; skip if unavailable
+    } catch (error) {
+      // Host-router discovery is best-effort; record the failure so it can be
+      // surfaced if no routers are found.
+      discoveryErrors.push({ context: "host-router discovery", error });
     }
 
     // If still no routers after host router resolution, fail
     if (!registry || registry.size === 0) {
-      throw new Error(
-        `[rsc-router] No routers found in registry after importing ${state.resolvedEntryPath}`,
-      );
+      throw new DiscoveryError(state.resolvedEntryPath, discoveryErrors);
     }
   }
 
-  // Import build utilities for manifest generation
-  const buildMod = await rscEnv.runner.import("@rangojs/router/build");
+  // generateManifestFull must run in the RSC runner realm: it invokes the
+  // user's urlpatterns.handler() via RangoContext, consuming router instances
+  // from the runner. The trie/fallback-ref builders are pure transforms over
+  // its output and are imported directly from source above.
+  const buildMod = await timed(
+    debug,
+    "inner: import @rangojs/router/build",
+    () => rscEnv.runner.import("@rangojs/router/build"),
+  );
   const generateManifestFull = buildMod.generateManifestFull;
 
+  debug?.("inner: found %d router(s) in registry", registry.size);
+
   const nestedRouterConflict = findNestedRouterConflict(
     [...registry.values()]
       .map((router) => router.__sourceFile)
@@ -130,18 +157,55 @@ export async function discoverRouters(
   // Collect all manifests for trie building (avoid re-running generateManifest)
   const allManifests: Array<{ id: string; manifest: any }> = [];
 
+  // Built-in clientChunks context (present only when the built-in strategy is
+  // active). Collect the production hashes of "use client" error/notFound
+  // fallback modules so the strategy can route them into app-fallback.
+  const clientChunkCtx = state.opts?.clientChunkCtx;
+  const collectClientFallbackRef = clientChunkCtx
+    ? (refKey: string) =>
+        clientChunkCtx.fallbackRefs.add(
+          computeProductionHash(state.projectRoot, refKey),
+        )
+    : undefined;
+  // Router-level boundary defaults (`createRouter({ defaultErrorBoundary, ... })`)
+  // are NOT in EntryData, so generateManifestFull's walk misses them. Collect any
+  // "use client" default boundary directly off the router instance. The value is
+  // commonly a handler function wrapping the client boundary in server providers,
+  // so collectFallbackClientRefs invokes + walks the tree. The walker keys on the
+  // global-registry Symbol.for("react.client.reference"), so it detects client
+  // references in a runner-realm boundary tree even when imported here directly.
+  const collectFromBoundaryNode = (node: unknown): void => {
+    if (collectClientFallbackRef) {
+      collectFallbackClientRefs(node, collectClientFallbackRef);
+    }
+  };
+
+  const manifestGenStart = debug ? performance.now() : 0;
   for (const [id, router] of registry) {
     if (!router.urlpatterns || !generateManifestFull) {
       continue;
     }
 
-    const manifest = generateManifestFull(
+    const manifest = await generateManifestFull(
       router.urlpatterns,
       routerMountIndex,
-      router.__basename ? { urlPrefix: router.__basename } : undefined,
+      {
+        ...(router.__basename ? { urlPrefix: router.__basename } : {}),
+        ...(collectClientFallbackRef ? { collectClientFallbackRef } : {}),
+      },
     );
     routerMountIndex++;
     allManifests.push({ id, manifest });
+
+    // Router-level "use client" boundary defaults -> app-fallback (the
+    // route-tree errorBoundary()/notFoundBoundary() helpers are already
+    // collected inside generateManifestFull via collectClientFallbackRef).
+    if (collectClientFallbackRef) {
+      collectFromBoundaryNode(router.__defaultErrorBoundary);
+      collectFromBoundaryNode(router.__defaultNotFoundBoundary);
+      collectFromBoundaryNode(router.__notFound);
+    }
+
     const routeCount = Object.keys(manifest.routeManifest).length;
     const staticRoutes = Object.values(manifest.routeManifest).filter(
       (p: any) => !p.includes(":") && !p.includes("*"),
@@ -193,24 +257,23 @@ export async function discoverRouters(
     // Flatten prefix tree leaf nodes into precomputed entries.
     // Leaf nodes (no children) can have their routes used directly by
     // evaluateLazyEntry() without running the handler at runtime.
+    // Walk once into a per-router array, then fold it into the merged array;
+    // the merged and per-router entries are identical, so a second walk is
+    // redundant. Append order is preserved within and across routers.
+    const routerPrecomputed: PrecomputedEntry[] = [];
     flattenLeafEntries(
       manifest.prefixTree,
       manifest.routeManifest,
-      newMergedPrecomputedEntries,
+      routerPrecomputed,
     );
+    newMergedPrecomputedEntries.push(...routerPrecomputed);
 
     // Store per-router manifest and precomputed entries for isolated virtual modules.
     newPerRouterManifestDataMap.set(id, manifest.routeManifest);
-    const routerPrecomputed: PrecomputedEntry[] = [];
-    flattenLeafEntries(
-      manifest.prefixTree,
-      manifest.routeManifest,
-      routerPrecomputed,
-    );
     newPerRouterPrecomputedMap.set(id, routerPrecomputed);
 
     console.log(
-      `[rsc-router] Router "${id}" -> ${routeCount} routes ` +
+      `[rango] Router "${id}" -> ${routeCount} routes ` +
         `(${staticRoutes} static, ${dynamicRoutes} dynamic)`,
     );
   }
@@ -226,7 +289,7 @@ export async function discoverRouters(
     );
     if (autoIds.length > 1) {
       console.warn(
-        `[rsc-router] WARNING: ${autoIds.length} routers use auto-generated IDs (${autoIds.join(", ")}). ` +
+        `[rango] WARNING: ${autoIds.length} routers use auto-generated IDs (${autoIds.join(", ")}). ` +
           `In multi-router setups, each createRouter() must have an explicit \`id\` option ` +
           `to ensure per-router manifest data is matched correctly at runtime. ` +
           `Example: createRouter({ id: "site", ... })`,
@@ -234,11 +297,17 @@ export async function discoverRouters(
     }
   }
 
+  debug?.(
+    "inner: generated manifests for %d router(s) (%sms)",
+    allManifests.length,
+    (performance.now() - manifestGenStart).toFixed(1),
+  );
+
   // Build route trie from merged manifest + ancestry
   let newMergedRouteTrie: any = null;
+  const trieStart = debug ? performance.now() : 0;
   if (Object.keys(newMergedRouteManifest).length > 0) {
-    const buildRouteTrie = buildMod.buildRouteTrie;
-    if (buildRouteTrie && mergedRouteAncestry) {
+    if (mergedRouteAncestry) {
       // Build routeToStaticPrefix from saved manifests
       const routeToStaticPrefix: Record<string, string> = {};
       for (const { manifest } of allManifests) {
@@ -271,64 +340,36 @@ export async function discoverRouters(
         }
       }
 
+      // buildRouteTrie reads these via ?.has / ?.[] — empty is observationally
+      // identical to undefined, so no empty->undefined coercion is needed.
       newMergedRouteTrie = buildRouteTrie(
         newMergedRouteManifest,
         mergedRouteAncestry,
         routeToStaticPrefix,
-        Object.keys(mergedRouteTrailingSlash).length > 0
-          ? mergedRouteTrailingSlash
-          : undefined,
-        prerenderRouteNames.size > 0 ? prerenderRouteNames : undefined,
-        passthroughRouteNames.size > 0 ? passthroughRouteNames : undefined,
-        Object.keys(mergedResponseTypeRoutes).length > 0
-          ? mergedResponseTypeRoutes
-          : undefined,
+        mergedRouteTrailingSlash,
+        prerenderRouteNames,
+        passthroughRouteNames,
+        mergedResponseTypeRoutes,
       );
 
-      // Build per-router tries for multi-router isolation.
+      // Build per-router tries for multi-router isolation. Uses the single
+      // shared buildPerRouterTrie so the production serialized trie is built by
+      // exactly the same code as the dev/HMR runtime rebuild (manifest-init.ts).
+      // Returns null for route-less manifests (route-trie.ts).
       for (const { id, manifest } of allManifests) {
-        if (
-          !manifest._routeAncestry ||
-          Object.keys(manifest._routeAncestry).length === 0
-        )
-          continue;
-        const perRouterStaticPrefix: Record<string, string> = {};
-        for (const name of Object.keys(manifest.routeManifest)) {
-          perRouterStaticPrefix[name] = "";
+        const perRouterTrie = buildPerRouterTrie(manifest);
+        if (perRouterTrie) {
+          newPerRouterTrieMap.set(id, perRouterTrie);
         }
-        buildRouteToStaticPrefix(manifest.prefixTree, perRouterStaticPrefix);
-
-        const perRouterPrerenderNames = manifest.prerenderRoutes
-          ? new Set<string>(manifest.prerenderRoutes)
-          : undefined;
-        const perRouterPassthroughNames = manifest.passthroughRoutes
-          ? new Set<string>(manifest.passthroughRoutes)
-          : undefined;
-
-        const perRouterTrie = buildRouteTrie(
-          manifest.routeManifest,
-          manifest._routeAncestry,
-          perRouterStaticPrefix,
-          manifest.routeTrailingSlash &&
-            Object.keys(manifest.routeTrailingSlash).length > 0
-            ? manifest.routeTrailingSlash
-            : undefined,
-          perRouterPrerenderNames && perRouterPrerenderNames.size > 0
-            ? perRouterPrerenderNames
-            : undefined,
-          perRouterPassthroughNames && perRouterPassthroughNames.size > 0
-            ? perRouterPassthroughNames
-            : undefined,
-          manifest.responseTypeRoutes &&
-            Object.keys(manifest.responseTypeRoutes).length > 0
-            ? manifest.responseTypeRoutes
-            : undefined,
-        );
-        newPerRouterTrieMap.set(id, perRouterTrie);
       }
     }
   }
 
+  debug?.(
+    "inner: trie build done (%sms)",
+    (performance.now() - trieStart).toFixed(1),
+  );
+
   // Commit all local state to the shared discovery state atomically.
   // This ensures a failed re-discovery (e.g. from a transient module
   // evaluation error) preserves the last known-good state.

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

@@ -0,0 +1,255 @@
+/**
+ * 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);
+  }
+}
+
+/** How the dev caller should surface a discovery failure. */
+export interface DiscoveryFailureReport {
+  level: "error" | "warn";
+  message: string;
+}
+
+/**
+ * Decide how to surface a dev-boot discovery failure in the terminal.
+ *
+ * The bare "no routers found" case (a DiscoveryError with no caught host-handler
+ * failures) is ambiguous. It is either:
+ *   - a genuine misconfiguration — the entry never calls createRouter(), or the
+ *     configured entry path is wrong; or
+ *   - a transient artifact of a Vite dependency re-optimization racing with boot
+ *     discovery (a module read before the entry import resolves to the
+ *     pre-optimize copy of the runner graph while createRouter() populated the
+ *     post-optimize copy — see router-discovery.ts).
+ *
+ * We can only tell them apart when the caller observed the dep optimizer's
+ * `browserHash` change across the discovery attempt (`reoptimizeObserved`): a
+ * reload-causing re-optimization landed mid-flight, so the empty read was
+ * transient and the app self-heals per-request (handler.ts builds the trie from
+ * the router's live urlpatterns) with discovery re-running on the next boot.
+ *
+ * A DiscoveryError that DOES carry caught host-handler failures already embeds
+ * the real cause in its message, and any non-DiscoveryError is a hard failure;
+ * both stay loud with full detail.
+ */
+export function describeDiscoveryFailure(
+  err: unknown,
+  opts: { reoptimizeObserved?: boolean } = {},
+): DiscoveryFailureReport {
+  if (err instanceof DiscoveryError && err.caught.length === 0) {
+    const entry = err.entryPath ?? "the router entry";
+    if (opts.reoptimizeObserved) {
+      return {
+        level: "warn",
+        message:
+          `[rango] No routers found while Vite was re-optimizing dependencies on ` +
+          `dev boot. This is transient: routes are served per-request and ` +
+          `discovery re-runs automatically, so it clears on the next boot. If ` +
+          `routes still 404, confirm ${entry} calls createRouter().`,
+      };
+    }
+    return {
+      level: "error",
+      message:
+        `${err.message}\n` +
+        `  Ensure ${entry} calls createRouter() at module top level and that the ` +
+        `configured router entry path is correct.`,
+    };
+  }
+
+  const e = err as { stack?: string; message?: string };
+  const detail = e?.stack ?? e?.message ?? String(err);
+  return {
+    level: "error",
+    message: `[rango] Router discovery failed: ${detail}`,
+  };
+}