@uniflowed/host 0.0.0-alpha.7 → 0.0.0-alpha.8

package/module-mocks.js

@@ -0,0 +1,356 @@
+// @noflow
+//
+// Plain JavaScript: this is part of the loader, and `bun-preload.js` imports
+// it before any transform exists.
+//
+// Standing a module in for another one, at the only place that can do it: the
+// loader. `@uniflowed/test`'s `uft.mock` is the API; this is the mechanism, and
+// it lives here because by the time the runner sees an `import` the module has
+// already been fetched, linked and evaluated.
+//
+// # Why these are *synchronous* hooks
+//
+// `./register.js` installs Node's asynchronous customization hooks, and those
+// run on a loader thread of their own. That is right for the transform, which
+// only needs the file's bytes — and useless for a mock, which is a value the
+// test built: a spy the test holds a reference to cannot be sent to another
+// thread, and a registry written on the main thread is not a registry the
+// loader thread can read.
+//
+// So interception uses `node:module`'s `registerHooks`, which run in the thread
+// that is doing the importing. They see this module's `mocks` map directly, and
+// they chain into the asynchronous hooks for everything they do not claim — so
+// a module that is not mocked is still transformed, still cached on disk, and
+// still costs exactly what it cost before.
+//
+// # Why a mocked module gets a URL of its own
+//
+// A worker runs one file at a time and reuses the process, and Node's module
+// registry is keyed by URL and never forgets. If a mocked module were served
+// under its own URL, the *next* file in that worker would import the plain
+// specifier and be handed the previous file's stand-in — a mock leaking across
+// files, which is the one failure `docs/architecture.md` says the runner exists
+// to prevent.
+//
+// So a mock does not replace a module; it redirects to a new one. Registering a
+// mock takes the next revision number, the resolve hook appends it to the URL,
+// and the mocked module is a different module from the real one rather than the
+// same module with different contents. `unmock` stops appending, so the real
+// URL — which may still hold the real module — is what the next import gets.
+// Revisions are handed out for the life of the worker and never reused, which
+// is what makes a cleared registry actually clear.
+//
+// The same parameter carries the module *epoch*. A module that imports a mocked
+// one is standing in for it too — `consumer.js` computed its exports from
+// whatever `client.js` gave it — so registering a mock, removing one, or
+// calling `uft.resetModules` all start a new epoch, and every module reached by
+// a path is evaluated again on the next import of it. Epochs are handed out for
+// the life of the worker and never reused, for the reason revisions are not:
+// the file after this one must not be able to land on a URL this one filled.
+//
+// The epoch is appended only to modules reached by a path specifier (`./x.js`,
+// `/srv/x.js`): a bare specifier is a package, and handing a second copy of
+// `@uniflowed/test` to a test file would give it a second registry, a second
+// set of spies, and two of everything this package assumes there is one of. A
+// *mocked* package still gets a URL of its own, from its revision — being
+// stood in for is exactly the case where identity has to be given up.
+
+import * as nodeModule from "node:module";
+
+/** The URL parameter carrying `<module epoch>.<mock revision>`. */
+export const REVISION_PARAM = "uf-modules";
+
+/** The URL parameter marking an import that must reach the real module. */
+export const ACTUAL_PARAM = "uf-actual";
+
+/** This module's own URL, which a generated stand-in imports its values from. */
+const SELF = import.meta.url;
+
+/** Registered mocks, by module key. */
+const mocks = new Map();
+
+/** Namespaces handed to a generated module, by the exact URL it was loaded as. */
+const served = new Map();
+
+/** How many mocks have ever been registered in this process. */
+let revisions = 0;
+
+/** How many epochs have ever been started in this process. */
+let epochs = 0;
+
+/** The epoch this file is in; `0` until it does something that starts one. */
+let epoch = 0;
+
+/** The installed hooks, or `null` when interception is not installed. */
+let handle = null;
+
+/**
+ * A module's identity for the purpose of mocking: its URL with no query.
+ *
+ * The query is where every mechanism in this file writes — the worker's
+ * cache-busting `uf-run`, this file's revision, `importActual`'s marker — so
+ * two URLs that differ only there are the same module as far as a mock is
+ * concerned.
+ */
+export function moduleKey(url) {
+  const parsed = new URL(url);
+  parsed.search = "";
+  parsed.hash = "";
+  return parsed.href;
+}
+
+/**
+ * Whether this host can intercept a module before it is imported.
+ *
+ * The one requirement is synchronous, in-thread module hooks. Node has them;
+ * Bun's `node:module` has neither `register` nor `registerHooks`, and Deno has
+ * no loader in `@uniflowed/host` at all. `@uniflowed/test` turns a `false` here
+ * into an error that names the host rather than a mock that quietly does
+ * nothing.
+ */
+export function interceptionSupported() {
+  return typeof nodeModule.registerHooks === "function";
+}
+
+/**
+ * Install the interception hooks, once.
+ *
+ * Called on the first `uft.mock` or `uft.resetModules` rather than at import,
+ * because a resolve hook that runs for every specifier in the process is not
+ * something a suite that never mocks anything should pay for.
+ */
+export function installInterception() {
+  if (handle != null) {
+    return true;
+  }
+  if (!interceptionSupported()) {
+    return false;
+  }
+  handle = nodeModule.registerHooks({ load: loadHook, resolve: resolveHook });
+  return true;
+}
+
+/**
+ * Register `namespace` as the stand-in for the module at `url`.
+ *
+ * Returns nothing: what the caller needs is that the *next* resolution of that
+ * module lands somewhere else, which the resolve hook arranges from the
+ * revision recorded here.
+ */
+export function defineModuleMock(url, namespace) {
+  revisions += 1;
+  mocks.set(moduleKey(url), { namespace, revision: revisions });
+  startModuleEpoch();
+}
+
+/** Stop standing in for the module at `url`. */
+export function removeModuleMock(url) {
+  if (!mocks.delete(moduleKey(url))) {
+    return false;
+  }
+  startModuleEpoch();
+  return true;
+}
+
+/** Whether the module at `url` is currently stood in for. */
+export function isModuleMocked(url) {
+  return mocks.has(moduleKey(url));
+}
+
+/** The epoch path imports are currently loading into. */
+export function moduleEpoch() {
+  return epoch;
+}
+
+/**
+ * Begin a new epoch, so a path import evaluates its module again.
+ *
+ * Counted process-wide rather than per file. A file that reused the number a
+ * previous file's epoch had would be handed that file's modules, mocks and all,
+ * which is the leak the whole scheme exists to prevent.
+ */
+export function startModuleEpoch() {
+  epochs += 1;
+  epoch = epochs;
+  return epoch;
+}
+
+/**
+ * Forget every mock and leave the epoch.
+ *
+ * Called by the worker between files. Epochs and revisions deliberately keep
+ * counting: the next file's mock of the same module must not be handed the URL
+ * this file's mock is cached under.
+ */
+export function resetModuleMocks() {
+  mocks.clear();
+  served.clear();
+  epoch = 0;
+}
+
+/**
+ * The URL an import that must reach the real module should use.
+ *
+ * A mocked module is standing at the URL an ordinary import resolves to, so
+ * reaching past it takes a URL of its own — one per epoch, so that two calls in
+ * a row hand back the same module rather than compiling it twice.
+ *
+ * A module nobody is standing in for needs no marker: the URL an ordinary
+ * import would use already holds the real thing, and taking the marked path
+ * anyway would hand back a second copy of a module the test is already holding.
+ *
+ * `pathLike` is whether the caller wrote a path rather than a package name, and
+ * it is not a detail: this is the resolve hook's rule applied by hand, and the
+ * rule is that a package keeps its identity across an epoch. Getting it wrong
+ * here would hand a test a second copy of `@uniflowed/test` — a second registry
+ * and a second set of spies — from the one call that is supposed to reach the
+ * real thing.
+ */
+export function actualUrl(url, pathLike) {
+  const parsed = new URL(url);
+  if (!mocks.has(moduleKey(url))) {
+    if (epoch !== 0 && pathLike) {
+      parsed.searchParams.set(REVISION_PARAM, `${epoch}.0`);
+    }
+    return parsed.href;
+  }
+  parsed.searchParams.set(ACTUAL_PARAM, String(epoch));
+  return parsed.href;
+}
+
+/**
+ * The values a generated stand-in module exports.
+ *
+ * Keyed by the exact URL the stand-in was loaded as rather than by the module
+ * key, so that a stand-in evaluated after its mock was replaced still reads the
+ * namespace its export list was written from.
+ */
+export function namespaceFor(url) {
+  const namespace = served.get(url);
+  if (namespace == null) {
+    throw new Error(`@uniflowed/host: no mocked namespace was recorded for ${url}`);
+  }
+  return namespace;
+}
+
+/**
+ * The source of the stand-in module for `url`, or `null` when there is none.
+ *
+ * An ES module's export names are fixed when it is compiled, so they are
+ * written out here from the keys the mock actually has. That is the whole
+ * reason this returns source rather than an object: a namespace object cannot
+ * be handed to `import`, and a module with the wrong names would fail to link
+ * with an error about the importer rather than about the mock.
+ */
+export function mockedSource(url) {
+  const parsed = new URL(url);
+  if (parsed.searchParams.has(ACTUAL_PARAM)) {
+    return null;
+  }
+  const record = mocks.get(moduleKey(url));
+  if (record == null) {
+    return null;
+  }
+
+  served.set(url, record.namespace);
+  const lines = [
+    `import { namespaceFor } from ${JSON.stringify(SELF)};`,
+    `const values = namespaceFor(${JSON.stringify(url)});`,
+  ];
+  const bindings = [];
+  for (const [index, name] of Object.keys(record.namespace).entries()) {
+    lines.push(`const binding${index} = values[${JSON.stringify(name)}];`);
+    bindings.push(`binding${index} as ${exportName(name)}`);
+  }
+  // `export {}` rather than nothing, so a mock with no exports is still an ES
+  // module: without an export or import declaration Node would have to guess
+  // the format from the package, and the guess is not always "module".
+  lines.push(bindings.length === 0 ? "export {};" : `export { ${bindings.join(", ")} };`);
+  return `${lines.join("\n")}\n`;
+}
+
+/** How an export is named in an `export {}` clause. */
+function exportName(name) {
+  // Reserved words are fine — `export { x as default }` is the whole point —
+  // but anything that is not an identifier at all has to be a string, which
+  // ES2022 allows and which is how a mock keeps a name like `foo-bar`.
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+
+/**
+ * The `load` hook: serve a stand-in, or defer to the transform.
+ *
+ * Deferring is the common case and has to stay cheap: with no mocks registered
+ * this is one map lookup on an empty map.
+ */
+function loadHook(url, context, nextLoad) {
+  if (mocks.size === 0 || !url.startsWith("file:")) {
+    return nextLoad(url, context);
+  }
+  const source = mockedSource(url);
+  if (source == null) {
+    return nextLoad(url, context);
+  }
+  return { format: "module", shortCircuit: true, source };
+}
+
+/**
+ * The `resolve` hook: send an import to the revision it belongs to.
+ *
+ * Runs after the rest of the chain, so what it rewrites is a fully resolved
+ * URL rather than a specifier it would have to resolve itself.
+ */
+function resolveHook(specifier, context, nextResolve) {
+  const resolved = nextResolve(specifier, context);
+  if (mocks.size === 0 && epoch === 0) {
+    return resolved;
+  }
+  const url = redirect(specifier, context?.parentURL, resolved?.url);
+  return url === resolved.url ? resolved : { ...resolved, url };
+}
+
+/** Where an import of `url` should actually go. */
+function redirect(specifier, parentURL, url) {
+  if (typeof url !== "string" || !url.startsWith("file:")) {
+    return url;
+  }
+  const parsed = new URL(url);
+  // Already answered: `importActual` names the URL it wants, and a URL that
+  // carries a revision was produced by this function on the way in.
+  if (parsed.searchParams.has(ACTUAL_PARAM) || parsed.searchParams.has(REVISION_PARAM)) {
+    return url;
+  }
+
+  const revision = mocks.get(moduleKey(url))?.revision ?? 0;
+  // A package keeps its identity across an epoch; a module of this project's
+  // own does not. See the note at the top of the file.
+  const at = isPathSpecifier(specifier) ? epochOf(parentURL) : 0;
+  if (revision === 0 && at === 0) {
+    return url;
+  }
+  parsed.searchParams.set(REVISION_PARAM, `${at}.${revision}`);
+  return parsed.href;
+}
+
+/** Whether `specifier` names a file rather than a package. */
+function isPathSpecifier(specifier) {
+  return specifier.startsWith("./") || specifier.startsWith("../") || specifier.startsWith("/");
+}
+
+/**
+ * The epoch an import from `parentURL` belongs to.
+ *
+ * A module loaded in epoch two loads its own dependencies in epoch two, however
+ * many mocks have been registered since: a graph half of which is one epoch and
+ * half another is two copies of a module that expects to be one.
+ */
+function epochOf(parentURL) {
+  if (parentURL == null || !parentURL.startsWith("file:")) {
+    return epoch;
+  }
+  const carried = new URL(parentURL).searchParams.get(REVISION_PARAM);
+  if (carried == null) {
+    return epoch;
+  }
+  return Number.parseInt(carried.split(".")[0], 10);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/host",
-  "version": "0.0.0-alpha.7",
+  "version": "0.0.0-alpha.8",
   "description": "Running Flow on a Capability JS Host, with no bundler in the way.",
   "type": "module",
   "license": "MIT",
@@ -13,6 +13,7 @@
   "exports": {
     "./bun-preload": "./bun-preload.js",
     "./internal/node-hooks.js": "./internal/node-hooks.js",
+    "./module-mocks": "./module-mocks.js",
     "./register": "./register.js",
     "./transform": "./transform.js",
     "./write-atomically": "./write-atomically.js"
@@ -20,7 +21,9 @@
   "files": [
     "register.js",
     "bun-preload.js",
+    "module-mocks.js",
     "transform.js",
+    "write-atomically.js",
     "internal/*.js"
   ]
 }

package/write-atomically.js

@@ -0,0 +1,54 @@
+// @noflow
+//
+// Plain JavaScript: this is reached from the loader hooks, which run before
+// any transform, and from the config loader, which runs before them.
+//
+// Writing a file a second process may be reading at the same time.
+//
+// `writeFileSync` truncates and then writes, so a reader can observe the empty
+// file or half of one. When what is being written is a module, the reader does
+// not get an error it can act on — it gets a module with no exports, and says
+// so about the *source*:
+//
+//     uf: uf.config.js must `export default defineConfig({ ... })`
+//
+// which is a sentence about a file that is perfectly correct. That is not
+// hypothetical: two `uf` commands in one project, which is `uf dev` in one
+// terminal and `uf build` in another, produced exactly it. See
+// ubugeeei-prod/uf#240.
+//
+// Writing to a private name and renaming is atomic within a filesystem, so a
+// reader sees the old file or the new one and never a part of either.
+
+import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Write `contents` to `target` so a concurrent reader never sees half of it.
+ *
+ * The temporary name carries the process id and a random suffix, because two
+ * processes racing to write the *same* target is the case this exists for and
+ * they must not collide on the temporary either.
+ *
+ * @param {string} target absolute path to write
+ * @param {string} contents what to write
+ * @param {{ tolerant?: boolean }} [options] `tolerant` swallows a failure,
+ *   which is what a cache wants — a read-only checkout still runs, just
+ *   without one. A config that cannot be written is a failure the caller has
+ *   to see.
+ */
+export function writeAtomically(target, contents, options = {}) {
+  const temporary = `${target}.${process.pid}.${Math.random().toString(36).slice(2)}`;
+  try {
+    mkdirSync(path.dirname(target), { recursive: true });
+    writeFileSync(temporary, contents);
+    renameSync(temporary, target);
+  } catch (error) {
+    try {
+      unlinkSync(temporary);
+    } catch {
+      // Nothing to clean up.
+    }
+    if (options.tolerant !== true) throw error;
+  }
+}