@uniflowed/vite 0.0.0-alpha.12 → 0.0.0-alpha.14

package/internal/rsc.js

@@ -35,7 +35,7 @@
 // route uf has positively decided needs no browser — and a manifest that is
 // missing, unreadable, or written by an older uf removes nothing at all.
 
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import path from "node:path";
 
 /** Environment variable naming the manifest, set by `uf build` and `uf dev`. */
@@ -140,12 +140,267 @@ export function clientRouteFilter(manifest, root, boundaries = {}) {
     if (needed(route.page)) return true;
     if (route.layouts.some(needed)) return true;
     if ((route.loading ?? []).some((entry) => needed(entry.module))) return true;
+    if ((route.templates ?? []).some((entry) => needed(entry.module))) return true;
+    // A boundary with no module of its own is the record the scan synthesises
+    // at the router root, and what renders there is the framework's own page —
+    // already in `@uniflowed/router`, reaching nothing this project wrote. It
+    // is skipped rather than left to `needed`, whose answer for a value that is
+    // not a file is "assume it is needed": that answer is right for a path the
+    // manifest has never heard of and wrong for the absence of a path, and
+    // taking it here would have kept every page of every project in the client
+    // bundle. See ubugeeei-prod/uf#351.
     for (const boundary of notFound) {
+      if (boundary.page == null) continue;
       if (covers(boundary.path, route.path) && needed(boundary.page)) return true;
     }
     for (const boundary of errors) {
+      if (boundary.module == null) continue;
       if (covers(boundary.path, route.path) && needed(boundary.module)) return true;
     }
     return false;
   };
 }
+
+// ---------------------------------------------------------------------------
+// Server actions
+//
+// The other half of the split, and the one the manifest was already carrying
+// an answer for. `serverActions` in the manifest is every action `uf_rsc`
+// decided is a *callable endpoint* — an action some module that can hand it
+// across a client boundary reaches — with the keyed id
+// `crates/uf_rsc/src/action.rs` derived for it. An action nothing exposes is
+// tracked in the registry and never written here, so a table built out of this
+// file cannot contain a row that was not meant to be dialable.
+//
+// Two tables come out of it, for the two graphs:
+//
+// * `serverActionModules` is the browser's. It says, for each `"use server"`
+//   file, which exports become `createServerReference` calls — and the plugin
+//   answers that source *instead of the file*, so the module's body never
+//   enters the client graph and neither does anything only it imported.
+// * `serverActionTable` is the server's. It is what `virtual:uf/actions`
+//   emits and what `createActionDispatcher` dials into.
+//
+// Both are keyed on the id and nothing else. No request-derived value ever
+// becomes a path, a specifier or an export name here or downstream; see the
+// header of `packages/router/internal/action-endpoint.js`.
+// ---------------------------------------------------------------------------
+
+/**
+ * The request header carrying an action id, lowercased as Node delivers it.
+ *
+ * A second spelling of `ACTION_HEADER` in
+ * `packages/router/internal/action-wire.js`, and it has to be one: this module
+ * is plain JavaScript the Vite host imports before any transform, and that one
+ * is Flow, which Node cannot import at all. `RSC_MANIFEST_ENV` above is the
+ * same situation with `crates/uf_rsc/src/manifest.rs`. What keeps a second
+ * spelling from becoming a second answer is
+ * `tests/library/server-actions.test.js`, which reads both and compares them.
+ */
+export const ACTION_HEADER = "uf-action";
+
+/** The id an action row must carry: 64 lowercase hexadecimal characters. */
+function isActionId(value) {
+  if (typeof value !== "string" || value.length !== 64) return false;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    const digit = code >= 0x30 && code <= 0x39;
+    const lower = code >= 0x61 && code <= 0x66;
+    if (!digit && !lower) return false;
+  }
+  return true;
+}
+
+/**
+ * Whether a name can be written as `export const <name>`.
+ *
+ * The scanner only ever produces identifiers, so this refuses nothing a real
+ * project has. It is here because the alternative to refusing is emitting a
+ * module that does not parse, and a generated file that does not parse fails a
+ * build somewhere far from the module that caused it. `default` is handled by
+ * the caller, which writes `export default`.
+ */
+function isExportableName(name) {
+  if (typeof name !== "string" || name.length === 0) return false;
+  const first = name.charCodeAt(0);
+  const startish = (code) =>
+    (code >= 0x41 && code <= 0x5a) ||
+    (code >= 0x61 && code <= 0x7a) ||
+    code === 0x24 ||
+    code === 0x5f;
+  if (!startish(first)) return false;
+  for (let index = 1; index < name.length; index += 1) {
+    const code = name.charCodeAt(index);
+    if (!startish(code) && !(code >= 0x30 && code <= 0x39)) return false;
+  }
+  return true;
+}
+
+/** Every callable action of the manifest, in the manifest's own order. */
+function callableActions(manifest) {
+  if (manifest == null || !Array.isArray(manifest.serverActions)) return [];
+  return manifest.serverActions.filter(
+    (action) =>
+      action != null &&
+      isActionId(action.id) &&
+      typeof action.module === "string" &&
+      action.module !== "" &&
+      // An inline `"use server"` closure has no export name to import, so it
+      // has no reference in the client bundle and no row in the server's
+      // table. It is in the manifest, and reaching it needs the payload
+      // ubugeeei-prod/uf#252 is about.
+      action.kind === "module-export" &&
+      isExportableName(action.export === "default" ? "default_" : action.export),
+  );
+}
+
+/**
+ * The absolute path of a module the manifest names, or `null`.
+ *
+ * The manifest's paths are project-relative with forward slashes and were
+ * written by a walk that already refused anything outside the root; joined
+ * here and checked again, because a path that escapes the project is a path
+ * this plugin would otherwise hand to Rollup as a module to emit.
+ */
+function moduleFile(root, relative) {
+  const joined = path.resolve(root, relative);
+  const inside = path.relative(root, joined);
+  if (inside === "" || inside.startsWith("..") || path.isAbsolute(inside)) return null;
+  return joined;
+}
+
+/**
+ * Which exports of each `"use server"` file become references in the browser.
+ *
+ * Keyed by absolute path, because that is what Vite's `load` hook is given.
+ * A file with no callable action is absent rather than present-and-empty: the
+ * plugin substitutes a module only for a key it finds, and substituting an
+ * empty module for a file something imports would be a build error in place of
+ * a working import.
+ *
+ * @param {object | null} manifest from {@link readRscManifest}
+ * @param {string} root absolute project root
+ * @returns {Map<string, Array<{id: string, module: string, export: string}>>}
+ */
+export function serverActionModules(manifest, root) {
+  const modules = new Map();
+  for (const action of callableActions(manifest)) {
+    const file = moduleFile(root, action.module);
+    if (file == null) continue;
+    const rows = modules.get(file);
+    const row = { id: action.id, module: action.module, export: action.export };
+    if (rows === undefined) modules.set(file, [row]);
+    else rows.push(row);
+  }
+  return modules;
+}
+
+/**
+ * Every callable action, as the server's dispatcher table.
+ *
+ * @param {object | null} manifest from {@link readRscManifest}
+ * @param {string} root absolute project root
+ * @returns {Array<{id: string, module: string, export: string, file: string}>}
+ */
+export function serverActionTable(manifest, root) {
+  const rows = [];
+  for (const action of callableActions(manifest)) {
+    const file = moduleFile(root, action.module);
+    if (file == null) continue;
+    rows.push({ id: action.id, module: action.module, export: action.export, file });
+  }
+  return rows;
+}
+
+/**
+ * The client bundle's stand-in for one `"use server"` module.
+ *
+ * What the browser gets in place of the file: one `createServerReference` per
+ * callable export, an id each, and nothing the module itself imported. This is
+ * the whole of how a database handle reached only through an action stays on
+ * the server — `crates/uf_rsc/src/graph/build.rs` colours the module server for
+ * the same reason, so that the analysis and the bundle agree about it.
+ *
+ * @param {Array<{id: string, module: string, export: string}>} actions
+ */
+export function actionReferenceSource(actions) {
+  const lines = ['import { createServerReference } from "@uniflowed/router/action";', ""];
+  for (const action of actions) {
+    const reference = `createServerReference(${JSON.stringify(action.id)}, ${JSON.stringify(
+      `${action.module}#${action.export}`,
+    )})`;
+    lines.push(
+      action.export === "default"
+        ? `export default ${reference};`
+        : `export const ${action.export} = ${reference};`,
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * The source of `virtual:uf/actions`: the table the endpoint dials into.
+ *
+ * One `import()` thunk per file rather than one per action, so a module with
+ * four actions is one chunk of the server bundle and not four. Lazy for the
+ * reason the handler table is: an action module is loaded when an action in it
+ * is called, and a project's actions are not something every request should
+ * pay to import.
+ *
+ * With no manifest the table is empty and every action call is a `404` — the
+ * same answer a project driving Vite itself gets for the route split, and for
+ * the same reason: uf will not guess at an analysis it was not given.
+ *
+ * @param {Array<{id: string, module: string, export: string, file: string}>} actions
+ */
+export function actionsModuleSource(actions) {
+  const loaders = new Map();
+  const declarations = [];
+  const loaderId = (file) => {
+    let id = loaders.get(file);
+    if (id === undefined) {
+      id = `load${loaders.size}`;
+      loaders.set(file, id);
+      declarations.push(`const ${id} = () => import(${JSON.stringify(file)});`);
+    }
+    return id;
+  };
+
+  const entries = actions.map(
+    (action) => `  {
+    id: ${JSON.stringify(action.id)},
+    module: ${JSON.stringify(action.module)},
+    export: ${JSON.stringify(action.export)},
+    load: ${loaderId(action.file)},
+  }`,
+  );
+
+  return `${declarations.join("\n")}
+export const actions = [
+${entries.join(",\n")}
+];
+export default actions;
+`;
+}
+
+/**
+ * A cheap identity for the manifest file, so a reader can tell it has changed.
+ *
+ * The plugin's `load` hook runs for every module in the graph and cannot parse
+ * the manifest each time. Size and modification time together are what
+ * `.uf/cache/transform` already keys on for the binary that wrote it, and the
+ * same reasoning applies: a file that differs in neither is the file that was
+ * read. `uf dev` also clears the cache outright when its watcher sees the
+ * manifest change, so this is the build's answer rather than the only one.
+ *
+ * @param {string | undefined} file
+ */
+export function rscManifestKey(file) {
+  if (file == null || file === "") return "";
+  try {
+    const stats = statSync(file);
+    return `${String(stats.size)}:${String(stats.mtimeMs)}`;
+  } catch {
+    return "";
+  }
+}

package/internal/serve.js

@@ -240,12 +240,12 @@ export function assetsFromManifest(manifest) {
  * naming rather than papering over, and it is the failure path of a request
  * that already went wrong — not the ordinary one this exists for.
  *
- * @param {{beginRequest: (request: Request) => {run: <T>(body: () => Promise<T>) => Promise<T>, settle: () => Promise<void>}}} entry
+ * @param {{beginRequest: (request: Request) => {context: object, run: <T>(body: () => Promise<T>) => Promise<T>, settle: () => Promise<void>}}} entry
  * @param {Request} request
  * @param {() => Promise<mixed>} body
  */
 export async function withRequest(entry, request, body) {
-  const { run, settle } = entry.beginRequest(request);
+  const { run, settle } = await beginRequest(entry, request);
   try {
     return await run(body);
   } finally {
@@ -253,6 +253,44 @@ export async function withRequest(entry, request, body) {
   }
 }
 
+/**
+ * Begin a request on this host, with what this host can do already on it.
+ *
+ * The half of [`withRequest`] that a caller which may *not* answer needs.
+ * `uf dev` runs the application's middleware, its action endpoint and its
+ * dispatcher for every request, and hands the ones none of them claimed back
+ * to Vite's chain — at which point the response is written somewhere this
+ * module cannot see, so settling has to wait for the socket rather than for a
+ * `finally` here. A caller that always answers should use [`withRequest`] and
+ * not think about it.
+ *
+ * `entry.beginRequest` and not an import: the request lives in an
+ * `AsyncLocalStorage` belonging to one copy of `@uniflowed/server`, and the
+ * copy that matters is the one inside the application bundle. See
+ * `serverModuleSource` in `./routes.js`.
+ *
+ * What this host can do is put on the request the way `createFetchHandler`
+ * puts it on the one it owns. `uf dev` and `uf build --compile` reach a route
+ * handler without going through that function, and a handler that streams
+ * events or queues work has to get the same answer from all four front doors —
+ * a capability that is present under `uf start` and absent under `uf dev` is
+ * the difference this whole seam exists to remove.
+ *
+ * `nodeCapabilities`, because both of those *are* a Node process with a
+ * socket: a body reaches the client as it is written, and the process is still
+ * there afterwards. Neither passes an upgrader or a queue, because uf defines
+ * both and implements neither.
+ *
+ * @param {{beginRequest: (request: Request) => {context: object, run: <T>(body: () => Promise<T>) => Promise<T>, settle: () => Promise<void>}}} entry
+ * @param {Request} request
+ */
+export async function beginRequest(entry, request) {
+  const lifecycle = entry.beginRequest(request);
+  const { nodeCapabilities } = await deployment();
+  lifecycle.context.capabilities ??= nodeCapabilities();
+  return lifecycle;
+}
+
 /**
  * The application half: route handlers, then rendering.
  *
@@ -274,11 +312,16 @@ export async function withRequest(entry, request, body) {
  * @param {{entry: object, assets: object, cache?: object}} build
  */
 export function createApplicationHandler({ entry, assets, cache }) {
-  const ready = deployment().then(({ createFetchHandler, createCacheStore }) =>
+  const ready = deployment().then(({ createFetchHandler, createCacheStore, nodeCapabilities }) =>
     createFetchHandler({
       app: entry,
       document: assets,
       cache: cacheFor(cache, createCacheStore),
+      // `uf preview` and `uf start` are a Node process with a socket, which is
+      // what a deployed `--adapter node` build is too — so a route handler
+      // that streams events answers the same way in the preview it is checked
+      // in and in the deployment it ends up as. See `withRequest` above.
+      capabilities: nodeCapabilities(),
     }),
   );
   return async function handle(request) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/vite",
-  "version": "0.0.0-alpha.12",
+  "version": "0.0.0-alpha.14",
   "description": "Vite, driven by uf.config.js: every Flow module through `uf transform`, MDX, the file-system router and static rendering as Vite plugins.",
   "type": "module",
   "license": "MIT",
@@ -10,6 +10,14 @@
     "url": "git+https://github.com/ubugeeei-prod/uf.git",
     "directory": "packages/vite"
   },
+  "uf": {
+    "builder": {
+      "driver": "./driver.js",
+      "preload": {
+        "bun": "@uniflowed/host/bun-preload"
+      }
+    }
+  },
   "exports": {
     ".": "./index.js",
     "./driver": "./driver.js",
@@ -25,8 +33,8 @@
   "dependencies": {
     "@mdx-js/rollup": "^3.1.1",
     "@shikijs/rehype": "^3.23.0",
-    "@uniflowed/host": "0.0.0-alpha.12",
-    "@uniflowed/server": "0.0.0-alpha.12",
+    "@uniflowed/host": "0.0.0-alpha.14",
+    "@uniflowed/server": "0.0.0-alpha.14",
     "rehype-slug": "^6.0.0",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",