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

package/src/vite/discovery/client-urls-projection.ts

@@ -0,0 +1,322 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { normalizePath, parseAst } from "vite";
+import {
+  serializeClientUrlPatterns,
+  type ClientUrlProjection,
+} from "../../client-urls/server-projection.js";
+import type { ClientUrlPatterns } from "../../client-urls/types.js";
+import {
+  computeProductionHash,
+  hashRefKey,
+} from "../plugins/client-ref-hashing.js";
+import { hasUseClientDirective } from "../utils/directive-prologue.js";
+import { createRangoDebugger, NS } from "../debug.js";
+import { findTsFiles } from "../../build/route-types/scan-filter.js";
+import type { DiscoveryState } from "./state.js";
+
+const debug = createRangoDebugger(NS.discovery);
+
+interface ClientUrlSsrEnvironment {
+  readonly runner?: {
+    import(id: string): Promise<Record<string, unknown>>;
+  };
+}
+
+interface ClientUrlProjectionServerModule {
+  clearClientUrlProjections(): void;
+  setClientUrlProjection(
+    referenceId: string,
+    projection: ClientUrlProjection,
+  ): void;
+}
+
+function hasDefaultExport(code: string): boolean {
+  let program: { body?: any[] };
+  try {
+    program = parseAst(code, { lang: "tsx" }) as { body?: any[] };
+  } catch {
+    return false;
+  }
+
+  for (const node of program.body ?? []) {
+    if (node?.type === "ExportDefaultDeclaration") return true;
+    if (node?.type !== "ExportNamedDeclaration") continue;
+    for (const specifier of node.specifiers ?? []) {
+      const exportedName =
+        specifier?.exported?.name ?? specifier?.exported?.value;
+      if (exportedName === "default") return true;
+    }
+  }
+  return false;
+}
+
+function normalizeSource(state: DiscoveryState, id: string): string {
+  const cleanId = id.split("?", 1)[0];
+  const absoluteId = isAbsolute(cleanId)
+    ? cleanId
+    : resolve(state.projectRoot, cleanId);
+  return normalizePath(absoluteId);
+}
+
+function referenceId(referenceKey: string): string {
+  return `${referenceKey}#default`;
+}
+
+function withoutReferenceQuery(reference: string): string {
+  const exportIndex = reference.lastIndexOf("#");
+  const moduleId =
+    exportIndex === -1 ? reference : reference.slice(0, exportIndex);
+  const exportName = exportIndex === -1 ? "" : reference.slice(exportIndex);
+  const queryIndex = moduleId.indexOf("?");
+  return `${queryIndex === -1 ? moduleId : moduleId.slice(0, queryIndex)}${exportName}`;
+}
+
+export function recordClientUrlsModule(
+  state: DiscoveryState,
+  code: string,
+  id: string,
+): void {
+  if (
+    !code.includes("clientUrls(") ||
+    !hasUseClientDirective(code) ||
+    !hasDefaultExport(code)
+  ) {
+    return;
+  }
+
+  const source = normalizeSource(state, id);
+  const projectRoot = normalizePath(resolve(state.projectRoot));
+  const relativeId = normalizePath(relative(projectRoot, source));
+  const outsideProject =
+    relativeId === ".." ||
+    relativeId.startsWith("../") ||
+    isAbsolute(relativeId);
+  const devReferenceKey = outsideProject ? `/@fs${source}` : `/${relativeId}`;
+
+  const sourceByReferenceId = (state.clientUrlSourceByReferenceId ??=
+    new Map());
+  sourceByReferenceId.set(referenceId(devReferenceKey), source);
+
+  const productionReferenceKeys = new Set([
+    hashRefKey(relativeId),
+    computeProductionHash(projectRoot, devReferenceKey),
+  ]);
+  for (const productionReferenceKey of productionReferenceKeys) {
+    sourceByReferenceId.set(referenceId(productionReferenceKey), source);
+  }
+}
+
+export function resolveClientUrlsSource(
+  state: DiscoveryState,
+  referenceId: string,
+): string | undefined {
+  return state.clientUrlSourceByReferenceId?.get(
+    withoutReferenceQuery(referenceId),
+  );
+}
+
+/**
+ * Deterministic filesystem discovery of clientUrls modules. Transform-based
+ * recording only sees modules that some environment actually loads — a
+ * clientUrls module not yet reachable from any transformed graph at discovery
+ * time (cold ordering, a mount added before its first import is served) would
+ * never be recorded and its include would fail with empty projections. Walking
+ * the project source (the same walk static route-type generation performs)
+ * makes recording independent of module-graph timing. The transform hooks
+ * still record too — they refresh dev HMR edits between scans.
+ */
+export function scanForClientUrlModules(state: DiscoveryState): void {
+  if (!state.projectRoot) return;
+  for (const filePath of findTsFiles(state.projectRoot, state.scanFilter)) {
+    let code: string;
+    try {
+      code = readFileSync(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+    recordClientUrlsModule(state, code, filePath);
+  }
+}
+
+function projectionError(
+  referenceId: string,
+  source: string | undefined,
+  message: string,
+  cause?: unknown,
+): Error {
+  const sourceDescription = source ? ` from source "${source}"` : "";
+  const errorMessage = `Cannot discover client URL projection for reference "${referenceId}"${sourceDescription}: ${message}`;
+  return cause === undefined
+    ? new Error(errorMessage)
+    : new Error(errorMessage, { cause });
+}
+
+/**
+ * Lenient pre-entry projection refresh. Re-serializes every RECORDED clientUrls
+ * module before the discovery pass imports the entry, so routers re-created by
+ * that import materialize against the CURRENT module contents.
+ *
+ * Scar: node-preset HMR served stale client-urls routes after a route-shape
+ * edit — the clientUrls module is an HMR-accepted client boundary in the rsc
+ * graph, and the strict registry-driven pass below only runs AFTER the entry
+ * import, so `.routes(reference)` materialized the previous pass's projection.
+ *
+ * Errors are deliberately swallowed per source (a module mid-edit keeps its
+ * last-known projection); the strict discoverClientUrlProjections() pass still
+ * surfaces real failures afterwards. No-ops on cold start (nothing recorded
+ * yet) and when the SSR runner is unavailable.
+ */
+export async function refreshRecordedClientUrlProjections(
+  state: DiscoveryState,
+  ssrEnv: ClientUrlSsrEnvironment | undefined,
+  serverMod: ClientUrlProjectionServerModule,
+): Promise<void> {
+  const sourceByReferenceId = state.clientUrlSourceByReferenceId;
+  if (
+    !sourceByReferenceId?.size ||
+    typeof ssrEnv?.runner?.import !== "function"
+  ) {
+    return;
+  }
+
+  const referenceIdsBySource = new Map<string, string[]>();
+  for (const [refId, source] of sourceByReferenceId) {
+    const ids = referenceIdsBySource.get(source);
+    if (ids) {
+      ids.push(refId);
+    } else {
+      referenceIdsBySource.set(source, [refId]);
+    }
+  }
+
+  for (const [source, referenceIds] of referenceIdsBySource) {
+    let definition: unknown;
+    try {
+      definition = (await ssrEnv.runner.import(source)).default;
+    } catch {
+      continue;
+    }
+    if (
+      (typeof definition !== "object" && typeof definition !== "function") ||
+      definition === null ||
+      (definition as { __brand?: unknown }).__brand !== "client-urls"
+    ) {
+      continue;
+    }
+    const projection = serializeClientUrlPatterns(
+      definition as ClientUrlPatterns,
+    );
+    debug?.(
+      "pre-entry refresh %s -> [%s]",
+      source,
+      projection.routes.map((route) => route.pattern).join(", "),
+    );
+    for (const referenceId of referenceIds) {
+      serverMod.setClientUrlProjection(referenceId, projection);
+      // The eager routes-manifest virtual module REPLAYS this state map
+      // (clearClientUrlProjections + set) whenever it re-evaluates — and the
+      // watcher's gen-file write invalidates it right before the entry import,
+      // so a stale map here would clobber the registry install above before
+      // the router materializes its mount. Keep both in sync.
+      state.clientUrlProjectionMap?.set(referenceId, projection);
+    }
+  }
+}
+
+/**
+ * Strict projection discovery over every RECORDED clientUrls module. Recorded
+ * modules — not router references — are the source of truth: include() mounts
+ * materialize lazily from the projection registry, so there is no router-level
+ * reference list to consult. Serializes every source before atomically
+ * installing the new projections (a failure preserves last-known state).
+ *
+ * A recorded source whose file no longer exists is dropped silently
+ * (recordClientUrlsModule never un-records, so deletions must self-heal here).
+ * A present-but-broken module is a hard error: it is part of the app graph.
+ */
+export async function discoverClientUrlProjections(
+  state: DiscoveryState,
+  ssrEnv: ClientUrlSsrEnvironment | undefined,
+  serverMod: ClientUrlProjectionServerModule,
+): Promise<void> {
+  scanForClientUrlModules(state);
+  const sourceByReferenceId = state.clientUrlSourceByReferenceId;
+  if (!sourceByReferenceId?.size) {
+    serverMod.clearClientUrlProjections();
+    state.clientUrlProjectionMap = new Map();
+    return;
+  }
+
+  const referenceIdsBySource = new Map<string, string[]>();
+  for (const [referenceId, source] of sourceByReferenceId) {
+    const ids = referenceIdsBySource.get(source);
+    if (ids) {
+      ids.push(referenceId);
+    } else {
+      referenceIdsBySource.set(source, [referenceId]);
+    }
+  }
+
+  if (typeof ssrEnv?.runner?.import !== "function") {
+    const [source, ids] = referenceIdsBySource.entries().next().value as [
+      string,
+      string[],
+    ];
+    throw projectionError(
+      ids[0],
+      source,
+      "the SSR module runner is unavailable",
+    );
+  }
+
+  const nextProjections = new Map<string, ClientUrlProjection>();
+  const removedSources: string[] = [];
+  for (const [source, referenceIds] of referenceIdsBySource) {
+    let module: Record<string, unknown>;
+    try {
+      module = await ssrEnv.runner.import(source);
+    } catch (cause) {
+      if (!existsSync(source)) {
+        removedSources.push(source);
+        continue;
+      }
+      throw projectionError(
+        referenceIds[0],
+        source,
+        "failed to import the source module",
+        cause,
+      );
+    }
+    const definition = module.default;
+    if (
+      (typeof definition !== "object" && typeof definition !== "function") ||
+      definition === null ||
+      (definition as { __brand?: unknown }).__brand !== "client-urls"
+    ) {
+      throw projectionError(
+        referenceIds[0],
+        source,
+        'the module default export must be created by clientUrls() and have __brand === "client-urls"',
+      );
+    }
+    const projection = serializeClientUrlPatterns(
+      definition as ClientUrlPatterns,
+    );
+    for (const referenceId of referenceIds) {
+      nextProjections.set(referenceId, projection);
+    }
+  }
+
+  for (const source of removedSources) {
+    for (const [referenceId, recorded] of sourceByReferenceId) {
+      if (recorded === source) sourceByReferenceId.delete(referenceId);
+    }
+  }
+
+  serverMod.clearClientUrlProjections();
+  for (const [id, projection] of nextProjections) {
+    serverMod.setClientUrlProjection(id, projection);
+  }
+  state.clientUrlProjectionMap = nextProjections;
+}

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);
+    },
+  };
+}