@rangojs/router 0.20.0 → 0.22.0

package/src/vite/discovery/bundle-postprocess.ts

@@ -33,6 +33,10 @@ export function postprocessBundle(state: DiscoveryState): void {
   );
 
   // 1. Evict handler code from whichever chunks contain handler exports.
+  // onDemand retention needs no cross-check here: the chunk scan marks
+  // onDemand exports directly from state.onDemandHandlerIds (the evaluated
+  // source's $$id set), so retention and the runtime od trie flag share one
+  // derivation and cannot disagree.
   // handlerChunkInfoMap/staticHandlerChunkInfoMap are populated by generateBundle
   // after the production RSC build. In Vite 6 multi-environment builds, the
   // RSC build runs twice (analysis + production). The maps are cleared at the

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

@@ -337,6 +337,20 @@ export async function discoverRouters(
     (performance.now() - trieStart).toFixed(1),
   );
 
+  // handlerId -> route name for onDemand routes, from the evaluated source —
+  // the authoritative side of postprocessBundle's retention cross-check.
+  const newOnDemandHandlerIds = new Map<string, string>();
+  for (const { manifest } of allManifests) {
+    if (!manifest.onDemandRoutes) continue;
+    const defs = manifest._prerenderDefs || {};
+    for (const routeName of manifest.onDemandRoutes) {
+      const handlerId = defs[routeName]?.$$id;
+      if (typeof handlerId === "string") {
+        newOnDemandHandlerIds.set(handlerId, routeName);
+      }
+    }
+  }
+
   // 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.
@@ -345,6 +359,7 @@ export async function discoverRouters(
   state.perRouterManifestDataMap = newPerRouterManifestDataMap;
   state.perRouterPrecomputedMap = newPerRouterPrecomputedMap;
   state.perRouterTrieMap = newPerRouterTrieMap;
+  state.onDemandHandlerIds = newOnDemandHandlerIds;
 
   // Install the route tries into the RSC realm BEFORE prerender collection.
   // matchForPrerender resolves each enumerated URL via findMatch, and without

package/src/vite/discovery/installed-packages.ts

@@ -0,0 +1,159 @@
+/**
+ * What is installed for a package a server build leaves external.
+ *
+ * The node preset bundles only packages that need the React server condition
+ * (plugin-rsc's `noExternal`); every other dependency stays an import the
+ * deployed process resolves from node_modules. The built chunk then says
+ * `from "pkg"` whichever version is installed, so a lockfile bump changes what
+ * the server renders and nothing the cache versions hash
+ * (discovery/build-versions.ts). This module supplies the missing input: the
+ * `name@version` of the package and of everything it depends on, as installed
+ * next to the project at build time.
+ *
+ * A registry package's code is fixed by its version. A linked package (a
+ * workspace package, resolved to a directory outside node_modules) is not.
+ * Vite bundles those unless the config lists one in `resolve.external`; then
+ * it comes through here and its files are digested instead.
+ */
+
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  type Stats,
+} from "node:fs";
+import { dirname, join, sep } from "node:path";
+import { compareStrings } from "../utils/compare-strings.js";
+
+interface InstalledPackage {
+  readonly label: string;
+  readonly dependencies: readonly string[];
+}
+
+/** What a symlink points at, or nothing for a dangling or circular one: an
+ *  import could not load it either. */
+function linkTarget(path: string): Stats | undefined {
+  try {
+    return statSync(path);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Digest of every file under `dir`, by relative path, skipping installs.
+ * Symlinks are followed (a linked file is importable like any other); a
+ * directory is entered once, so a link back up the tree ends there.
+ */
+function digestDirectory(dir: string): string {
+  const hash = createHash("sha256");
+  const entered = new Set<string>();
+  const visit = (current: string, prefix: string): void => {
+    const real = realpathSync(current);
+    if (entered.has(real)) return;
+    entered.add(real);
+    const entries = readdirSync(current, { withFileTypes: true }).sort((a, b) =>
+      compareStrings(a.name, b.name),
+    );
+    for (const entry of entries) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      const path = join(current, entry.name);
+      const name = `${prefix}${entry.name}`;
+      const kind = entry.isSymbolicLink() ? linkTarget(path) : entry;
+      if (kind?.isDirectory()) {
+        visit(path, `${name}/`);
+      } else if (kind?.isFile()) {
+        const bytes = readFileSync(path);
+        hash.update(`${name}\0${bytes.byteLength}\0`);
+        hash.update(bytes);
+      }
+    }
+  };
+  visit(dir, "");
+  return hash.digest("hex");
+}
+
+/** Node's lookup for a bare specifier: the nearest node_modules holding it. */
+function findPackageDir(name: string, from: string): string | undefined {
+  for (let dir = from; ; ) {
+    const candidate = join(dir, "node_modules", name);
+    if (existsSync(join(candidate, "package.json"))) {
+      return realpathSync(candidate);
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/**
+ * Returns a function describing an installed package by name: the sorted
+ * `name@version` lines of the package and its transitive dependencies
+ * (dependencies, optionalDependencies and peerDependencies, each resolved from
+ * the package that declares it), with a digest of its files for a linked
+ * one, or `undefined` when the package is not installed. Results are kept per
+ * name for the life of the returned function.
+ */
+export function createInstalledPackageDescriber(
+  projectRoot: string,
+): (name: string) => string | undefined {
+  const packages = new Map<string, InstalledPackage | undefined>();
+  const read = (dir: string): InstalledPackage | undefined => {
+    if (packages.has(dir)) return packages.get(dir);
+    let manifest: any;
+    try {
+      manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+    } catch {
+      packages.set(dir, undefined);
+      return undefined;
+    }
+    // Outside the try: a linked package whose files cannot be read must fail
+    // the build, not drop out of the version.
+    const linked = !dir.split(sep).includes("node_modules");
+    const found: InstalledPackage = {
+      label:
+        `${manifest.name}@${manifest.version}` +
+        (linked ? ` files:${digestDirectory(dir)}` : ""),
+      dependencies: Object.keys({
+        ...manifest.dependencies,
+        ...manifest.optionalDependencies,
+        ...manifest.peerDependencies,
+      }),
+    };
+    packages.set(dir, found);
+    return found;
+  };
+
+  // Packages share most of their dependencies (the same peers, the same
+  // utilities): each lookup is done once for every package described.
+  const located = new Map<string, string | undefined>();
+  const locate = (name: string, from: string): string | undefined => {
+    const key = `${from}\0${name}`;
+    if (!located.has(key)) located.set(key, findPackageDir(name, from));
+    return located.get(key);
+  };
+
+  const described = new Map<string, string | undefined>();
+  return (name) => {
+    if (described.has(name)) return described.get(name);
+    const labels = new Set<string>();
+    const seen = new Set<string>();
+    const pending: Array<[name: string, from: string]> = [[name, projectRoot]];
+    while (pending.length > 0) {
+      const [dependency, from] = pending.pop()!;
+      const dir = locate(dependency, from);
+      if (dir === undefined || seen.has(dir)) continue;
+      seen.add(dir);
+      const installed = read(dir);
+      if (!installed) continue;
+      labels.add(installed.label);
+      for (const next of installed.dependencies) pending.push([next, dir]);
+    }
+    const text = labels.size > 0 ? [...labels].sort().join("\n") : undefined;
+    described.set(name, text);
+    return text;
+  };
+}

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

@@ -7,6 +7,7 @@
  */
 
 import { contextSet, hasContextVars } from "../../context-var.js";
+import { sha256 } from "./build-versions.js";
 import {
   encodePathParam,
   substituteRouteParams,
@@ -21,6 +22,27 @@ import { createRangoDebugger, NS } from "../debug.js";
 
 const debug = createRangoDebugger(NS.prerender);
 
+/**
+ * Note a payload the build rendered and will ship as an asset module, for the
+ * owning router's cache version (build-versions.ts). The handler that produced
+ * it is evicted from the bundle, so the payload is the only thing left in the
+ * server output that changes when the handler or its build-time data does.
+ */
+function recordBuildData(
+  state: DiscoveryState,
+  kind: "prerender" | "static",
+  key: string,
+  value: string,
+  owner: { routerId?: string; moduleId?: string },
+): void {
+  state.buildData.push({
+    kind,
+    key,
+    digest: sha256(value),
+    ...owner,
+  });
+}
+
 /**
  * Expand prerender routes into concrete URLs and render them via the
  * RSC runner. Stages asset modules and stores key-to-file entries in
@@ -248,7 +270,7 @@ export async function expandPrerenderRoutes(
       group.concurrency,
       async (entry) => {
         const startUrl = performance.now();
-        for (const [, routerInstance] of registry) {
+        for (const [routerId, routerInstance] of registry) {
           if (!routerInstance.matchForPrerender) continue;
           try {
             const result = await routerInstance.matchForPrerender(
@@ -281,6 +303,9 @@ export async function expandPrerenderRoutes(
               "__pr",
               mainValue,
             );
+            recordBuildData(state, "prerender", mainKey, mainValue, {
+              routerId,
+            });
             // Prerender + ppr composition: flag the URL as a build-time shell
             // candidate for the post-build capture phase (producer B, #699).
             // The payload JSON is retained in memory so that phase can seed an
@@ -310,6 +335,15 @@ export async function expandPrerenderRoutes(
                 "__pr",
                 interceptValue,
               );
+              recordBuildData(
+                state,
+                "prerender",
+                interceptKey,
+                interceptValue,
+                {
+                  routerId,
+                },
+              );
             }
             const elapsed = (performance.now() - startUrl).toFixed(0);
             console.log(
@@ -447,6 +481,9 @@ export async function renderStaticHandlers(
               "__st",
               exportValue,
             );
+            recordBuildData(state, "static", def.$$id, exportValue, {
+              moduleId,
+            });
             const elapsed = (performance.now() - startHandler).toFixed(0);
             console.log(`[rango]   OK   ${name.padEnd(40)} (${elapsed}ms)`);
             staticDone++;

package/src/vite/discovery/router-versions-phase.ts

@@ -0,0 +1,336 @@
+/**
+ * Post-build cache version phase.
+ *
+ * Runs from the buildApp post hook, after every environment bundle is written
+ * and postprocessBundle has rewritten the RSC chunks, and before the shell
+ * capture phase, which stamps its entries with the document versions computed
+ * here. Reads the bytes that ship, computes each router's versions
+ * (build-versions.ts) and writes the table into the built
+ * `@rangojs/router:version` module in place of its placeholder.
+ */
+
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {
+  DEFAULT_ROUTER_VERSIONS_KEY,
+  type RouterVersionsTable,
+} from "../../router-versions.js";
+import { isEncryptionKeyStable } from "../encryption-key.js";
+import { createRangoDebugger, NS } from "../debug.js";
+import {
+  defaultExportProperties,
+  literalProperties,
+} from "../plugins/stable-rsc-output.js";
+import { RANGO_BUILD_DIR } from "../utils/prerender-utils.js";
+import {
+  computeRouterVersions,
+  fillRouterVersions,
+  portableModuleId,
+  sha256,
+  type BuildDataRecord,
+  type ComputedRouterVersions,
+} from "./build-versions.js";
+import { createInstalledPackageDescriber } from "./installed-packages.js";
+import type { DiscoveryState } from "./state.js";
+
+const debug = createRangoDebugger(NS.build);
+
+/** plugin-rsc's client asset manifest, written into the SSR and RSC out dirs. */
+const ASSETS_MANIFEST_FILE = "__vite_rsc_assets_manifest.js";
+const EMPTY_SERVER_RESOURCES = /"serverResources":\s*\{\s*\}/;
+
+/** Minimal builder surface the post-build phases read. */
+export interface BuilderLike {
+  config?: { base?: string };
+  environments?: Record<
+    string,
+    { config?: { build?: { outDir?: string } } } | undefined
+  >;
+}
+
+/**
+ * An environment's output directory, or Vite's default layout without one.
+ * Resolved against the root: a relative `build.outDir` is relative to it, not
+ * to the directory `vite build <root>` was run from.
+ */
+export function environmentOutDir(
+  builder: BuilderLike | undefined,
+  projectRoot: string,
+  environment: string,
+): string {
+  return resolve(
+    projectRoot,
+    builder?.environments?.[environment]?.config?.build?.outDir ??
+      join("dist", environment),
+  );
+}
+
+/**
+ * Where the build leaves what each version was computed from. Outside the
+ * output directories, so it never ships.
+ */
+export const VERSIONS_REPORT_FILE: string = `${RANGO_BUILD_DIR}/cache-versions.json`;
+
+function readIfPresent(path: string): Buffer | undefined {
+  try {
+    return readFileSync(path);
+  } catch (err: any) {
+    if (err?.code === "ENOENT") return undefined;
+    throw err;
+  }
+}
+
+/**
+ * The `serverResources` map of plugin-rsc's assets manifest
+ * (`export default { ..., serverResources: { "<module>": { js, css } } }`):
+ * each server module that imports CSS, to the source text of its entry. Text,
+ * not a parsed value: with `renderBuiltUrl` an entry holds runtime expressions.
+ * Throws when the manifest is not that shape, so a plugin-rsc that moves it
+ * fails the build instead of dropping stylesheets from the versions.
+ */
+export function readServerResources(manifest: string): Map<string, string> {
+  // Most apps import no CSS from a server component: skip parsing a manifest
+  // that lists every client reference. (Inside a JSON string the quotes would
+  // be escaped, so this text can only be the property itself.)
+  if (EMPTY_SERVER_RESOURCES.test(manifest)) return new Map();
+  const entries = literalProperties(
+    defaultExportProperties(manifest)?.find(
+      (property) => property.key === "serverResources",
+    )?.value,
+  );
+  if (!entries) {
+    throw new Error(
+      `${ASSETS_MANIFEST_FILE} has no serverResources object literal: the installed ` +
+        `@vitejs/plugin-rsc writes a manifest @rangojs/router cannot read. ` +
+        `Report it with the plugin-rsc version.`,
+    );
+  }
+  return new Map(
+    entries.map((entry) => [
+      entry.key,
+      manifest.slice(entry.value.start, entry.value.end),
+    ]),
+  );
+}
+
+/**
+ * One record per clientUrls() module: the projection the server materializes
+ * the group from. The map holds it under each of the module's reference ids.
+ */
+function clientUrlRecords(s: DiscoveryState): BuildDataRecord[] {
+  const projectionOf = new Map<string, string>();
+  for (const [referenceId, projection] of s.clientUrlProjectionMap ?? []) {
+    projectionOf.set(
+      s.clientUrlSourceByReferenceId?.get(referenceId) ?? referenceId,
+      JSON.stringify(projection),
+    );
+  }
+  return [...projectionOf].map(([source, projection]) => ({
+    kind: "client-urls",
+    key: portableModuleId(source, s.projectRoot),
+    digest: sha256(projection),
+    moduleId: source,
+  }));
+}
+
+/**
+ * Write every version's inputs as `name: digest`. A version is one hash, so a
+ * changed version says nothing about what changed; diffing two builds' reports
+ * names the file, payload or key that did.
+ */
+function writeVersionsReport(
+  projectRoot: string,
+  computed: ComputedRouterVersions,
+  sourceOf: ReadonlyMap<string, string>,
+): void {
+  const routers: Record<string, unknown> = {};
+  for (const detail of computed.details) {
+    routers[detail.routerId] = {
+      source: sourceOf.get(detail.routerId) ?? "",
+      data: detail.data,
+      document: detail.document,
+      dataInputs: Object.fromEntries(detail.dataInputs),
+      documentInputs: Object.fromEntries(detail.documentInputs),
+    };
+  }
+  // Listed once, not per router. `ssrAndClient`: what the `ssr-and-client`
+  // input of every document version is a digest of. `unownedFiles`: server
+  // files in no router's version but the whole build's (the host entry, the
+  // registries); a change there keeps every app's cache.
+  const report = {
+    routers,
+    ssrAndClient: {
+      base: computed.ssrAndClient.base,
+      ssr: Object.fromEntries(computed.ssrAndClient.ssr),
+      externals: Object.fromEntries(computed.ssrAndClient.externals),
+      client: computed.ssrAndClient.client,
+    },
+    unownedFiles: computed.unownedFiles,
+  };
+  try {
+    const path = resolve(projectRoot, VERSIONS_REPORT_FILE);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(report, null, 2) + "\n");
+  } catch (err: any) {
+    debug?.("could not write %s: %s", VERSIONS_REPORT_FILE, err?.message);
+  }
+}
+
+/**
+ * Compute the versions, write them into the built version module and return
+ * the table (`undefined` outside a build). Fails the build when an input was
+ * not recorded or cannot be read: a version computed without it would stay
+ * the same when it changes.
+ */
+export function runRouterVersionsPhase(
+  s: DiscoveryState,
+  builder: BuilderLike | undefined,
+): RouterVersionsTable | undefined {
+  if (!s.isBuildMode) return undefined;
+  const { serverBuildGraph: server, clientBuildGraph: client } = s;
+  const ssr = s.ssrBundle;
+  const rscVersionFiles = s.versionModuleFiles.get("rsc") ?? [];
+  // The built version module holds a placeholder only this phase replaces: a
+  // build that skipped it would throw a ReferenceError on its first import.
+  if (!server || !client || !ssr || rscVersionFiles.length === 0) {
+    const missing = [
+      !server && "the RSC bundle",
+      !client && "the client bundle",
+      !ssr && "the SSR bundle",
+      rscVersionFiles.length === 0 &&
+        "the RSC chunk that holds the version module",
+    ].filter(Boolean);
+    throw new Error(
+      `[rango] The build did not record ${missing.join(", ")}, so the cache versions cannot be computed. ` +
+        "This is a bug in @rangojs/router; please report it.",
+    );
+  }
+
+  const start = performance.now();
+  const rscOutDir = environmentOutDir(builder, s.projectRoot, "rsc");
+  const ssrOutDir = environmentOutDir(builder, s.projectRoot, "ssr");
+
+  let computed: ComputedRouterVersions;
+  try {
+    const assetsManifest = readIfPresent(join(rscOutDir, ASSETS_MANIFEST_FILE));
+    if (assetsManifest === undefined) {
+      throw new Error(
+        `${ASSETS_MANIFEST_FILE} is not in the RSC output directory, so the stylesheets ` +
+          `server components link cannot be read`,
+      );
+    }
+    computed = computeRouterVersions({
+      projectRoot: s.projectRoot,
+      server,
+      client,
+      // plugin-rsc writes its manifest next to the SSR bundle, not into it.
+      ssr: {
+        chunks: ssr.chunks,
+        assets: [
+          ...ssr.assets.filter(
+            (asset) => asset.fileName !== ASSETS_MANIFEST_FILE,
+          ),
+          { fileName: ASSETS_MANIFEST_FILE, name: ASSETS_MANIFEST_FILE },
+        ],
+      },
+      routers: s.perRouterManifests.map((entry) => ({
+        id: entry.id,
+        moduleId: entry.sourceFile,
+      })),
+      buildData: [...s.buildData, ...clientUrlRecords(s)],
+      readServerFile: (fileName) => readIfPresent(join(rscOutDir, fileName)),
+      readSsrFile: (fileName) => readIfPresent(join(ssrOutDir, fileName)),
+      base: builder?.config?.base ?? "/",
+      serverResources: readServerResources(assetsManifest.toString("utf-8")),
+      externals: {
+        describePackage: createInstalledPackageDescriber(s.projectRoot),
+        readFile: readIfPresent,
+        buildId: randomUUID(),
+      },
+    });
+  } catch (err: any) {
+    throw new Error(
+      `[rango] Could not compute the cache versions: ${err?.message ?? err}`,
+      { cause: err },
+    );
+  }
+  const { table, details } = computed;
+
+  for (const [environment, fileNames] of s.versionModuleFiles) {
+    const outDir = environmentOutDir(builder, s.projectRoot, environment);
+    let filled = 0;
+    for (const fileName of fileNames) {
+      const path = join(outDir, fileName);
+      const source = readIfPresent(path);
+      const next =
+        source === undefined
+          ? undefined
+          : fillRouterVersions(source.toString("utf-8"), table);
+      if (next === undefined) continue;
+      writeFileSync(path, next);
+      filled++;
+    }
+    if (environment === "rsc" && filled === 0) {
+      throw new Error(
+        `[rango] Could not write the cache versions into the server build: no placeholder in ${fileNames.join(", ")} under ${outDir}. ` +
+          `The build would fail to start. This is a bug in @rangojs/router; please report it.`,
+      );
+    }
+  }
+
+  const elapsed = (performance.now() - start).toFixed(1);
+  const sourceOf = new Map(
+    s.perRouterManifests.map((entry) => [
+      entry.id,
+      entry.sourceFile ? portableModuleId(entry.sourceFile, s.projectRoot) : "",
+    ]),
+  );
+  const detailOf = new Map(details.map((detail) => [detail.routerId, detail]));
+  const wholeBuild = detailOf.get(DEFAULT_ROUTER_VERSIONS_KEY)!;
+  let keyed = 0;
+  if (s.perRouterManifests.length > 0) {
+    console.log(
+      `[rango] Cache versions for ${s.perRouterManifests.length} router(s), data / document (${elapsed}ms):`,
+    );
+    for (const { id } of s.perRouterManifests) {
+      // A router whose module is not in the server bundle serves with the
+      // whole-build pair: any change clears it. Say so, it is not isolated.
+      const own = detailOf.get(id);
+      const detail = own ?? wholeBuild;
+      if (detail.usesEncryptionKey) keyed++;
+      console.log(
+        `[rango]   ${detail.data} / ${detail.document}  ${sourceOf.get(id) || id}${own ? "" : " (whole build)"}`,
+      );
+    }
+  }
+  debug?.(
+    "router versions: %d server file(s), %sms, table=%o",
+    server.chunks.length + server.assets.length,
+    elapsed,
+    table,
+  );
+  writeVersionsReport(s.projectRoot, computed, sourceOf);
+
+  if (computed.undetermined.length > 0) {
+    console.log(
+      `[rango] ${computed.undetermined.length} import(s) the server build leaves external could not be read ` +
+        `at build time (${computed.undetermined.join(", ")}): a package that is not installed where the build ` +
+        `can find it, a path that does not resolve, or a URL. What they resolve to at run time is unknown, so ` +
+        `the routers importing them get a new cache version on every build.`,
+    );
+  }
+
+  // The one condition under which a deploy of unchanged code still clears a
+  // cache: the key is part of these routers' versions and this build made its
+  // own. Said once per build, and only when it applies.
+  if (keyed > 0 && !isEncryptionKeyStable()) {
+    console.log(
+      `[rango] No stable encryption key: ${keyed} router(s) encrypt server-action arguments ` +
+        `with a key generated for this build, so their cache version changes on every build and each ` +
+        `deploy clears their cache. To keep it, set rango({ encryptionKey: process.env.RANGO_ENCRYPTION_KEY }) ` +
+        `with a base64 32-byte key (openssl rand -base64 32).`,
+    );
+  }
+  return table;
+}