@tinvar/renderer 0.0.0-stage → 0.4.1

package/src/dev-server.js

@@ -0,0 +1,460 @@
+// Dev mode: Vite's dev server is the renderer.
+//
+// tinvar-spec.md, "Operations and tooling": "Dev mode: Vite's dev server is
+// the renderer, with HMR and no separate build." The rsc and ssr
+// environments render from source through Vite's module runner, and the
+// browser loads the client environment from the same dev server -- under
+// DEV_BASE, which PHP's server proxies to it, HMR socket included, so the
+// app runs on one origin ("Dev experience": "HMR passed through PHP").
+//
+// What production's renderer has and this does not: the permission-model
+// sandbox and the in-process network lock. Vite watches the whole project,
+// spawns its bundlers' native code and serves HTTP, none of which the
+// sandbox would let it do. In their place: it refuses to start anywhere
+// that says production, binds loopback only, keeps the dev server's file
+// serving away from secrets, and still refuses an environment holding
+// credentials. That is a dev tool's footing, not production's, which is why
+// production can never reach it.
+
+import { createRequire } from 'node:module';
+import { existsSync, mkdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { useDevEntry } from './dev-app.js';
+import { assertDevelopment, DevServerRefused } from './dev-guard.js';
+import {
+  actionsOf,
+  boundaryUsers,
+  QUERY_MAP,
+  queriesOfComponents,
+  queriesOfViews,
+  queryUsers,
+  readQueryMap,
+  viewsOf,
+} from './vite.js';
+
+export { assertDevelopment, DevServerRefused, PRODUCTION_MARKERS } from './dev-guard.js';
+
+/** Where the dev server's modules are served from, behind PHP's server. */
+export const DEV_BASE = '/_vite/';
+
+/** Addresses the dev server may listen on: this machine's, and nothing else. */
+const LOOPBACK = new Set(['127.0.0.1', '::1']);
+
+/** The app's Vite config file. */
+function configFileOf(appRoot) {
+  for (const name of ['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs']) {
+    const file = path.join(appRoot, name);
+    if (existsSync(file)) return file;
+  }
+  throw new Error(`No Vite config in ${appRoot}; dev mode renders through the app's own Vite environments.`);
+}
+
+/**
+ * Starts Vite's dev server on loopback for the app at `appRoot`, and points
+ * the renderer's dev entry at its rsc environment.
+ *
+ * @param {{ appRoot: string, port: number, host?: string, deferredManifest?: string | null, logLevel?: string }} options
+ *        `deferredManifest` is where to keep the views' <Deferred> components
+ *        up to date, as the build's deferredBoundaries() writes them
+ * @returns {Promise<{ vite: any, url: string, close: () => Promise<void> }>}
+ */
+export async function createDevServer({
+  appRoot,
+  port,
+  host = '127.0.0.1',
+  deferredManifest = null,
+  logLevel,
+}) {
+  assertDevelopment();
+  if (!LOOPBACK.has(host)) {
+    throw new DevServerRefused(`The dev server listens on loopback only; refusing ${host}.`);
+  }
+
+  // The app's own Vite, the one its plugins were written against.
+  const require = createRequire(path.join(appRoot, 'package.json'));
+  const { createServer } = await import(require.resolve('vite'));
+
+  // Before the watcher exists: what was written before this moment is no
+  // change it should act on. See ignoreReplayedChanges().
+  const watchedFrom = Date.now();
+
+  // Told when Vite makes its server again -- an edit to vite.config.ts
+  // restarts it -- once the new one is listening (see followRestarts()).
+  let restarted = () => {};
+  // Settled once a restarted server listens: what asks for the environment
+  // in the middle of a restart -- the new environments made, the new server
+  // not yet listening -- waits for that rather than reading no address as
+  // one off loopback.
+  let listened = null;
+  const restartListening = () => (listened ??= Promise.withResolvers()).promise;
+
+  const vite = await createServer({
+    root: appRoot,
+    configFile: configFileOf(appRoot),
+    base: DEV_BASE,
+    // No index.html and no SPA fallback: PHP serves every document.
+    appType: 'custom',
+    clearScreen: false,
+    ...(logLevel ? { logLevel } : {}),
+    plugins: [
+      ignoreReplayedChanges(watchedFrom),
+      followRestarts(() => {
+        const waiting = listened;
+        listened = null;
+        waiting?.resolve();
+        restarted();
+      }),
+    ],
+    // The plugin's own request handler renders through the rsc entry's
+    // default export, over HTTP. Here documents come from PHP, over the
+    // socket, so the dev server serves modules and nothing else.
+    rsc: { serverHandler: false },
+    server: {
+      host,
+      port,
+      strictPort: true,
+      fs: {
+        // Vite's own refusals, and the secrets an app keeps beside its code:
+        // a key file, a database, the PHP dependencies.
+        deny: ['.env', '.env.*', '*.{crt,pem}', '**/.git/**', '**/*.key', '**/*.sqlite*', '**/vendor/**'],
+      },
+    },
+  });
+
+  await vite.listen();
+
+  const address = loopbackAddress(vite);
+  if (address === null) {
+    const bound = vite.httpServer?.address();
+    await vite.close();
+    throw new DevServerRefused(`The dev server bound ${JSON.stringify(bound)}, which is not loopback.`);
+  }
+
+  // The rsc environment renders go through, and its entry's id. Vite makes
+  // its environments again when it restarts, closing the old ones' module
+  // runners: a render through the one the server started with failed from
+  // then on. So each render asks for the environment Vite has now, and one
+  // that has changed is taken up -- its entry resolved, the ssr environment
+  // warmed, the watcher followed -- before anything renders through it.
+  let current = null;
+  let refused = null;
+  let taking = null;
+  const rscEntry = async (rsc) => {
+    const input = rsc.config.build.rollupOptions.input;
+    const source = typeof input === 'string' ? input : input?.index;
+    if (typeof source !== 'string') {
+      throw new Error("The rsc environment names no 'index' entry in build.rollupOptions.input.");
+    }
+    const resolved = await rsc.pluginContainer.resolveId(source, undefined);
+    if (!resolved) throw new Error(`The rsc entry ${source} does not resolve.`);
+    return resolved.id;
+  };
+  const environment = async () => {
+    if (refused !== null) throw refused;
+    const rsc = vite.environments.rsc;
+    if (current?.rsc === rsc) return current;
+    taking ??= (async () => {
+      try {
+        // Restarted on another address -- a config that moved the host --
+        // is closed rather than served: dev stays on loopback, whatever
+        // the config now says. A server not listening yet is a restart
+        // still under way, which says nothing of its address until it is.
+        if (current !== null && vite.httpServer && !vite.httpServer.listening) {
+          await restartListening();
+        }
+        if (current !== null && loopbackAddress(vite) === null) {
+          refused = new DevServerRefused(
+            `The dev server restarted on ${JSON.stringify(vite.httpServer?.address())}, which is not loopback; it is closed. Start dev again.`,
+          );
+          await vite.close();
+          throw refused;
+        }
+        const id = await rscEntry(rsc);
+        const restart = current !== null;
+        current = { rsc, id };
+        if (restart) {
+          await rsc.runner.import(id);
+          await warmSsr(vite, require);
+          watch();
+        }
+        return current;
+      } finally {
+        taking = null;
+      }
+    })();
+    return taking;
+  };
+  const load = async () => {
+    const { rsc, id } = await environment();
+    return rsc.runner.import(id);
+  };
+
+  try {
+    await environment();
+  } catch (error) {
+    await vite.close();
+    throw error;
+  }
+  useDevEntry(load);
+
+  // Loaded once now, so a broken entry fails the start rather than the
+  // first page, and the module graph the deferred manifest is read from
+  // holds every view the entry imports.
+  await load();
+
+  // And what a document render asks of the ssr environment, before the
+  // socket that says this renderer is ready exists.
+  await warmSsr(vite, require);
+
+  // Taken up as soon as a restarted server listens, not at the next render:
+  // the first page after a config edit renders in PHP's time, as the first
+  // page after a start does.
+  restarted = () => {
+    environment().catch((error) => {
+      console.error('[tinvar:renderer] could not take up the restarted dev server:', error?.message ?? error);
+    });
+  };
+
+  // The watcher is Vite's server's, and a restart makes a new one: what
+  // listens on it is put on the one in use, and taken off the one before.
+  let watching = null;
+  let stopWatching = () => {};
+  const watch = () => {
+    if (watching === null || watching.watcher === vite.watcher) return;
+    watching.off();
+    watching.on();
+  };
+  if (deferredManifest) {
+    const write = async () => {
+      try {
+        await load();
+        writeAtomically(deferredManifest, await deferredManifestOf(vite, appRoot));
+      } catch (error) {
+        // An edit that does not compile is Vite's to report, in the browser
+        // overlay; the last manifest that did stays.
+        console.error(
+          "[tinvar:renderer] could not read the views' deferred boundaries:",
+          error?.message ?? error,
+        );
+      }
+    };
+    await write();
+    let timer = null;
+    const changed = () => {
+      clearTimeout(timer);
+      timer = setTimeout(write, 150);
+    };
+    watching = {
+      watcher: null,
+      on() {
+        this.watcher = vite.watcher;
+        for (const event of ['change', 'add', 'unlink']) this.watcher.on(event, changed);
+      },
+      off() {
+        for (const event of ['change', 'add', 'unlink']) this.watcher?.off(event, changed);
+        this.watcher = null;
+      },
+    };
+    watching.on();
+    stopWatching = () => {
+      clearTimeout(timer);
+      watching?.off();
+    };
+  }
+
+  const shown = address.family === 'IPv6' ? `[${address.address}]` : address.address;
+
+  return {
+    vite,
+    url: `http://${shown}:${address.port}${DEV_BASE}`,
+    async close() {
+      stopWatching();
+      await vite.close();
+    },
+  };
+}
+
+/** The dev server's address when it is a loopback one; null for any other, or none. */
+function loopbackAddress(vite) {
+  const address = vite.httpServer?.address();
+  return address && typeof address === 'object' && LOOPBACK.has(address.address) ? address : null;
+}
+
+/**
+ * Calls `restarted` each time Vite makes its server again after the first,
+ * once the new server is listening: a restart, for an edit to the config
+ * file or a plugin's asking. configureServer is called for every server
+ * Vite makes, this plugin being in the inline config every one is made
+ * from; the first is the one createDevServer() waits for itself.
+ *
+ * @param {() => void} restarted
+ */
+function followRestarts(restarted) {
+  let made = 0;
+  return {
+    name: 'tinvar:follow-restarts',
+    apply: 'serve',
+    configureServer(server) {
+      if (made++ === 0) return;
+      server.httpServer?.once('listening', () => restarted());
+    },
+  };
+}
+
+/**
+ * Drops the watcher's change events for files that have not changed since
+ * `watchedFrom`.
+ *
+ * macOS's file events can report writes made before the watch began: files
+ * written a few seconds before -- an app copied, a branch checked out, the
+ * dev server started straight after -- came back as changes the next time
+ * anything in the tree was written, seconds later or many, and all at
+ * once. Vite acts on each: vite.config.ts "changed", so it restarted the
+ * server under the renderer, whose renders then failed; tsconfig.json
+ * "changed", so every page was reloaded; and the edit that set it off was
+ * lost among them. A change the watcher reports for a file whose inode was
+ * last changed before the watch began is that history, and goes no further.
+ * The inode's change time, not the modification time a copy or an archive
+ * may carry over: only the kernel sets it, to the moment of the write.
+ *
+ * Changes only. An added file was not there when the watch began, whatever
+ * its times say -- a directory moved in keeps its files' -- and goes on.
+ *
+ * @param {number} watchedFrom milliseconds since the epoch
+ */
+function ignoreReplayedChanges(watchedFrom) {
+  const before = (file) => {
+    try {
+      return statSync(file).ctimeMs < watchedFrom;
+    } catch {
+      return false;
+    }
+  };
+
+  return {
+    name: 'tinvar:ignore-replayed-changes',
+    apply: 'serve',
+    // The first hook that has the watcher. Nothing in the tree is written
+    // before it -- Vite's own writes start with listen() -- so no event can
+    // set the history off before this is in place.
+    configureServer(server) {
+      const { watcher } = server;
+      const emit = watcher.emit;
+      watcher.emit = function (event, ...args) {
+        // chokidar emits each event twice: by its name, and as 'all'.
+        const file = event === 'change' ? args[0] : event === 'all' && args[0] === 'change' ? args[1] : null;
+        if (typeof file === 'string' && before(file)) return false;
+
+        return emit.call(this, event, ...args);
+      };
+    },
+  };
+}
+
+/**
+ * Loads the ssr environment's entry, and every client component the views
+ * reach as the ssr environment imports it -- by the key the RSC stream names
+ * it with -- so that the first document render loads none of it.
+ *
+ * Left to that render, it was most of the render: the shop's icon library
+ * alone is some 1,900 modules, one per icon, each transformed and evaluated,
+ * and on a loaded machine that took 12 to 18 s, inside the 15 s PHP gives a
+ * render. The socket had said the renderer was ready, and the first page was
+ * a 500. The time is the same here; it is spent before anyone is waiting.
+ *
+ * The client components are the RSC plugin's to know, through its
+ * (experimental) plugin API. One that does not load is not the start's to
+ * fail: it is the page's, which shows it in Vite's overlay as it would have.
+ *
+ * @param {any} vite
+ * @param {NodeJS.Require} require the app's, which resolves its own plugins
+ */
+async function warmSsr(vite, require) {
+  const ssr = vite.environments.ssr;
+  if (!ssr?.runner) return;
+
+  const warm = (id, load) =>
+    Promise.resolve()
+      .then(() => load(id))
+      .catch((error) => {
+        console.error(
+          `[tinvar:renderer] could not load ${id} ahead of the first render:`,
+          error?.message ?? error,
+        );
+      });
+  const imported = (id) => ssr.runner.import(id);
+
+  const input = ssr.config.build.rollupOptions.input;
+  const source = typeof input === 'string' ? input : input?.index;
+  const entry = typeof source === 'string' ? await ssr.pluginContainer.resolveId(source, undefined) : null;
+  if (entry) await warm(entry.id, imported);
+
+  let manager;
+  try {
+    const { getPluginApi } = await import(require.resolve('@vitejs/plugin-rsc'));
+    manager = getPluginApi?.(vite.config)?.manager;
+  } catch {
+    // No RSC plugin of that shape: the ssr environment's entry is warm, and
+    // its client components load on the first render, as before.
+  }
+
+  // Through the loader the ssr entry installed for the RSC stream's client
+  // references, where there is one: it collects each component's styles and
+  // checks the reference as well as importing it, as the render would. With
+  // the modules alone warm, the first render still took 6 s on a loaded
+  // machine; through the loader, a second or two.
+  const loader = globalThis.__vite_rsc_client_require__;
+  const load = typeof loader === 'function' ? loader : imported;
+  await Promise.all(
+    Object.values(manager?.clientReferenceMetaMap ?? {}).map((meta) => warm(meta.referenceKey, load)),
+  );
+}
+
+/**
+ * The views' <Deferred> components, read from the rsc environment's module
+ * graph as the build's deferredBoundaries() reads them from the bundle --
+ * the same viewsOf(), over what the dev server has resolved -- so a route
+ * may mint in dev exactly when it could from a build of the same source
+ * (ADR 0009, ADR 0024). And the queries each view and each registered
+ * deferred component may call, the same way, so a route's allowlist in dev
+ * is the one its build would give it. A call the build would refuse throws
+ * here, and the last list that could be read stays.
+ *
+ * @returns {Promise<{ format: 1, views: Record<string, string[]>, queries: Record<string, string[]>, componentQueries: Record<string, string[]>, actions: Record<string, string[]>, componentActions: Record<string, string[]> }>}
+ */
+export async function deferredManifestOf(vite, appRoot, pages = 'resources/pages', queryMap = QUERY_MAP) {
+  const rsc = vite.environments.rsc;
+  const pagesDir = path.resolve(appRoot, pages);
+
+  /** @type {Map<string, string[]>} */
+  const graph = new Map();
+  for (const [id, mod] of rsc.moduleGraph.idToModuleMap) {
+    graph.set(
+      id,
+      [...mod.importedModules].map((imported) => imported.id).filter((v) => typeof v === 'string'),
+    );
+  }
+
+  const resolveId = async (specifier, importer) =>
+    (await rsc.pluginContainer.resolveId(specifier, importer))?.id ?? null;
+  const users = await boundaryUsers(graph, pagesDir, resolveId);
+  const callers = await queryUsers(graph, pagesDir, resolveId, readQueryMap(path.resolve(appRoot, queryMap)));
+  const actions = await actionsOf(graph, callers.registry, pagesDir, resolveId);
+
+  return {
+    format: 1,
+    views: viewsOf(graph, users, pagesDir),
+    queries: queriesOfViews(graph, callers.calls, pagesDir),
+    componentQueries: queriesOfComponents(graph, callers.calls, callers.registry),
+    actions: actions.views,
+    componentActions: actions.components,
+  };
+}
+
+/** Written aside and moved into place, so PHP never reads half a file. */
+function writeAtomically(file, data) {
+  mkdirSync(path.dirname(file), { recursive: true });
+  const aside = `${file}.${process.pid}.tmp`;
+  writeFileSync(aside, JSON.stringify(data, null, 2) + '\n');
+  renameSync(aside, file);
+}