@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/vite/discovery/dev-prerender-cache.ts

@@ -0,0 +1,117 @@
+/**
+ * Dev prerender result cache — memoizes /__rsc_prerender responses between
+ * HMR edits (issue #654).
+ *
+ * Freshness invariant (why identity keying is correct): the endpoint
+ * re-imports the user's entry module through a Vite module runner on every
+ * request. When ANY module in the entry → router → urls → handler chain was
+ * invalidated (file edit propagates up the importer graph), that import
+ * re-executes the entry, `createRouter()` re-runs, and `RouterRegistry.set`
+ * (router.ts) replaces the router instance with a NEW object. When nothing
+ * was invalidated, the import is a module-cache hit and the instance is the
+ * SAME object. Router-instance identity therefore IS the HMR generation:
+ * keying the cache on it gives "serve cached until an edit invalidates the
+ * chain" without any watcher bookkeeping, and the WeakMap lets every stale
+ * generation's bucket be garbage-collected the moment the registry drops
+ * the old instance.
+ *
+ * Staleness envelope: a cached body can only go stale through NON-module
+ * inputs (a getParams() reading a database, fs content outside the module
+ * graph). Production freezes those at build time, so serving them frozen
+ * between edits makes dev MORE faithful to production, not less — the
+ * pre-#654 behavior of re-rendering per request was the anomaly.
+ */
+
+import type { SerializedSegmentData } from "../../cache/types.js";
+
+/** Structural slice of `matchForPrerender`'s result the payload derivation needs. */
+export interface DevPrerenderMatchPayloadSource {
+  segments: SerializedSegmentData[];
+  handles: string;
+  interceptSegments?: SerializedSegmentData[];
+  interceptHandles?: string;
+}
+
+/** Serialized response bodies for the two endpoint variants of one render. */
+export interface DevPrerenderPayloadBodies {
+  /** `intercept != 1` response: the route's own segments + handles. */
+  main: string;
+  /**
+   * `intercept=1` response: main + intercept segments with the MERGED handle
+   * string. Falls back to `main` byte-for-byte when the route has no
+   * intercept segments — mirroring the endpoint's historical behavior.
+   */
+  intercept: string;
+}
+
+export interface DevPrerenderCache {
+  get(router: object, key: string): string | undefined;
+  set(router: object, key: string, body: string): void;
+}
+
+/**
+ * Derive both variant bodies from one matchForPrerender result, so a single
+ * render warms the main AND intercept cache keys (matchForPrerender computes
+ * intercept segments unconditionally either way — see prerender-match.ts
+ * step 14).
+ */
+export function payloadBodiesFromResult(
+  result: DevPrerenderMatchPayloadSource,
+): DevPrerenderPayloadBodies {
+  const main = JSON.stringify({
+    segments: result.segments,
+    handles: result.handles,
+  });
+  const intercept = result.interceptSegments?.length
+    ? JSON.stringify({
+        segments: [...result.segments, ...result.interceptSegments],
+        handles: result.interceptHandles ?? "",
+      })
+    : main;
+  return { main, intercept };
+}
+
+/**
+ * Cache key for one endpoint request shape. `pathname` and `routeName` come
+ * straight from the query; `passthrough` selects the getParams-checked match
+ * path; `intercept` selects which variant body is served. All four dimensions
+ * change the response, so all four are in the key.
+ */
+export function devPrerenderCacheKey(
+  pathname: string,
+  opts: { intercept: boolean; passthrough: boolean; routeName: string | null },
+): string {
+  return `${pathname}|i=${opts.intercept ? 1 : 0}|p=${opts.passthrough ? 1 : 0}|r=${opts.routeName ?? ""}`;
+}
+
+/**
+ * Per-router FIFO cap: a dev session that visits an unbounded set of
+ * prerendered pathnames (e.g. crawling param routes) must not grow one
+ * bucket without limit. 500 rendered payloads is far beyond any interactive
+ * session; eviction order does not matter for correctness (a miss just
+ * re-renders).
+ */
+const MAX_ENTRIES_PER_ROUTER = 500;
+
+export function createDevPrerenderCache(
+  maxEntriesPerRouter: number = MAX_ENTRIES_PER_ROUTER,
+): DevPrerenderCache {
+  const buckets = new WeakMap<object, Map<string, string>>();
+  return {
+    get(router: object, key: string): string | undefined {
+      return buckets.get(router)?.get(key);
+    },
+    set(router: object, key: string, body: string): void {
+      let bucket = buckets.get(router);
+      if (!bucket) {
+        bucket = new Map();
+        buckets.set(router, bucket);
+      }
+      if (!bucket.has(key) && bucket.size >= maxEntriesPerRouter) {
+        const oldest = bucket.keys().next().value;
+        if (oldest !== undefined) bucket.delete(oldest);
+      }
+      bucket.set(key, body);
+    },
+  };
+}

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

@@ -11,15 +11,36 @@ import {
   formatNestedRouterConflictError,
   findNestedRouterConflict,
 } from "../../build/generate-route-types.js";
-import {
-  flattenLeafEntries,
-  buildRouteToStaticPrefix,
-} from "../utils/manifest-utils.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 { buildPerRouterTrie } from "../../build/route-trie.js";
+import { collectFallbackClientRefs } from "../../build/collect-fallback-refs.js";
+import { mergeFullManifests } from "../../build/merge-full-manifests.js";
+import { flattenLeafEntries } from "../utils/manifest-utils.js";
 import type { DiscoveryState, PrecomputedEntry } from "./state.js";
 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";
+import {
+  discoverClientUrlProjections,
+  refreshRecordedClientUrlProjections,
+} from "./client-urls-projection.js";
+
+const debug = createRangoDebugger(NS.discovery);
 
 /**
  * Import the user's entry via RSC runner, generate manifests for each
@@ -32,47 +53,56 @@ import {
 export async function discoverRouters(
   state: DiscoveryState,
   rscEnv: any,
+  ssrEnv?: any,
 ): Promise<any> {
   if (!state.resolvedEntryPath) return;
 
+  // Import the router package FIRST (leaf module, no side effects on user
+  // code) so recorded clientUrls projections can be refreshed BEFORE the entry
+  // import: routers re-created by that import call `.routes(reference)` at
+  // module scope and materialize whatever projection is installed at that
+  // moment. On HMR re-discovery that must be the CURRENT module contents, not
+  // the previous pass's snapshot (see refreshRecordedClientUrlProjections).
+  const serverMod = await timed(
+    debug,
+    "inner: import @rangojs/router/server",
+    () => rscEnv.runner.import("@rangojs/router/server"),
+  );
+  await timed(debug, "inner: refresh recorded client URL projections", () =>
+    refreshRecordedClientUrlProjections(state, ssrEnv, serverMod),
+  );
+
   // 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");
   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 +117,35 @@ 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");
+  await timed(debug, "inner: discover client URL projections", () =>
+    discoverClientUrlProjections(state, ssrEnv, serverMod),
+  );
+
+  // 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)
@@ -118,30 +161,72 @@ export async function discoverRouters(
   // full pass succeeds, so a failed re-discovery preserves the last
   // known-good state instead of leaving it partially wiped.
   const newMergedRouteManifest: Record<string, string> = {};
-  const newMergedPrecomputedEntries: PrecomputedEntry[] = [];
   const newPerRouterManifests: typeof state.perRouterManifests = [];
   const newPerRouterManifestDataMap = new Map<string, any>();
   const newPerRouterPrecomputedMap = new Map<string, PrecomputedEntry[]>();
   const newPerRouterTrieMap = new Map<string, any>();
-  let mergedRouteAncestry: Record<string, string[]> = {};
-  let mergedRouteTrailingSlash: Record<string, string> = {};
 
   let routerMountIndex = 0;
   // 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) {
+    if (!generateManifestFull) {
       continue;
     }
 
-    const manifest = generateManifestFull(
-      router.urlpatterns,
-      routerMountIndex,
-      router.__basename ? { urlPrefix: router.__basename } : undefined,
-    );
-    routerMountIndex++;
+    const mounts =
+      router.__urlpatternMounts ??
+      (router.urlpatterns ? [{ patterns: router.urlpatterns }] : []);
+    if (mounts.length === 0) continue;
+
+    const mountManifests = [];
+    for (const mount of mounts) {
+      mountManifests.push(
+        await generateManifestFull(mount.patterns, routerMountIndex, {
+          routerId: id,
+          ...(router.__basename ? { urlPrefix: router.__basename } : {}),
+          ...(collectClientFallbackRef ? { collectClientFallbackRef } : {}),
+        }),
+      );
+      routerMountIndex++;
+    }
+    const manifest = mergeFullManifests(mountManifests);
     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("*"),
@@ -176,41 +261,28 @@ export async function discoverRouters(
     newPerRouterManifests.push({
       id,
       routeManifest: manifest.routeManifest,
+      routeTrailingSlash: manifest.routeTrailingSlash,
       routeSearchSchemas: manifest.routeSearchSchemas,
       sourceFile: router.__sourceFile,
       factoryOnlyPrefixes,
     });
 
-    // Merge ancestry (internal field, used only for trie building)
-    if (manifest._routeAncestry) {
-      Object.assign(mergedRouteAncestry, manifest._routeAncestry);
-    }
-    // Merge trailing slash config
-    if (manifest.routeTrailingSlash) {
-      Object.assign(mergedRouteTrailingSlash, manifest.routeTrailingSlash);
-    }
-
     // 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.
+    const routerPrecomputed: PrecomputedEntry[] = [];
     flattenLeafEntries(
       manifest.prefixTree,
       manifest.routeManifest,
-      newMergedPrecomputedEntries,
+      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 +298,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,111 +306,66 @@ export async function discoverRouters(
     }
   }
 
-  // Build route trie from merged manifest + ancestry
-  let newMergedRouteTrie: any = null;
-  if (Object.keys(newMergedRouteManifest).length > 0) {
-    const buildRouteTrie = buildMod.buildRouteTrie;
-    if (buildRouteTrie && mergedRouteAncestry) {
-      // Build routeToStaticPrefix from saved manifests
-      const routeToStaticPrefix: Record<string, string> = {};
-      for (const { manifest } of allManifests) {
-        // Root-level routes have empty static prefix
-        for (const name of Object.keys(manifest.routeManifest)) {
-          if (!(name in routeToStaticPrefix)) {
-            routeToStaticPrefix[name] = "";
-          }
-        }
-        buildRouteToStaticPrefix(manifest.prefixTree, routeToStaticPrefix);
-      }
-
-      // Collect prerender route names and response type routes from all manifests
-      const prerenderRouteNames = new Set<string>();
-      const passthroughRouteNames = new Set<string>();
-      const mergedResponseTypeRoutes: Record<string, string> = {};
-      for (const { manifest } of allManifests) {
-        if (manifest.prerenderRoutes) {
-          for (const name of manifest.prerenderRoutes) {
-            prerenderRouteNames.add(name);
-          }
-        }
-        if (manifest.passthroughRoutes) {
-          for (const name of manifest.passthroughRoutes) {
-            passthroughRouteNames.add(name);
-          }
-        }
-        if (manifest.responseTypeRoutes) {
-          Object.assign(mergedResponseTypeRoutes, manifest.responseTypeRoutes);
-        }
-      }
-
-      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,
-      );
+  debug?.(
+    "inner: generated manifests for %d router(s) (%sms)",
+    allManifests.length,
+    (performance.now() - manifestGenStart).toFixed(1),
+  );
 
-      // Build per-router tries for multi-router isolation.
-      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] = "";
-        }
-        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,
-        );
+  // No merged trie is built: find-match.ts consumes per-router tries only
+  // (getRouterTrie(routerId)), falling back to regex over live routes on a
+  // gap — the global merged trie was never read by any matcher.
+  const trieStart = debug ? performance.now() : 0;
+  if (Object.keys(newMergedRouteManifest).length > 0) {
+    // 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) {
+      const perRouterTrie = buildPerRouterTrie(manifest);
+      if (perRouterTrie) {
         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.
   state.mergedRouteManifest = newMergedRouteManifest;
-  state.mergedPrecomputedEntries = newMergedPrecomputedEntries;
   state.perRouterManifests = newPerRouterManifests;
   state.perRouterManifestDataMap = newPerRouterManifestDataMap;
   state.perRouterPrecomputedMap = newPerRouterPrecomputedMap;
   state.perRouterTrieMap = newPerRouterTrieMap;
-  state.mergedRouteTrie = newMergedRouteTrie;
+
+  // Install the route tries into the RSC realm BEFORE prerender collection.
+  // matchForPrerender resolves each enumerated URL via findMatch, and without
+  // a trie findMatch silently falls back to the insertion-order regex matcher
+  // — a root `path("/*")` declared before a nested static route then wins the
+  // match, and the artifact bakes the CATCH-ALL page under `catchAll/<hash>`
+  // while runtime (trie-ranked: wildcard last) matches the real route and
+  // misses the manifest — wrong-content bake for plain Prerender routes, a
+  // guaranteed 404 once handler eviction runs. Dev never hits this because
+  // propagateDiscoveryState (router-discovery.ts) pushes the same setters on
+  // every discovery/HMR pass; configureServer early-returns in build mode, so
+  // collection was the one findMatch consumer running trieless. Mirrors the
+  // dev perRouterSetters loop; deliberately does NOT markRouterTrieAuthoritative
+  // so a genuine trie gap keeps the regex fallback, exactly as in dev.
+  const perRouterSetters: Array<[Map<string, unknown>, string]> = [
+    [newPerRouterManifestDataMap, "setRouterManifest"],
+    [newPerRouterTrieMap, "setRouterTrie"],
+    [newPerRouterPrecomputedMap, "setRouterPrecomputedEntries"],
+  ];
+  for (const [map, fn] of perRouterSetters) {
+    const setter = serverMod[fn];
+    if (typeof setter !== "function") continue;
+    for (const [routerId, value] of map) setter(routerId, value);
+  }
 
   // Expand prerender routes and render static handlers (build mode only)
   await expandPrerenderRoutes(state, rscEnv, registry, allManifests);