@rangojs/router 0.0.0-experimental.10 → 0.0.0-experimental.100

package/src/vite/discovery/gate-state.ts

@@ -0,0 +1,171 @@
+import type { Debugger } from "../debug.js";
+
+/**
+ * Manifest-readiness gate + rediscovery scheduler.
+ *
+ * Owns the four pieces of state that cooperate to keep
+ * `s.discoveryDone` (the promise the manifest virtual module's `load()`
+ * hook awaits) consistent across HMR fan-out:
+ *
+ *   - **gatePending**: a Promise has been issued and not yet resolved.
+ *     Workerd's manifest virtual module load() is blocked on it.
+ *   - **inProgress**: a refresh's work callback is currently executing.
+ *   - **queued**: a refresh was attempted while one was already in
+ *     flight; the active run consumes this in its `finally` and
+ *     recurses.
+ *   - **pendingEvents**: a route-file event has been received (gate
+ *     already reset) but the corresponding refresh's work hasn't started
+ *     yet — i.e. the debounce hasn't fired. Set in `noteRouteEvent`,
+ *     cleared at the start of each refresh cycle. Refresh's finally MUST
+ *     hold the gate if this is true even when `queued` is false,
+ *     otherwise an event whose debounce fires AFTER the active refresh
+ *     completes (the "tail-race" window) would observe a resolved gate.
+ *
+ * The HMR-event flow (cloudflare-stress repro):
+ *
+ *   t=0    Touch 1  → noteRouteEvent  → pendingEvents=true, beginGate
+ *                                      (gate1 pending)
+ *          → debounce 100ms
+ *   t=100  runRefreshCycle(work)      → clear pendingEvents, work starts
+ *   t=750  Touch 2  → noteRouteEvent  → pendingEvents=true (no-op gate)
+ *                                      → debounce fires at t=850
+ *   t=800  refresh A's finally        → queued=false, pendingEvents=true
+ *                                      → HOLD gate (don't resolve)
+ *   t=850  runRefreshCycle (debounce) → clear pendingEvents, work starts
+ *   t=1500 refresh B's finally        → queued=false, pendingEvents=false
+ *                                      → resolveGate (gate1 resolves)
+ *
+ * @internal Exported only for unit tests.
+ */
+export interface DiscoveryGate {
+  /**
+   * Reset the gate to a fresh pending Promise via `s.discoveryDone`.
+   * No-op when a gate is already pending — file watchers can fire
+   * multiple events for one save, and replacing the resolver would
+   * orphan the original promise (workerd's manifest load() would hang).
+   */
+  beginGate(): void;
+  /**
+   * Resolve the current pending gate. No-op when no gate is pending.
+   * Called at the tail of the last refresh cycle in a burst.
+   */
+  resolveGate(): void;
+  /**
+   * Record that a route-file event has arrived. Sets `pendingEvents`
+   * and begins the gate. Idempotent for both flags.
+   */
+  noteRouteEvent(): void;
+  /**
+   * Run one refresh cycle, managing queue + pending state around it.
+   * If a cycle is already in flight, sets `queued=true` and returns.
+   * Otherwise clears `pendingEvents`, runs `work`, and in `finally`:
+   *
+   *   - queued        → recurse, gate stays pending
+   *   - pendingEvents → hold gate (next debounced cycle resolves)
+   *   - neither       → resolveGate
+   */
+  runRefreshCycle(work: () => Promise<void>): Promise<void>;
+  /** Snapshot of internal state. Test-only. */
+  readonly state: () => Readonly<{
+    gatePending: boolean;
+    inProgress: boolean;
+    queued: boolean;
+    pendingEvents: boolean;
+  }>;
+}
+
+/** State container the gate writes `discoveryDone` into. */
+export interface GateOwner {
+  discoveryDone: Promise<void> | null | undefined;
+}
+
+export function createDiscoveryGate(
+  s: GateOwner,
+  debug?: Debugger,
+): DiscoveryGate {
+  let gatePending = false;
+  let gateResolver: () => void = () => {};
+  let inProgress = false;
+  let queued = false;
+  let pendingEvents = false;
+
+  const beginGate = (): void => {
+    if (gatePending) return;
+    s.discoveryDone = new Promise<void>((resolve) => {
+      gateResolver = resolve;
+    });
+    gatePending = true;
+  };
+
+  const resolveGate = (): void => {
+    if (!gatePending) return;
+    // Defer resolution while a refresh cycle is in flight or queued, or
+    // while an unprocessed route-file event is pending its debounce.
+    // Without this guard, cold-start's `discover().then(resolveGate)`
+    // could fire while an HMR-triggered runRefreshCycle is mid-flight,
+    // prematurely unblocking workerd's manifest load() against the
+    // stale cold-start gen. The active cycle's `finally` calls
+    // resolveGate again at the tail and finishes the resolution then.
+    if (inProgress || queued || pendingEvents) {
+      debug?.(
+        "hmr: resolveGate deferred — work in flight (inProgress=%s queued=%s pendingEvents=%s)",
+        inProgress,
+        queued,
+        pendingEvents,
+      );
+      return;
+    }
+    gatePending = false;
+    debug?.("hmr: discoveryDone resolved");
+    gateResolver();
+  };
+
+  const noteRouteEvent = (): void => {
+    pendingEvents = true;
+    beginGate();
+  };
+
+  const runRefreshCycle = async (work: () => Promise<void>): Promise<void> => {
+    if (inProgress) {
+      queued = true;
+      debug?.("hmr: rediscovery in flight — queued for a follow-up cycle");
+      return;
+    }
+    // Snapshot the current pendingEvents into "we're about to process";
+    // events arriving from now on re-set it.
+    pendingEvents = false;
+    inProgress = true;
+    try {
+      await work();
+    } finally {
+      inProgress = false;
+      if (queued) {
+        queued = false;
+        debug?.("hmr: consuming queued rediscovery");
+        runRefreshCycle(work).catch((err: unknown) => {
+          debug?.(
+            "hmr: queued cycle rejected — releasing gate (%s)",
+            err instanceof Error ? err.message : String(err),
+          );
+          // Belt-and-suspenders: even if the queued cycle's own try/catch
+          // missed something, ensure workerd doesn't hang.
+          resolveGate();
+        });
+      } else if (pendingEvents) {
+        debug?.(
+          "hmr: holding gate for pending events (debounce not yet fired)",
+        );
+      } else {
+        resolveGate();
+      }
+    }
+  };
+
+  return {
+    beginGate,
+    resolveGate,
+    noteRouteEvent,
+    runRefreshCycle,
+    state: () => ({ gatePending, inProgress, queued, pendingEvents }),
+  };
+}

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

@@ -0,0 +1,486 @@
+/**
+ * Prerender Collection
+ *
+ * Expands prerender routes into concrete URLs and renders them at build
+ * time. Also handles Static handler rendering for segment-level static
+ * generation.
+ */
+
+import { contextSet } from "../../context-var.js";
+import {
+  encodePathParam,
+  substituteRouteParams,
+  runWithConcurrency,
+  groupByConcurrency,
+  notifyOnError,
+  stageBuildAssetModule,
+} from "../utils/prerender-utils.js";
+import type { DiscoveryState } from "./state.js";
+import { createRangoDebugger, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.prerender);
+
+/**
+ * Expand prerender routes into concrete URLs and render them via the
+ * RSC runner. Stages asset modules and stores key-to-file entries in
+ * state.prerenderManifestEntries.
+ */
+export async function expandPrerenderRoutes(
+  state: DiscoveryState,
+  rscEnv: any,
+  registry: Map<string, any>,
+  allManifests: Array<{ id: string; manifest: any }>,
+): Promise<void> {
+  if (!state.opts?.enableBuildPrerender || !state.isBuildMode) return;
+
+  const overallStart = debug ? performance.now() : 0;
+  debug?.(
+    "expandPrerenderRoutes: start (%d router manifest(s))",
+    allManifests.length,
+  );
+
+  type PrerenderEntry = {
+    urlPath: string;
+    routeName: string;
+    concurrency: number;
+    buildVars?: Record<string, any>;
+    isPassthroughRoute?: boolean;
+  };
+  const entries: PrerenderEntry[] = [];
+
+  // Build a merged route map for getParams context reverse()
+  const allRoutes: Record<string, string> = {};
+  for (const { manifest: m } of allManifests) {
+    if (m.routeManifest) Object.assign(allRoutes, m.routeManifest);
+  }
+  const getParamsReverse = (name: string, params?: Record<string, string>) => {
+    const pattern = allRoutes[name];
+    if (!pattern) throw new Error(`Unknown route: "${name}"`);
+    if (!params) return pattern;
+    return substituteRouteParams(pattern, params);
+  };
+
+  let resolvedRoutes = 0;
+  let totalDynamic = 0;
+
+  // Count dynamic routes upfront for progress reporting
+  for (const { manifest } of allManifests) {
+    if (!manifest.prerenderRoutes) continue;
+    for (const routeName of manifest.prerenderRoutes) {
+      const pattern = manifest.routeManifest[routeName];
+      if (pattern && (pattern.includes(":") || pattern.includes("*"))) {
+        totalDynamic++;
+      }
+    }
+  }
+
+  // Periodic progress log so long getParams() calls don't look stalled
+  const paramsStart = performance.now();
+  const progressInterval =
+    totalDynamic > 0
+      ? setInterval(() => {
+          const elapsed = ((performance.now() - paramsStart) / 1000).toFixed(1);
+          console.log(
+            `[rsc-router] Resolving prerender params... ${resolvedRoutes}/${totalDynamic} routes (${elapsed}s)`,
+          );
+        }, 5000)
+      : undefined;
+
+  try {
+    for (const { manifest } of allManifests) {
+      if (!manifest.prerenderRoutes) continue;
+      const defs = manifest._prerenderDefs || {};
+      const passthroughSet = new Set(manifest.passthroughRoutes || []);
+      for (const routeName of manifest.prerenderRoutes) {
+        const pattern = manifest.routeManifest[routeName];
+        if (!pattern) continue;
+        const def = defs[routeName];
+        const isPassthroughRoute = passthroughSet.has(routeName);
+        const hasDynamic = pattern.includes(":") || pattern.includes("*");
+        if (!hasDynamic) {
+          // Static route: use pattern directly (strip trailing slash for URL)
+          entries.push({
+            urlPath: pattern.replace(/\/$/, "") || "/",
+            routeName,
+            concurrency: 1,
+            isPassthroughRoute,
+          });
+        } else {
+          // Dynamic route: call getParams() to enumerate param combinations
+          if (def?.getParams) {
+            const getParamsStart = debug ? performance.now() : 0;
+            try {
+              const buildVars: Record<string, any> = {};
+              const buildEnv = state.resolvedBuildEnv;
+              const getParamsCtx = {
+                build: true as const,
+                dev: !state.isBuildMode,
+                set: ((keyOrVar: any, value: any) => {
+                  contextSet(buildVars, keyOrVar, value);
+                }) as any,
+                reverse: getParamsReverse,
+                get env() {
+                  if (buildEnv !== undefined) return buildEnv;
+                  throw new Error(
+                    "[rsc-router] ctx.env is not available during build-time getParams(). " +
+                      "Configure buildEnv in your rango() plugin options to enable build-time env access.",
+                  );
+                },
+              };
+              const paramsList = await def.getParams(getParamsCtx);
+              debug?.(
+                "getParams %s -> %d params (%sms)",
+                routeName,
+                paramsList.length,
+                (performance.now() - getParamsStart).toFixed(1),
+              );
+              const concurrency = def.options?.concurrency ?? 1;
+              const hasBuildVars =
+                Object.keys(buildVars).length > 0 ||
+                Object.getOwnPropertySymbols(buildVars).length > 0;
+              for (const params of paramsList) {
+                let url = substituteRouteParams(
+                  pattern,
+                  params as Record<string, string>,
+                  encodePathParam,
+                );
+                // Anonymous wildcard fallback: use conventional keys if provided
+                if (url.includes("*")) {
+                  const wildcardValue =
+                    (params as Record<string, string>)["*"] ??
+                    (params as Record<string, string>).splat;
+                  if (wildcardValue !== undefined) {
+                    url = url.replace(
+                      /\*[^/]*$/,
+                      encodePathParam(wildcardValue),
+                    );
+                  }
+                }
+                entries.push({
+                  urlPath: url.replace(/\/$/, "") || "/",
+                  routeName,
+                  concurrency,
+                  ...(hasBuildVars ? { buildVars } : {}),
+                  isPassthroughRoute,
+                });
+              }
+              resolvedRoutes++;
+            } catch (err: any) {
+              resolvedRoutes++;
+              // Skip in getParams() skips the entire route
+              if (err.name === "Skip") {
+                console.log(
+                  `[rsc-router]   SKIP route "${routeName}" - ${err.message}`,
+                );
+                notifyOnError(
+                  registry,
+                  err,
+                  "prerender",
+                  routeName,
+                  undefined,
+                  true,
+                );
+                continue;
+              }
+              // Regular error: fail the build
+              console.error(
+                `[rsc-router] Failed to get params for prerender route "${routeName}": ${err.message}`,
+              );
+              notifyOnError(registry, err, "prerender", routeName);
+              throw err;
+            }
+          } else {
+            console.warn(
+              `[rsc-router] Dynamic prerender route "${routeName}" has no getParams(), skipping`,
+            );
+          }
+        }
+      }
+    }
+  } finally {
+    if (progressInterval) {
+      clearInterval(progressInterval);
+      const elapsed = ((performance.now() - paramsStart) / 1000).toFixed(1);
+      console.log(
+        `[rsc-router] Resolved prerender params: ${resolvedRoutes}/${totalDynamic} routes (${elapsed}s)`,
+      );
+    }
+  }
+
+  if (entries.length === 0) {
+    debug?.(
+      "no prerender entries (done in %sms)",
+      (performance.now() - overallStart).toFixed(1),
+    );
+    return;
+  }
+
+  // Determine the max concurrency for the log header
+  const maxConcurrency = Math.max(...entries.map((e) => e.concurrency));
+  const concurrencyNote =
+    maxConcurrency > 1 ? ` (concurrency: ${maxConcurrency})` : "";
+  console.log(
+    `[rsc-router] Pre-rendering ${entries.length} URL(s)${concurrencyNote}...`,
+  );
+  debug?.(
+    "prerender loop: %d entries, max concurrency %d",
+    entries.length,
+    maxConcurrency,
+  );
+
+  const { hashParams } = await rscEnv.runner.import("@rangojs/router/build");
+
+  const manifestEntries: Record<string, string> = {};
+  let doneCount = 0;
+  let skipCount = 0;
+  const startTotal = performance.now();
+
+  // Group entries by concurrency for batched rendering.
+  // Within each group, all entries share the same concurrency limit.
+  const groups = groupByConcurrency(entries);
+
+  for (const group of groups) {
+    await runWithConcurrency(
+      group.entries,
+      group.concurrency,
+      async (entry) => {
+        const startUrl = performance.now();
+        for (const [, routerInstance] of registry) {
+          if (!routerInstance.matchForPrerender) continue;
+          try {
+            const result = await routerInstance.matchForPrerender(
+              entry.urlPath,
+              {},
+              entry.buildVars,
+              entry.isPassthroughRoute,
+              state.resolvedBuildEnv,
+            );
+            if (!result) continue;
+
+            // Handler returned ctx.passthrough() — skip manifest entry
+            if (result.passthrough) {
+              const elapsed = (performance.now() - startUrl).toFixed(0);
+              console.log(
+                `[rsc-router]   PASS ${entry.urlPath.padEnd(40)} (${elapsed}ms) - live fallback`,
+              );
+              doneCount++;
+              break;
+            }
+
+            const paramHash = hashParams(result.params || {});
+            const mainKey = `${result.routeName}/${paramHash}`;
+            const mainValue = JSON.stringify({
+              segments: result.segments,
+              handles: result.handles,
+            });
+            manifestEntries[mainKey] = stageBuildAssetModule(
+              state.projectRoot,
+              "__pr",
+              mainValue,
+            );
+            if (result.interceptSegments?.length) {
+              const interceptKey = `${result.routeName}/${paramHash}/i`;
+              const interceptValue = JSON.stringify({
+                segments: [...result.segments, ...result.interceptSegments],
+                handles: {
+                  ...result.handles,
+                  ...(result.interceptHandles || {}),
+                },
+              });
+              manifestEntries[interceptKey] = stageBuildAssetModule(
+                state.projectRoot,
+                "__pr",
+                interceptValue,
+              );
+            }
+            const elapsed = (performance.now() - startUrl).toFixed(0);
+            console.log(
+              `[rsc-router]   OK   ${entry.urlPath.padEnd(40)} (${elapsed}ms)`,
+            );
+            doneCount++;
+            break;
+          } catch (err: any) {
+            if (err.name === "Skip") {
+              const elapsed = (performance.now() - startUrl).toFixed(0);
+              console.log(
+                `[rsc-router]   SKIP ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+              );
+              skipCount++;
+              notifyOnError(
+                registry,
+                err,
+                "prerender",
+                entry.routeName,
+                entry.urlPath,
+                true,
+              );
+              break;
+            }
+            // Regular error: log, notify, and fail the build
+            const elapsed = (performance.now() - startUrl).toFixed(0);
+            console.error(
+              `[rsc-router]   FAIL ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+            );
+            notifyOnError(
+              registry,
+              err,
+              "prerender",
+              entry.routeName,
+              entry.urlPath,
+            );
+            throw err;
+          }
+        }
+      },
+    );
+  }
+
+  const totalElapsed = (performance.now() - startTotal).toFixed(0);
+  if (doneCount > 0) {
+    state.prerenderManifestEntries = manifestEntries;
+  }
+  const parts = [`${doneCount} done`];
+  if (skipCount > 0) parts.push(`${skipCount} skipped`);
+  console.log(
+    `[rsc-router] Pre-render complete: ${parts.join(", ")} (${totalElapsed}ms total)`,
+  );
+  debug?.(
+    "expandPrerenderRoutes done: %d done, %d skipped, %sms (overall %sms)",
+    doneCount,
+    skipCount,
+    totalElapsed,
+    (performance.now() - overallStart).toFixed(1),
+  );
+}
+
+/**
+ * Render Static handlers at build time. Each Static handler is called
+ * with a synthetic BuildContext and its output is RSC-serialized.
+ * Stages asset modules and stores handlerId-to-file entries in
+ * state.staticManifestEntries.
+ */
+export async function renderStaticHandlers(
+  state: DiscoveryState,
+  rscEnv: any,
+  registry: Map<string, any>,
+): Promise<void> {
+  if (
+    !state.opts?.enableBuildPrerender ||
+    !state.isBuildMode ||
+    !state.resolvedStaticModules?.size
+  )
+    return;
+
+  const overallStart = debug ? performance.now() : 0;
+  debug?.(
+    "renderStaticHandlers: start (%d static module(s))",
+    state.resolvedStaticModules.size,
+  );
+
+  const manifestEntries: Record<string, string> = {};
+  let staticDone = 0;
+  let staticSkip = 0;
+  let totalStaticCount = 0;
+
+  // Count handlers for the log header
+  for (const [, exportNames] of state.resolvedStaticModules) {
+    totalStaticCount += exportNames.length;
+  }
+  const startStatic = performance.now();
+  console.log(
+    `[rsc-router] Rendering ${totalStaticCount} static handler(s)...`,
+  );
+
+  for (const [moduleId, exportNames] of state.resolvedStaticModules) {
+    let mod: any;
+    try {
+      mod = await rscEnv!.runner.import(moduleId);
+    } catch (err: any) {
+      console.error(
+        `[rsc-router] Failed to import static module ${moduleId}: ${err.message}`,
+      );
+      notifyOnError(registry, err, "static");
+      throw err;
+    }
+
+    for (const name of exportNames) {
+      const def = mod[name];
+      if (!def || def.__brand !== "staticHandler" || !def.$$id) continue;
+      // Passthrough handlers stay live in the bundle
+      if (def.options?.passthrough) continue;
+
+      const startHandler = performance.now();
+      let handled = false;
+      for (const [, routerInstance] of registry) {
+        if (!routerInstance.renderStaticSegment) continue;
+        try {
+          const result = await routerInstance.renderStaticSegment(
+            def.handler,
+            def.$$id,
+            (def as any).$$routePrefix,
+            state.resolvedBuildEnv,
+            !state.isBuildMode,
+          );
+          if (result) {
+            const hasHandles = Object.keys(result.handles).length > 0;
+            const exportValue = hasHandles
+              ? JSON.stringify(result)
+              : JSON.stringify(result.encoded);
+            manifestEntries[def.$$id] = stageBuildAssetModule(
+              state.projectRoot,
+              "__st",
+              exportValue,
+            );
+            const elapsed = (performance.now() - startHandler).toFixed(0);
+            console.log(
+              `[rsc-router]   OK   ${name.padEnd(40)} (${elapsed}ms)`,
+            );
+            staticDone++;
+            handled = true;
+            break;
+          }
+        } catch (err: any) {
+          if (err.name === "Skip") {
+            const elapsed = (performance.now() - startHandler).toFixed(0);
+            console.log(
+              `[rsc-router]   SKIP ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+            );
+            staticSkip++;
+            notifyOnError(registry, err, "static", undefined, undefined, true);
+            handled = true;
+            break;
+          }
+          // Regular error: log, notify, and fail the build
+          const elapsed = (performance.now() - startHandler).toFixed(0);
+          console.error(
+            `[rsc-router]   FAIL ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+          );
+          notifyOnError(registry, err, "static");
+          throw err;
+        }
+      }
+      if (!handled) {
+        console.warn(
+          `[rsc-router] No router could render static handler "${name}"`,
+        );
+      }
+    }
+  }
+
+  const totalStaticElapsed = (performance.now() - startStatic).toFixed(0);
+  if (staticDone > 0) {
+    state.staticManifestEntries = manifestEntries;
+  }
+  const staticParts = [`${staticDone} done`];
+  if (staticSkip > 0) staticParts.push(`${staticSkip} skipped`);
+  console.log(
+    `[rsc-router] Static render complete: ${staticParts.join(", ")} (${totalStaticElapsed}ms total)`,
+  );
+  debug?.(
+    "renderStaticHandlers done: %d done, %d skipped, %sms (overall %sms)",
+    staticDone,
+    staticSkip,
+    totalStaticElapsed,
+    (performance.now() - overallStart).toFixed(1),
+  );
+}