@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.141

package/src/vercel/tracing.ts

@@ -0,0 +1,88 @@
+/**
+ * Vercel OpenTelemetry tracing integration.
+ *
+ * Bridges the router's performance phases (request, middleware, action,
+ * loaders, handler, render, ssr) onto OpenTelemetry spans so they show up in
+ * Vercel's trace waterfall next to the platform's automatic spans, with correct
+ * nesting. Vercel exposes tracing through OpenTelemetry (not a native import-free
+ * API like Cloudflare), so this is a thin convenience over `createOTelTracing`:
+ * it reads the global OTel tracer that `@vercel/otel`'s `registerOTel()` installs.
+ *
+ * Usage (vercel preset). A Rango/Vite app does NOT auto-load `instrumentation.ts`
+ * the way Next.js does, so export the tracing config from there and import it —
+ * the import is what runs `registerOTel()`. A standalone `registerOTel()` that
+ * nothing imports is a silent no-op (the tracer never registers, spans drop):
+ *
+ *   // instrumentation.ts
+ *   import { registerOTel } from "@vercel/otel";
+ *   import { createVercelTracing } from "@rangojs/router/vercel";
+ *   registerOTel({ serviceName: "my-app" });
+ *   export const tracing = createVercelTracing();
+ *
+ *   // router.tsx — importing `tracing` runs instrumentation.ts (and registerOTel)
+ *   import { createRouter } from "@rangojs/router";
+ *   import { tracing } from "./instrumentation.js";
+ *   export const router = createRouter({ tracing });
+ *
+ * Two runtime caveats inherited from the platform:
+ *   - Node.js runtime only. Vercel custom spans are unsupported on the Edge
+ *     runtime; `startActiveSpan` also needs an AsyncLocalStorage context manager
+ *     (which @vercel/otel configures on Node) for spans to nest correctly.
+ *   - `registerOTel()` must run before the first request. Reading the tracer via
+ *     `trace.getTracer` here is safe even if it runs first — the API's proxy
+ *     tracer delegates to the provider once registered — but no provider means
+ *     every span is a no-op (the request behaves exactly as if tracing were off).
+ *
+ * Whether spans are actually exported is governed by your OTel setup / Vercel
+ * tracing destination, not by this adapter.
+ */
+
+import { trace } from "@opentelemetry/api";
+import {
+  createOTelTracing,
+  type OTelActiveSpanTracer,
+} from "../router/telemetry-otel.js";
+import type {
+  RouterTracingConfig,
+  TracePhaseToggles,
+} from "../router/tracing.js";
+
+/** Options for createVercelTracing. */
+export interface VercelTracingOptions {
+  /** Master switch. Defaults to true. */
+  enabled?: boolean;
+  /** Per-phase span toggles. Omitted phases default to enabled. */
+  spans?: TracePhaseToggles;
+  /**
+   * OTel instrumentation-scope name passed to `trace.getTracer()`. Defaults to
+   * `"rango"`. Ignored when `tracer` is provided.
+   */
+  tracerName?: string;
+  /**
+   * Explicit tracer override. Defaults to the global OTel tracer
+   * (`trace.getTracer(tracerName)`) — the provider `@vercel/otel`'s
+   * `registerOTel()` installs. Pass this to bridge onto a tracer you own.
+   */
+  tracer?: OTelActiveSpanTracer;
+}
+
+/**
+ * Create the tracing config for a Vercel router. Pass the result to
+ * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
+ * action, loaders, handler, render, and ssr phases; pass `spans` to turn
+ * individual phases off.
+ *
+ * @see createOTelTracing (`@rangojs/router`) for the underlying adapter on any
+ *   platform with an OpenTelemetry SDK.
+ * @see createCloudflareTracing (`@rangojs/router/cloudflare`) for the same slot
+ *   using Cloudflare Workers native custom spans.
+ */
+export function createVercelTracing(
+  options: VercelTracingOptions = {},
+): RouterTracingConfig {
+  const { tracerName = "rango", tracer, enabled, spans } = options;
+  return createOTelTracing(tracer ?? trace.getTracer(tracerName), {
+    enabled,
+    spans,
+  });
+}

package/src/vite/debug.ts

@@ -0,0 +1,185 @@
+/**
+ * Debug logging for the Rango Vite plugin.
+ *
+ * Thin wrapper over the `debug` package (the same one Vite uses for its
+ * own `vite:*` namespaces). Enable with either:
+ *
+ *     DEBUG='rango:*' vite dev
+ *     vite --debug rango:*          # vite prepends `vite:`, we bridge it
+ *
+ * Returns `undefined` when no matching namespace is enabled, so call sites
+ * can guard expensive diagnostics with a simple truthiness check:
+ *
+ *     const debug = createRangoDebugger(NS.routes);
+ *     if (debug) debug("built manifest (%d routes) in %dms", n, ms);
+ *
+ * Back-compat: INTERNAL_RANGO_DEBUG=1 still enables all rango namespaces.
+ *
+ * Vite CLI note: `vite --debug <feat>` rewrites to `DEBUG=vite:<feat>` — it
+ * always prefixes with `vite:` and cannot enable bare `rango:*` namespaces.
+ * We work around this by registering a shadow `vite:rango:*` instance for
+ * each debugger, so either invocation works.
+ */
+
+import debugFactory from "debug";
+
+/**
+ * Canonical debug namespaces. Import as `NS.xxx` instead of string literals
+ * so typos become type errors and the full set lives in one place.
+ */
+export const NS = {
+  config: "rango:config",
+  discovery: "rango:discovery",
+  routes: "rango:routes",
+  prerender: "rango:prerender",
+  build: "rango:build",
+  dev: "rango:dev",
+  transform: "rango:transform",
+  chunks: "rango:chunks",
+} as const;
+
+// Back-compat: the legacy INTERNAL_RANGO_DEBUG env var enabled per-site
+// console.logs in this plugin. Map it to `rango:*` so those call sites can
+// be migrated to the `debug` pipeline without breaking existing setups.
+// Uses debug.enable() rather than mutating process.env because the `debug`
+// package already snapshotted DEBUG when it was imported above.
+if (process.env.INTERNAL_RANGO_DEBUG) {
+  const existing = debugFactory.disable();
+  debugFactory.enable(existing ? `${existing},rango:*` : "rango:*");
+}
+
+export type Debugger = (formatter: string, ...args: unknown[]) => void;
+
+export function createRangoDebugger(namespace: string): Debugger | undefined {
+  const primary = debugFactory(namespace);
+  // Shadow namespace so `vite --debug rango:*` (which expands to
+  // DEBUG=vite:rango:*) and `vite --debug` (DEBUG=vite:*) both pick us up.
+  const shadow = debugFactory(`vite:${namespace}`);
+  if (primary.enabled) return primary as Debugger;
+  if (shadow.enabled) return shadow as Debugger;
+  return undefined;
+}
+
+/**
+ * Measure an async block and log its duration via `debug`. No-ops (still
+ * runs `fn`) when the namespace is disabled, so production cost is a single
+ * `.enabled` check per call.
+ *
+ *     await timed(debug, "discover routers", () => discoverRouters(state));
+ */
+export async function timed<T>(
+  debug: Debugger | undefined,
+  label: string,
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  if (!debug) return await fn();
+  const start = performance.now();
+  try {
+    return await fn();
+  } finally {
+    debug("%s (%sms)", label, (performance.now() - start).toFixed(1));
+  }
+}
+
+/**
+ * Synchronous variant of `timed`. Use for sync call sites — wrapping them
+ * with the async `timed` would create a floating promise that discards any
+ * throw, bypassing the surrounding try/catch.
+ */
+export function timedSync<T>(
+  debug: Debugger | undefined,
+  label: string,
+  fn: () => T,
+): T {
+  if (!debug) return fn();
+  const start = performance.now();
+  try {
+    return fn();
+  } finally {
+    debug("%s (%sms)", label, (performance.now() - start).toFixed(1));
+  }
+}
+
+/**
+ * Aggregate counter for high-frequency call sites (typically Vite
+ * `transform` hooks that run on many files). Per-call logging would
+ * drown real signal; this collects totals and reports once on flush.
+ *
+ *     const counter = createCounter(debug, "use-cache-transform");
+ *     // inside transform():
+ *     return counter?.time(id, () => doWork()) ?? doWork();
+ *     // or manually:
+ *     counter?.record(id, ms);
+ *     // flush on buildEnd (counter resets, so multi-env builds each get
+ *     // their own summary line):
+ *     counter?.flush();
+ *
+ * Returns `undefined` when the namespace is disabled so call sites pay
+ * nothing when off.
+ */
+export interface Counter {
+  record(file: string, ms: number): void;
+  /**
+   * Convenience: time a sync or async block and record it. Propagates
+   * throws; records regardless of outcome. Returns the function's result.
+   */
+  time<T>(file: string, fn: () => T): T;
+  time<T>(file: string, fn: () => Promise<T>): Promise<T>;
+  flush(): void;
+}
+
+export function createCounter(
+  debug: Debugger | undefined,
+  label: string,
+): Counter | undefined {
+  if (!debug) return undefined;
+  let n = 0;
+  let totalMs = 0;
+  let slowestMs = 0;
+  let slowestFile = "";
+  const record = (file: string, ms: number): void => {
+    n++;
+    totalMs += ms;
+    if (ms > slowestMs) {
+      slowestMs = ms;
+      slowestFile = file;
+    }
+  };
+  return {
+    record,
+    time<T>(file: string, fn: () => T | Promise<T>): T | Promise<T> {
+      const start = performance.now();
+      let out: T | Promise<T>;
+      try {
+        out = fn();
+      } catch (err) {
+        record(file, performance.now() - start);
+        throw err;
+      }
+      if (out && typeof (out as any).then === "function") {
+        return (out as Promise<T>).finally(() =>
+          record(file, performance.now() - start),
+        );
+      }
+      record(file, performance.now() - start);
+      return out;
+    },
+    flush(): void {
+      if (n === 0) return;
+      debug(
+        "%s: %d files, %sms total, slowest %sms %s",
+        label,
+        n,
+        totalMs.toFixed(1),
+        slowestMs.toFixed(1),
+        slowestFile,
+      );
+      // Reset so buildEnd firing once per environment (Vite 6+ multi-env)
+      // gives one log line per env rather than silently dropping later data.
+      n = 0;
+      totalMs = 0;
+      slowestMs = 0;
+      slowestFile = "";
+    },
+  };
+}

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

@@ -0,0 +1,182 @@
+/**
+ * Bundle Post-Processing
+ *
+ * Handles handler code eviction from prerender/static chunks and
+ * injection of collected prerender/static data into the RSC entry bundle.
+ */
+
+import { resolve } from "node:path";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { evictHandlerCode } from "../utils/bundle-analysis.js";
+import { copyStagedBuildAssets } from "../utils/prerender-utils.js";
+import { jsonParseExpression } from "../utils/manifest-utils.js";
+import type { DiscoveryState } from "./state.js";
+
+/**
+ * Post-process the RSC bundle: evict handler code and inject
+ * prerender/static data as importable asset modules.
+ */
+export function postprocessBundle(state: DiscoveryState): void {
+  const hasPrerenderData =
+    state.prerenderManifestEntries &&
+    Object.keys(state.prerenderManifestEntries).length > 0;
+  const hasStaticData =
+    state.staticManifestEntries &&
+    Object.keys(state.staticManifestEntries).length > 0;
+  if (!hasPrerenderData && !hasStaticData) return;
+
+  // Find RSC entry (recorded in generateBundle, fallback to dist/rsc/index.js)
+  const rscEntryPath = resolve(
+    state.projectRoot,
+    "dist/rsc",
+    state.rscEntryFileName ?? "index.js",
+  );
+
+  // 1. Evict handler code from whichever chunks contain handler exports.
+  // 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
+  // start of each generateBundle pass so only production data is used here.
+  const evictionTargets: Array<{
+    infos: Iterable<import("./state.js").ChunkInfo>;
+    fnName: string;
+    brand: string;
+    label: string;
+  }> = [
+    {
+      infos: state.handlerChunkInfoMap.values(),
+      fnName: "Prerender",
+      brand: "prerenderHandler",
+      label: "handler code from RSC bundle",
+    },
+    {
+      infos: state.staticHandlerChunkInfoMap.values(),
+      fnName: "Static",
+      brand: "staticHandler",
+      label: "static handler code",
+    },
+  ];
+
+  for (const target of evictionTargets) {
+    for (const info of target.infos) {
+      const chunkPath = resolve(state.projectRoot, "dist/rsc", info.fileName);
+      try {
+        const code = readFileSync(chunkPath, "utf-8");
+        const result = evictHandlerCode(
+          code,
+          info.exports,
+          target.fnName,
+          target.brand,
+        );
+        if (result) {
+          writeFileSync(chunkPath, result.code);
+          const savedKB = (result.savedBytes / 1024).toFixed(1);
+          console.log(
+            `[rango] Evicted ${target.label} (${savedKB} KB saved): ${info.fileName}`,
+          );
+        }
+      } catch (replaceErr: any) {
+        console.warn(
+          `[rango] Failed to evict ${target.label}: ${replaceErr.message}`,
+        );
+      }
+    }
+  }
+  state.handlerChunkInfoMap.clear();
+  state.staticHandlerChunkInfoMap.clear();
+
+  // 2. Write prerender data as separate importable asset modules
+  // and inject a lazy manifest loader into the RSC entry.
+  if (hasPrerenderData && existsSync(rscEntryPath)) {
+    const rscCode = readFileSync(rscEntryPath, "utf-8");
+    // Check for the specific injection marker to avoid double-injection.
+    if (!rscCode.includes("__prerender-manifest.js")) {
+      try {
+        let totalBytes = copyStagedBuildAssets(
+          state.projectRoot,
+          Object.values(state.prerenderManifestEntries!),
+        );
+
+        const manifestMap: Record<string, string> = {};
+        for (const [key, assetFileName] of Object.entries(
+          state.prerenderManifestEntries!,
+        )) {
+          manifestMap[key] = `./assets/${assetFileName}`;
+        }
+
+        const manifestCode = [
+          `const m=${jsonParseExpression(manifestMap)};`,
+          `export function loadPrerenderAsset(s){return import(s)}`,
+          `export default m;`,
+          "",
+        ].join("\n");
+        const manifestPath = resolve(
+          state.projectRoot,
+          "dist/rsc/__prerender-manifest.js",
+        );
+        writeFileSync(manifestPath, manifestCode);
+        totalBytes += Buffer.byteLength(manifestCode);
+
+        const injection = `globalThis.__loadPrerenderManifestModule = () => import("./__prerender-manifest.js");\n`;
+        writeFileSync(rscEntryPath, injection + rscCode);
+
+        const totalKB = (totalBytes / 1024).toFixed(1);
+        console.log(
+          `[rango] Wrote prerender assets (${totalKB} KB total, ${Object.keys(state.prerenderManifestEntries!).length} entries)`,
+        );
+      } catch (err: any) {
+        throw new Error(
+          `[rango] Failed to write prerender assets: ${err.message}`,
+        );
+      }
+    }
+  }
+
+  // 3. Write static handler data as separate importable asset modules
+  // and inject a __STATIC_MANIFEST import into the RSC entry.
+  if (hasStaticData && existsSync(rscEntryPath)) {
+    const rscCode = readFileSync(rscEntryPath, "utf-8");
+    if (!rscCode.includes("__static-manifest.js")) {
+      try {
+        const manifestEntries: string[] = [];
+        let totalBytes = copyStagedBuildAssets(
+          state.projectRoot,
+          Object.values(state.staticManifestEntries!),
+        );
+
+        for (const [handlerId, assetFileName] of Object.entries(
+          state.staticManifestEntries!,
+        )) {
+          manifestEntries.push(
+            `${JSON.stringify(handlerId)}:()=>import("./assets/${assetFileName}")`,
+          );
+        }
+
+        // Set the global inside the manifest module so it is assigned
+        // during module evaluation (before dependent modules like
+        // segment-resolution.ts run their top-level initializers).
+        const manifestCode = `const m={${manifestEntries.join(",")}};globalThis.__STATIC_MANIFEST=m;export default m;\n`;
+        const manifestPath = resolve(
+          state.projectRoot,
+          "dist/rsc/__static-manifest.js",
+        );
+        writeFileSync(manifestPath, manifestCode);
+        totalBytes += Buffer.byteLength(manifestCode);
+
+        // The import ensures the manifest module is evaluated early.
+        // The global is already set inside the module itself.
+        const injection = `import "./__static-manifest.js";\n`;
+        writeFileSync(rscEntryPath, injection + rscCode);
+
+        const totalKB = (totalBytes / 1024).toFixed(1);
+        console.log(
+          `[rango] Wrote static assets (${totalKB} KB total, ${Object.keys(state.staticManifestEntries!).length} entries)`,
+        );
+      } catch (err: any) {
+        throw new Error(
+          `[rango] Failed to write static assets: ${err.message}`,
+        );
+      }
+    }
+  }
+}