@rangojs/router 0.27.0 → 0.29.0

package/src/vite/discovery/build-discovery-phase.ts

@@ -0,0 +1,204 @@
+/**
+ * Build discovery phase: the discovery plugin's buildStart, buildApp (post)
+ * and buildEnd hooks.
+ *
+ * buildStart discovers routers through a temp RSC server and writes the
+ * generated route types. When PPR shell candidates exist, it defers closing
+ * that server, and releasing the buildEnv, as a PAIR: the buildApp post hook
+ * releases them after the shell capture (success), buildEnd after an
+ * environment build failure (abort).
+ */
+
+import type { Rolldown, ViteBuilder } from "vite";
+import type { DiscoveryState } from "./state.js";
+import { createTempRscServer } from "../temp-rsc-server.js";
+import { acquireBuildEnv, releaseBuildEnv } from "./build-env.js";
+import { discoverRouters } from "./discover-routers.js";
+import { writeRouteTypesFiles } from "./route-types-writer.js";
+import { runShellPrerenderPhase } from "./shell-prerender-phase.js";
+import { runRouterVersionsPhase } from "./router-versions-phase.js";
+import { resetStagedBuildAssets } from "../utils/prerender-utils.js";
+import { createRangoDebugger, timed, timedSync, NS } from "../debug.js";
+
+const debugDiscovery = createRangoDebugger(NS.discovery);
+
+/**
+ * Reset the per-build prerender collection state. A helper (not inline
+ * assignments in buildStart) so TS's property narrowing does not pin
+ * `s.shellCandidates` to `null` across the discovery call that repopulates
+ * it — the finally block re-reads it to decide the temp-server keep-alive.
+ */
+function resetPrerenderCollection(s: DiscoveryState): void {
+  s.prerenderManifestEntries = null;
+  s.staticManifestEntries = null;
+  s.shellCandidates = null;
+  s.prerenderPayloadValues = null;
+  s.buildData = [];
+}
+
+/**
+ * buildStart. Build mode: create a temporary Vite dev server to access the
+ * RSC environment's module runner, then discover routers and generate
+ * manifests. The manifest data is stored for the virtual module's load hook.
+ */
+export async function buildDiscoveryPhase(
+  s: DiscoveryState,
+  context: Rolldown.PluginContext,
+): Promise<void> {
+  if (!s.isBuildMode) return;
+  // Only run once across environment builds
+  if (s.mergedRouteManifest !== null) {
+    debugDiscovery?.(
+      "build: skip (already discovered, env=%s)",
+      context.environment?.name ?? "?",
+    );
+    return;
+  }
+  const buildStartTime = performance.now();
+  debugDiscovery?.("build: start (env=%s)", context.environment?.name ?? "?");
+  resetStagedBuildAssets(s.projectRoot);
+  resetPrerenderCollection(s);
+
+  // Acquire build-time env bindings if configured
+  await timed(debugDiscovery, "build acquireBuildEnv", () =>
+    acquireBuildEnv(s, s.viteCommand, s.viteMode),
+  );
+
+  let tempServer: any = null;
+  // Signal to user-space code (e.g. reverse.ts) that build-time discovery
+  // is active. Uses globalThis because the temp server's module runner
+  // creates a separate module context — there is no shared import path
+  // between the vite plugin and user code loaded via runner.import().
+  (globalThis as any).__rscRouterDiscoveryActive = true;
+  try {
+    tempServer = await timed(debugDiscovery, "build createTempRscServer", () =>
+      createTempRscServer(s, { forceBuild: true }),
+    );
+
+    const rscEnv = (tempServer.environments as any)?.rsc;
+    if (!rscEnv?.runner) {
+      console.warn(
+        "[rango] RSC environment runner not available during build, skipping manifest generation",
+      );
+      return;
+    }
+
+    // Point resolvedStaticModules at the temp server's expose-internal-ids
+    // plugin so that discoverRouters() can access the static handler module
+    // map after the temp server's transforms populate it.
+    const tempIdsPlugin = (tempServer as any).config?.plugins?.find(
+      (p: any) => p.name === "@rangojs/router:expose-internal-ids",
+    );
+    if (tempIdsPlugin?.api?.staticHandlerModules) {
+      s.resolvedStaticModules = tempIdsPlugin.api.staticHandlerModules;
+    }
+
+    await timed(debugDiscovery, "build discoverRouters", () =>
+      discoverRouters(s, rscEnv, (tempServer.environments as any)?.ssr),
+    );
+    // Update named-routes.gen.ts from runtime discovery.
+    // The runtime manifest includes dynamically generated routes
+    // that the static parser cannot extract from source code.
+    timedSync(debugDiscovery, "build writeRouteTypesFiles", () =>
+      writeRouteTypesFiles(s),
+    );
+  } catch (err: any) {
+    // Extract the user source file from the stack trace (skip internal frames)
+    const sourceFile = err.stack
+      ?.split("\n")
+      .find(
+        (line: string) =>
+          line.includes(s.projectRoot) && !line.includes("node_modules"),
+      )
+      ?.match(/\(([^)]+)\)/)?.[1];
+    // Extract the route name from "Unknown route: <name>" errors
+    const routeName = err.message?.match(/Unknown route: (.+)/)?.[1];
+    const details = [
+      routeName ? `  Route name: ${routeName}` : null,
+      sourceFile ? `  File: ${sourceFile}` : null,
+      err.stack ? `  Stack:\n${err.stack}` : null,
+    ]
+      .filter(Boolean)
+      .join("\n");
+    throw new Error(`[rango] Build-time router discovery failed:\n${details}`, {
+      cause: err,
+    });
+  } finally {
+    delete (globalThis as any).__rscRouterDiscoveryActive;
+    if (tempServer && s.shellCandidates?.length) {
+      // Prerender+ppr candidates exist: keep the temp server (and its
+      // realm — tries installed, registry populated) alive for the
+      // post-build shell capture phase (buildApp post, producer B #699).
+      // The prelude embeds built client asset URLs, so the capture can
+      // only run after the client build; that phase closes the server.
+      // buildEnv release is deferred with it — a bake-lane loader
+      // executing during the capture may read ctx.env.
+      s.shellPhaseTempServer = tempServer;
+    } else {
+      if (tempServer) {
+        await timed(debugDiscovery, "build tempServer.close", () =>
+          tempServer.close(),
+        );
+      }
+      await releaseBuildEnv(s);
+    }
+    debugDiscovery?.(
+      "build discovery done (%sms)",
+      (performance.now() - buildStartTime).toFixed(1),
+    );
+  }
+}
+
+/**
+ * buildApp (post). Post-build phases, after EVERY environment bundle is
+ * written.
+ *
+ * 1. Cache versions (router-versions-phase.ts): hashes the server output as
+ *    postprocessBundle left it and writes the per-router table into the
+ *    built version module. First, because phase 2 stamps its entries with
+ *    these versions and reads the same RSC out dir.
+ * 2. PPR shell capture (producer B, #699): the shell prelude embeds built
+ *    client asset URLs (bootstrap entry), which do not exist at buildStart.
+ *    The kept temp server and the buildEnv were deferred AS A PAIR in
+ *    buildStart's finally; this finally is the pair's success-path owner
+ *    (buildEndPhase owns the aborted-build path) — the phase itself is a pure
+ *    producer and tears down only the globals it installs.
+ */
+export async function postBuildPhase(
+  s: DiscoveryState,
+  builder: ViteBuilder,
+): Promise<void> {
+  try {
+    await runShellPrerenderPhase(
+      s,
+      builder as any,
+      runRouterVersionsPhase(s, builder as any),
+    );
+  } finally {
+    if (s.isBuildMode) {
+      const tempServer = s.shellPhaseTempServer;
+      s.shellPhaseTempServer = null;
+      if (tempServer) await tempServer.close();
+      await releaseBuildEnv(s);
+    }
+  }
+}
+
+/**
+ * buildEnd. An environment build failure aborts the builder before the
+ * buildApp post hook — never leak the kept temp server (open handles hang
+ * the CLI) or the deferred buildEnv (a live miniflare proxy).
+ */
+export async function buildEndPhase(
+  s: DiscoveryState,
+  error: Error | undefined,
+): Promise<void> {
+  if (!error || !s.shellPhaseTempServer) return;
+  const tempServer = s.shellPhaseTempServer;
+  s.shellPhaseTempServer = null;
+  try {
+    await tempServer.close();
+  } finally {
+    await releaseBuildEnv(s);
+  }
+}

package/src/vite/discovery/build-env.ts

@@ -0,0 +1,148 @@
+/**
+ * Build-time env (rango({ buildEnv })): resolution of the option and the
+ * lifetime of the resolved bindings on DiscoveryState. Acquired by dev
+ * discovery (dev-server-phase.ts) and build discovery
+ * (build-discovery-phase.ts).
+ */
+
+import { dirname, join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { BUILD_ENV_GLOBAL_KEY } from "../plugins/cloudflare-protocol-stub.js";
+import type {
+  BuildEnvOption,
+  BuildEnvFactoryContext,
+  BuildEnvResult,
+} from "../plugin-types.js";
+import type { DiscoveryState } from "./state.js";
+
+const WRANGLER_CONFIG_NAMES: readonly string[] = [
+  "wrangler.json",
+  "wrangler.jsonc",
+  "wrangler.toml",
+];
+
+/**
+ * getPlatformProxy() looks for the wrangler config from process.cwd() and
+ * resolves its default persist path against cwd, so building from another
+ * directory dropped the app's bindings (#1037). Search upward from the Vite
+ * root with wrangler's own file names and order. Persisted state goes under
+ * the Vite root, where @cloudflare/vite-plugin reads it in dev and preview
+ * (its getPersistenceRoot), also when the config sits above the root. No
+ * config found: no options, wrangler's own lookup.
+ */
+function wranglerProxyOptions(
+  root: string,
+): Record<string, unknown> | undefined {
+  const viteRoot = resolve(root);
+  for (let dir = viteRoot; ; dir = dirname(dir)) {
+    for (const name of WRANGLER_CONFIG_NAMES) {
+      const configPath = join(dir, name);
+      if (existsSync(configPath)) {
+        return {
+          configPath,
+          persist: { path: join(viteRoot, ".wrangler", "state", "v3") },
+        };
+      }
+    }
+    if (dirname(dir) === dir) return undefined;
+  }
+}
+
+/**
+ * Resolve the buildEnv option into a concrete { env, dispose? } result.
+ * Handles all four input shapes: false, "auto", factory, plain object.
+ */
+export async function resolveBuildEnv(
+  option: BuildEnvOption | undefined,
+  factoryCtx: BuildEnvFactoryContext,
+): Promise<BuildEnvResult | null> {
+  if (!option) return null;
+
+  if (option === "auto") {
+    if (factoryCtx.preset !== "cloudflare") {
+      throw new Error(
+        '[rango] buildEnv: "auto" is only supported with preset: "cloudflare". ' +
+          "Use a factory function or plain object for other presets.",
+      );
+    }
+    try {
+      // Resolve wrangler from the user's project root (not the router package)
+      const userRequire = createRequire(
+        resolve(factoryCtx.root, "package.json"),
+      );
+      const wranglerPath = userRequire.resolve("wrangler");
+      const { getPlatformProxy } = (await import(
+        pathToFileURL(wranglerPath).href
+      )) as {
+        getPlatformProxy: (opts?: any) => Promise<any>;
+      };
+      const proxy = await getPlatformProxy(
+        wranglerProxyOptions(factoryCtx.root),
+      );
+      return {
+        env: proxy.env as Record<string, unknown>,
+        dispose: proxy.dispose,
+      };
+    } catch (err: any) {
+      throw new Error(
+        '[rango] buildEnv: "auto" requires wrangler to be installed.\n' +
+          `Install it with: pnpm add -D wrangler\n${err.message}`,
+      );
+    }
+  }
+
+  if (typeof option === "function") {
+    return await option(factoryCtx);
+  }
+
+  // Plain object
+  return { env: option };
+}
+
+/**
+ * Acquire build-time env bindings and store on discovery state.
+ * Returns true if env was acquired, false if buildEnv is disabled.
+ */
+export async function acquireBuildEnv(
+  s: DiscoveryState,
+  command: "serve" | "build",
+  mode: string,
+): Promise<boolean> {
+  const option = s.opts?.buildEnv;
+  if (!option) return false;
+
+  const result = await resolveBuildEnv(option, {
+    root: s.projectRoot,
+    mode,
+    command,
+    preset: s.opts?.preset ?? "node",
+  });
+  if (!result) return false;
+
+  s.resolvedBuildEnv = result.env;
+  s.buildEnvDispose = result.dispose ?? null;
+  // Bridge the resolved env into `cloudflare:workers`'s stubbed `env`
+  // export so user code that does `import { env } from "cloudflare:workers"`
+  // sees the real bindings proxy during discovery + prerender instead of
+  // an empty object. The stub reads this global at module-evaluation time.
+  (globalThis as Record<string, unknown>)[BUILD_ENV_GLOBAL_KEY] = result.env;
+  return true;
+}
+
+/**
+ * Release build-time env resources and clear state.
+ */
+export async function releaseBuildEnv(s: DiscoveryState): Promise<void> {
+  if (s.buildEnvDispose) {
+    try {
+      await s.buildEnvDispose();
+    } catch (err: any) {
+      console.warn(`[rango] buildEnv dispose failed: ${err.message}`);
+    }
+    s.buildEnvDispose = null;
+  }
+  s.resolvedBuildEnv = undefined;
+  delete (globalThis as Record<string, unknown>)[BUILD_ENV_GLOBAL_KEY];
+}

package/src/vite/discovery/bundle-scan-phase.ts

@@ -0,0 +1,128 @@
+/**
+ * Bundle scan phase: the discovery plugin's generateBundle hook.
+ *
+ * Records the inputs of the per-router cache versions (build-versions.ts) for
+ * every environment and, during the RSC build, the RSC entry filename and the
+ * chunks holding Prerender/Static handler exports. closeBundle
+ * (bundle-postprocess.ts) uses them for handler code eviction and prerender
+ * data injection.
+ */
+
+import type { Rolldown } from "vite";
+import type { DiscoveryState } from "./state.js";
+import {
+  recordBundleFiles,
+  recordClientGraph,
+  recordServerGraph,
+  recordVersionModuleFiles,
+} from "./build-versions.js";
+import { extractHandlerExportsFromChunk } from "../utils/bundle-analysis.js";
+import { createRangoDebugger, NS } from "../debug.js";
+
+const debugBuild = createRangoDebugger(NS.build);
+
+export function bundleScanPhase(
+  s: DiscoveryState,
+  context: Rolldown.PluginContext,
+  bundle: any,
+): void {
+  // Inputs of the per-router cache versions (discovery/build-versions.ts).
+  // Each pass overwrites its slot: plugin-rsc runs the RSC and SSR builds
+  // twice, and the real pass comes last.
+  if (s.isBuildMode) {
+    const envName = context.environment?.name;
+    if (envName) {
+      s.versionModuleFiles.set(envName, recordVersionModuleFiles(bundle));
+    }
+    if (envName === "rsc") {
+      s.serverBuildGraph = recordServerGraph(context, bundle);
+    } else if (envName === "client") {
+      s.clientBuildGraph = recordClientGraph(context, bundle);
+    } else if (envName === "ssr") {
+      s.ssrBundle = recordBundleFiles(bundle);
+    }
+  }
+  if (context.environment?.name !== "rsc") return;
+  const genStart = debugBuild ? performance.now() : 0;
+
+  // Record RSC entry chunk filename for closeBundle injection
+  for (const [fileName, chunk] of Object.entries(bundle) as [string, any][]) {
+    if (chunk.type === "chunk" && chunk.isEntry) {
+      s.rscEntryFileName = fileName;
+      break;
+    }
+  }
+
+  if (!s.resolvedPrerenderModules?.size && !s.resolvedStaticModules?.size) {
+    debugBuild?.(
+      "generateBundle (rsc): no handlers to scan (%sms)",
+      (performance.now() - genStart).toFixed(1),
+    );
+    return;
+  }
+
+  // Clear maps at the start of each RSC generateBundle pass.
+  // Vite 6 multi-environment builds run RSC twice (analysis + production);
+  // clearing prevents stale/duplicate records from the analysis pass.
+  s.handlerChunkInfoMap.clear();
+  s.staticHandlerChunkInfoMap.clear();
+
+  for (const [fileName, chunk] of Object.entries(bundle) as [string, any][]) {
+    if (chunk.type !== "chunk") continue;
+
+    // Scan all chunks for handler exports (handlers may land in any chunk)
+    if (s.resolvedPrerenderModules?.size) {
+      const handlers = extractHandlerExportsFromChunk(
+        chunk.code,
+        s.resolvedPrerenderModules,
+        "Prerender",
+        false,
+        // Mark onDemand exports (retained, not evicted) from the
+        // discovery-derived $$id set — the same evaluated source that sets
+        // the runtime od trie flag, so retention and serve can never
+        // disagree. Populated by discoverRouters (buildStart), which runs
+        // before this generateBundle pass.
+        s.onDemandHandlerIds,
+      );
+      if (handlers.length > 0) {
+        const existing = s.handlerChunkInfoMap.get(fileName);
+        if (existing) {
+          existing.exports.push(...handlers);
+        } else {
+          s.handlerChunkInfoMap.set(fileName, {
+            fileName,
+            exports: handlers,
+          });
+        }
+      }
+    }
+
+    if (s.resolvedStaticModules?.size) {
+      const handlers = extractHandlerExportsFromChunk(
+        chunk.code,
+        s.resolvedStaticModules,
+        "Static",
+        false,
+      );
+      if (handlers.length > 0) {
+        const existing = s.staticHandlerChunkInfoMap.get(fileName);
+        if (existing) {
+          existing.exports.push(...handlers);
+        } else {
+          s.staticHandlerChunkInfoMap.set(fileName, {
+            fileName,
+            exports: handlers,
+          });
+        }
+      }
+    }
+  }
+
+  debugBuild?.(
+    "generateBundle (rsc): scanned %d chunks, %d prerender chunk(s), %d static chunk(s) (%sms)",
+    Object.keys(bundle).length,
+    s.handlerChunkInfoMap.size,
+    s.staticHandlerChunkInfoMap.size,
+    (performance.now() - genStart).toFixed(1),
+  );
+}

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

@@ -23,6 +23,7 @@
  */
 
 import type { SerializedSegmentData } from "../../cache/types.js";
+import { interceptVariantSegments } from "../../prerender/store.js";
 
 /** Structural slice of `matchForPrerender`'s result the payload derivation needs. */
 export interface DevPrerenderMatchPayloadSource {
@@ -37,8 +38,9 @@ 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=1` response: the build's intercept variant
+   * (interceptVariantSegments, prerender/store.ts) with the producer's handle
+   * string for it. Falls back to `main` byte-for-byte when the route has no
    * intercept segments — mirroring the endpoint's historical behavior.
    */
   intercept: string;
@@ -64,7 +66,10 @@ export function payloadBodiesFromResult(
   });
   const intercept = result.interceptSegments?.length
     ? JSON.stringify({
-        segments: [...result.segments, ...result.interceptSegments],
+        segments: interceptVariantSegments(
+          result.segments,
+          result.interceptSegments,
+        ),
         handles: result.interceptHandles ?? "",
       })
     : main;