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

package/src/vite/plugins/version-plugin.ts

@@ -0,0 +1,263 @@
+import { parseAst, type Plugin } from "vite";
+import { VIRTUAL_IDS, getVirtualVersionContent } from "./virtual-entries.js";
+import { hasUseClientDirective } from "../utils/directive-prologue.js";
+
+interface ClientModuleSignature {
+  key: string;
+}
+
+function isCodeModule(id: string): boolean {
+  return /\.(tsx?|jsx?)($|\?)/.test(id);
+}
+
+function normalizeModuleId(id: string): string {
+  return id.split("?", 1)[0];
+}
+
+function getClientModuleSignature(
+  source: string,
+): ClientModuleSignature | undefined {
+  // Same leading-directive sniff the rango HMR plugin uses (shared helper, so the
+  // two agree on what counts as a client module). A parse failure yields false.
+  if (!hasUseClientDirective(source)) return undefined;
+
+  let program: any;
+  try {
+    program = parseAst(source, { lang: "tsx" });
+  } catch {
+    return undefined;
+  }
+
+  const exports = new Set<string>();
+  let hasDefault = false;
+  let hasExportAll = false;
+
+  const collectBindingNames = (pattern: any) => {
+    if (!pattern) return;
+    if (pattern.type === "Identifier") {
+      exports.add(pattern.name);
+    } else if (pattern.type === "ObjectPattern") {
+      for (const prop of pattern.properties ?? []) {
+        if (prop?.type === "RestElement") {
+          collectBindingNames(prop.argument);
+        } else {
+          collectBindingNames(prop?.value);
+        }
+      }
+    } else if (pattern.type === "ArrayPattern") {
+      for (const el of pattern.elements ?? []) {
+        if (el?.type === "RestElement") {
+          collectBindingNames(el.argument);
+        } else {
+          collectBindingNames(el);
+        }
+      }
+    }
+  };
+
+  const collectDeclarationNames = (declaration: any) => {
+    if (!declaration) return;
+    if (declaration.type === "VariableDeclaration") {
+      for (const decl of declaration.declarations ?? []) {
+        collectBindingNames(decl?.id);
+      }
+      return;
+    }
+    collectBindingNames(declaration.id);
+  };
+
+  for (const node of program.body ?? []) {
+    if (node?.type === "ExportDefaultDeclaration") {
+      hasDefault = true;
+      continue;
+    }
+    if (node?.type === "ExportAllDeclaration") {
+      hasExportAll = true;
+      continue;
+    }
+    if (node?.type !== "ExportNamedDeclaration") continue;
+
+    collectDeclarationNames(node.declaration);
+
+    for (const specifier of node.specifiers ?? []) {
+      const exportedName =
+        specifier?.exported?.name ?? specifier?.exported?.value;
+      if (exportedName === "default") {
+        hasDefault = true;
+      } else if (typeof exportedName === "string") {
+        exports.add(exportedName);
+      }
+    }
+  }
+
+  return {
+    key: JSON.stringify({
+      default: hasDefault,
+      exportAll: hasExportAll,
+      exports: [...exports].sort(),
+    }),
+  };
+}
+
+/**
+ * Plugin providing rsc-router:version virtual module.
+ * Exports VERSION that changes when RSC modules change (dev) or at build time (production).
+ *
+ * The version is used for:
+ * 1. Cache invalidation - CFCacheStore uses VERSION to invalidate stale cache
+ * 2. Version mismatch detection - client sends version, server reloads on mismatch
+ *
+ * In dev mode, the version updates when:
+ * - Server starts (initial version)
+ * - RSC modules change via HMR (triggers version module invalidation)
+ *
+ * Client-only HMR changes don't update the version since they don't affect
+ * server-rendered content or cached RSC payloads.
+ * @internal
+ */
+export function createVersionPlugin(): Plugin {
+  // Generate version at plugin creation time (build/server start)
+  const buildVersion = Date.now().toString(16);
+  let currentVersion = buildVersion;
+  let isDev = false;
+  let server: any = null;
+  let resolvedCacheDir: string | undefined;
+  const clientModuleSignatures = new Map<string, ClientModuleSignature>();
+
+  let versionCounter = 0;
+  const bumpVersion = (reason: string) => {
+    currentVersion = Date.now().toString(16) + String(++versionCounter);
+    console.log(`[rango] ${reason}, version updated: ${currentVersion}`);
+
+    const rscEnv = server?.environments?.rsc;
+    const versionMod = rscEnv?.moduleGraph?.getModuleById(
+      "\0" + VIRTUAL_IDS.version,
+    );
+    if (versionMod) {
+      rscEnv.moduleGraph.invalidateModule(versionMod);
+    }
+  };
+
+  return {
+    name: "@rangojs/router:version",
+    enforce: "pre",
+
+    configResolved(config) {
+      isDev = config.command === "serve";
+      resolvedCacheDir = config.cacheDir
+        ? String(config.cacheDir).replace(/\\/g, "/")
+        : undefined;
+    },
+
+    configureServer(devServer) {
+      server = devServer;
+
+      devServer.watcher.on("unlink", (filePath) => {
+        if (!isDev) return;
+        if (!clientModuleSignatures.has(filePath)) return;
+        clientModuleSignatures.delete(filePath);
+        bumpVersion("Client module removed");
+      });
+    },
+
+    resolveId(id) {
+      if (id === VIRTUAL_IDS.version) {
+        return "\0" + id;
+      }
+      return null;
+    },
+
+    load(id) {
+      if (id === "\0" + VIRTUAL_IDS.version) {
+        return getVirtualVersionContent(currentVersion);
+      }
+      return null;
+    },
+
+    transform(code, id) {
+      if (!isDev || !isCodeModule(id)) return null;
+      const normalizedId = normalizeModuleId(id);
+      if (
+        !code.includes("use client") &&
+        !clientModuleSignatures.has(normalizedId)
+      ) {
+        return null;
+      }
+
+      const signature = getClientModuleSignature(code);
+      if (signature) {
+        clientModuleSignatures.set(normalizedId, signature);
+      } else {
+        clientModuleSignatures.delete(normalizedId);
+      }
+      return null;
+    },
+
+    async hotUpdate(ctx) {
+      if (!isDev) return;
+
+      const isRscModule = this.environment?.name === "rsc";
+
+      if (!isRscModule) return;
+
+      if (isViteDepCachePath(ctx.file, resolvedCacheDir)) return;
+
+      if (
+        ctx.modules.length === 1 &&
+        ctx.modules[0].id === "\0" + VIRTUAL_IDS.version
+      ) {
+        return;
+      }
+
+      if (isCodeModule(ctx.file)) {
+        const filePath = normalizeModuleId(ctx.file);
+        const previousSignature = clientModuleSignatures.get(filePath);
+        try {
+          const source = await ctx.read();
+          const nextSignature = getClientModuleSignature(source);
+          if (nextSignature) {
+            clientModuleSignatures.set(filePath, nextSignature);
+            if (
+              previousSignature &&
+              previousSignature.key === nextSignature.key
+            ) {
+              return;
+            }
+          } else {
+            clientModuleSignatures.delete(filePath);
+            if (!previousSignature) {
+              if (ctx.modules.length === 0) return;
+            }
+          }
+        } catch {}
+      } else {
+        if (ctx.modules.length === 0) return;
+      }
+
+      bumpVersion("RSC module changed");
+    },
+  };
+}
+
+export function isViteDepCachePath(
+  filePath: string | undefined,
+  cacheDir?: string,
+): boolean {
+  if (!filePath) return false;
+  const normalized = filePath.replace(/\\/g, "/");
+
+  if (cacheDir) {
+    const normalizedCacheDir = cacheDir.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (
+      normalized === normalizedCacheDir ||
+      normalized.startsWith(normalizedCacheDir + "/")
+    ) {
+      return true;
+    }
+  }
+
+  return (
+    /\/node_modules\/\.vite[^/]*\//.test(normalized) ||
+    normalized.includes("/.vite-isolated/")
+  );
+}

package/src/vite/plugins/virtual-entries.ts

@@ -0,0 +1,234 @@
+export const VIRTUAL_ENTRY_BROWSER: string = `
+import {
+  createFromReadableStream,
+  createFromFetch,
+  setServerCallback,
+  encodeReply,
+  createTemporaryReferenceSet,
+} from "@rangojs/router/internal/deps/browser";
+import { createElement, StrictMode } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { rscStream } from "@rangojs/router/internal/deps/html-stream-client";
+import { initBrowserApp, Rango } from "@rangojs/router/browser";
+
+async function initializeApp() {
+  const deps = {
+    createFromFetch,
+    createFromReadableStream,
+    encodeReply,
+    setServerCallback,
+    createTemporaryReferenceSet,
+  };
+
+  // initBrowserApp resolves the initial payload and returns the browser app
+  // context, including strictMode (default true) from createRouter. StrictMode
+  // is the default; createRouter({ strictMode: false }) ships the opt-out in the
+  // payload metadata. StrictMode emits no DOM, so toggling never changes markup.
+  const { strictMode } = await initBrowserApp({ rscStream, deps });
+
+  const app = createElement(Rango);
+  hydrateRoot(
+    document,
+    strictMode === false ? app : createElement(StrictMode, null, app)
+  );
+}
+
+initializeApp().catch(console.error);
+`.trim();
+
+export const VIRTUAL_ENTRY_SSR: string = `
+import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
+import { renderToReadableStream, resume } from "react-dom/server.edge";
+import { prerender } from "react-dom/static.edge";
+import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
+import {
+  createSSRHandler,
+  createShellCaptureHandler,
+  createShellResumeHandler,
+} from "@rangojs/router/ssr";
+
+export const renderHTML = createSSRHandler({
+  createFromReadableStream,
+  renderToReadableStream,
+  injectRSCPayload,
+  loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+});
+
+export const captureShellHTML = createShellCaptureHandler({
+  createFromReadableStream,
+  renderToReadableStream,
+  injectRSCPayload,
+  prerender,
+  resume,
+  loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+});
+
+export const resumeShellHTML = createShellResumeHandler({
+  createFromReadableStream,
+  renderToReadableStream,
+  injectRSCPayload,
+  prerender,
+  resume,
+  loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+});
+`.trim();
+
+/**
+ * Virtual modules an RSC entry must import at startup to register the data the
+ * request handler needs before the first request arrives:
+ *
+ * - routes-manifest: the pre-generated route map so href()/matching work on a
+ *   cold start (full map in build, in-memory no-op in dev).
+ * - loader-manifest: setLoaderImports() for fetchable loaders. Critical for
+ *   serverless/multi-process deployments and for fetchable loaders reachable
+ *   only through a client component — without it those loaders are never
+ *   registered for the _rsc_loader endpoint and fail in production.
+ *
+ * Single source of truth: both the generated virtual RSC entry below and the
+ * custom-entry injector (version-injector) consume this list, so a new
+ * bootstrap manifest cannot be added to one path and forgotten on the other.
+ * That exact drift (loader-manifest present here but missing from the injector)
+ * is what left fetchable loaders unresolved on custom worker entries.
+ */
+export const RSC_ENTRY_BOOTSTRAP_IMPORTS: readonly string[] = [
+  "virtual:rsc-router/routes-manifest",
+  "virtual:rsc-router/loader-manifest",
+];
+
+export function getVirtualEntryRSC(routerPath: string): string {
+  const bootstrapImports = RSC_ENTRY_BOOTSTRAP_IMPORTS.map(
+    (id) => `import "${id}";`,
+  ).join("\n");
+  return `
+import {
+  renderToReadableStream,
+  decodeReply,
+  createTemporaryReferenceSet,
+  loadServerAction,
+  decodeAction,
+  decodeFormState,
+} from "@rangojs/router/internal/deps/rsc";
+import { router } from "${routerPath}";
+import { createRSCHandler } from "@rangojs/router/internal/rsc-handler";
+import { VERSION } from "@rangojs/router:version";
+
+// Startup bootstrap imports (routes + loader manifests). See
+// RSC_ENTRY_BOOTSTRAP_IMPORTS — the same list the custom-entry injector uses.
+${bootstrapImports}
+
+// Lazily create the handler on first request so that ESM live bindings
+// have resolved by the time we read \`router\`. During HMR the module may
+// re-evaluate before router.tsx finishes, leaving the import undefined.
+let _handler;
+export default function handler(request, env) {
+  if (!_handler) {
+    _handler = createRSCHandler({
+      router,
+      version: VERSION,
+      // Forward the router's CSP nonce provider. createRSCHandler reads the
+      // provider only from options.nonce; without this, createRouter({ nonce })
+      // is silently dropped on the Node preset (the Cloudflare path wires it via
+      // router.fetch). router.nonce is undefined when unconfigured, a safe no-op.
+      nonce: router.nonce,
+      deps: {
+        renderToReadableStream,
+        decodeReply,
+        createTemporaryReferenceSet,
+        loadServerAction,
+        decodeAction,
+        decodeFormState,
+      },
+      loadSSRModule: () =>
+        import.meta.viteRsc.loadModule("ssr", "index"),
+    });
+  }
+  return _handler(request, env);
+}
+`.trim();
+}
+
+export function getVirtualEntryRSCHost(hostEntryPath: string): string {
+  return `
+import * as __hostEntry from "${hostEntryPath}";
+import { isNoRouteMatchError } from "@rangojs/router/host";
+
+// Register every sub-app's fetchable loaders + route manifests at startup, same
+// as the single-router entry. Discovery's host fallback populates these for all
+// mounted sub-apps, so the aggregate manifests cover the whole host tree.
+import "virtual:rsc-router/loader-manifest";
+import "virtual:rsc-router/routes-manifest";
+
+// The host entry module must export the HostRouter instance (createHostRouter()),
+// as a default export or a named \`hostRouter\`/\`router\` export. A Cloudflare-style
+// \`export default { fetch }\` object is not a HostRouter and is rejected (on first
+// request; see the lazy resolution below).
+// We require BOTH .match() and .host(): a regular createRouter() also exposes
+// .match(), so matching on .match() alone would accept an ordinary router and then
+// return its MatchResult (not a Response) at runtime. .host() is unique to a
+// HostRouter, so it disambiguates a mistaken \`hostRouter\` path.
+// Exports are read dynamically (m[name]) so Rollup does not emit IMPORT_IS_UNDEFINED
+// warnings for the named exports a default-only host module legitimately omits.
+const __resolveHostRouter = (m) => {
+  for (const name of ["default", "hostRouter", "router"]) {
+    const candidate = m[name];
+    if (
+      candidate &&
+      typeof candidate.match === "function" &&
+      typeof candidate.host === "function"
+    )
+      return candidate;
+  }
+  return undefined;
+};
+
+// Resolve + validate the HostRouter lazily on first request, mirroring the
+// single-router entry's \`_handler\`. During HMR the host module can re-evaluate
+// before its createHostRouter() export has resolved; validating at module-
+// evaluation time would then throw a spurious "must export a HostRouter" error
+// overlay for a perfectly valid app. Resolving on first request lets the live
+// binding settle first.
+let _hostRouter;
+
+// input = { env, ctx } from the launcher / node server. The host router threads
+// it unchanged to each matched sub-app's handler and cache factory.
+// On node/vercel rango owns this entry, so there is no user worker to translate
+// an unmatched host into a response: catch NoRouteMatchError and return 404
+// (parity with the documented Cloudflare catch). Other errors propagate.
+export default async function handler(request, input) {
+  if (!_hostRouter) {
+    _hostRouter = __resolveHostRouter(__hostEntry);
+    if (!_hostRouter) {
+      throw new Error(
+        "[rango] The host entry (${hostEntryPath}) must export a HostRouter instance (createHostRouter()) for the node/vercel preset: a default export, or a named 'hostRouter'/'router' export. An ordinary createRouter() is not a host router (it has no .host()), and a Cloudflare-style 'export default { fetch }' object is not supported on this preset."
+      );
+    }
+  }
+  try {
+    return await _hostRouter.match(request, input);
+  } catch (err) {
+    // isNoRouteMatchError also matches by name: a workspace with a duplicated
+    // @rangojs/router copy can throw a NoRouteMatchError whose prototype differs
+    // from this module's import, so a bare instanceof would turn an
+    // unmatched-host 404 into a 500.
+    if (isNoRouteMatchError(err)) {
+      return new Response("Not Found", { status: 404 });
+    }
+    throw err;
+  }
+}
+`.trim();
+}
+
+export const VIRTUAL_IDS = {
+  browser: "virtual:rsc-router/entry.browser.js",
+  ssr: "virtual:rsc-router/entry.ssr.js",
+  rsc: "virtual:rsc-router/entry.rsc.js",
+  version: "@rangojs/router:version",
+} as const;
+
+export function getVirtualVersionContent(version: string): string {
+  return `export const VERSION = ${JSON.stringify(version)};`;
+}

package/src/vite/plugins/virtual-stub-plugin.ts

@@ -0,0 +1,29 @@
+import type { Plugin } from "vite";
+
+/**
+ * Stub plugin that resolves and provides empty exports for virtual modules
+ * that the RSC entry may import but aren't needed for route discovery.
+ * @internal
+ */
+export function createVirtualStubPlugin(): Plugin {
+  const STUB_PREFIXES = [
+    "virtual:rsc-router/",
+    "virtual:entry-",
+    "virtual:vite-rsc/",
+  ];
+  return {
+    name: "@rangojs/router:virtual-stubs",
+    resolveId(id) {
+      if (STUB_PREFIXES.some((p) => id.startsWith(p))) {
+        return "\0stub:" + id;
+      }
+      return null;
+    },
+    load(id) {
+      if (id.startsWith("\0stub:")) {
+        return "export default {}";
+      }
+      return null;
+    },
+  };
+}