@tinvar/renderer 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carson Hopper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/dev-renderer.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// Starts the renderer in dev mode: Vite's dev server renders from source.
+//
+//   node packages/renderer/bin/dev-renderer.js <socket-path> <app-root> --port=N
+//     [--deferred=FILE] [--codec=msgpack|json-lines] [--exit-with-stdin]
+//
+// PHP talks to it over the socket exactly as it talks to the built renderer;
+// the browser loads modules from the dev server on loopback port N, through
+// PHP's server (tinvar serve --dev). See src/dev-server.js for what dev mode
+// gives up, and why that keeps it out of production.
+
+// As bin/renderer.js: a listener of our own replaces SIGUSR1's default, which
+// opens Node's debugger to anything that can signal this process.
+process.on('SIGUSR1', () => {});
+
+import { assertDevelopment, DevServerRefused } from '../src/dev-guard.js';
+
+// Before anything else is loaded -- Vite, the app, its dependencies -- and
+// loudly: the dev server never runs in production, whatever started it.
+try {
+  assertDevelopment(process.env);
+} catch (error) {
+  console.error(`[tinvar:renderer] ${error.message}`);
+  process.exit(78);
+}
+
+// React picks its build at import time; the development build is the one
+// that carries component stacks and HMR.
+process.env.NODE_ENV = 'development';
+
+const { lstatSync, mkdirSync } = await import('node:fs');
+const path = (await import('node:path')).default;
+const { assertScrubbedEnvironment, createRenderer } = await import('../src/server.js');
+const { createDevServer } = await import('../src/dev-server.js');
+const { scrubEnvironment } = await import('../src/sandbox.js');
+
+const positional = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+const options = process.argv.slice(2).filter((a) => a.startsWith('--'));
+const option = (name) => options.find((f) => f.startsWith(`--${name}=`))?.slice(name.length + 3);
+
+const [socketPath, appRoot] = positional;
+const port = Number(option('port'));
+if (!socketPath || !appRoot || !Number.isInteger(port) || port < 1 || port > 65535) {
+  console.error(
+    'usage: dev-renderer.js <socket-path> <app-root> --port=N [--deferred=FILE] [--codec=msgpack|json-lines] [--exit-with-stdin]',
+  );
+  process.exit(64);
+}
+
+// Unsandboxed is no reason to hold credentials: a dependency that could read
+// them could send them, here more easily than anywhere.
+if (process.env.TINVAR_ALLOW_UNSCRUBBED_ENV !== '1') {
+  try {
+    assertScrubbedEnvironment();
+  } catch (error) {
+    console.error(`[tinvar:renderer] ${error.message}`);
+    process.exit(78);
+  }
+}
+// And then nothing but the allowlist a sandboxed renderer's child is given,
+// with what dev mode reads besides -- the names tinvar serve --dev passes
+// (ServeCommand::DEV_RENDERER_ENV) -- however this process was started.
+scrubEnvironment(['TINVAR_ENV', 'APP_ENV', 'TINVAR_PROFILE']);
+
+// The socket's directory, private, as the built renderer's launcher makes it;
+// and nothing that is not a socket already at the path.
+mkdirSync(path.dirname(path.resolve(socketPath)), { recursive: true, mode: 0o700 });
+try {
+  if (!lstatSync(socketPath).isSocket()) {
+    console.error(
+      `[tinvar:renderer] Refusing ${socketPath}: something other than a socket is already there.`,
+    );
+    process.exit(73);
+  }
+} catch {
+  // Nothing there yet.
+}
+
+if (options.includes('--exit-with-stdin')) {
+  process.stdin.on('end', () => process.kill(process.pid, 'SIGTERM'));
+  process.stdin.resume();
+}
+
+let dev;
+try {
+  dev = await createDevServer({
+    appRoot: path.resolve(appRoot),
+    port,
+    deferredManifest: option('deferred') ? path.resolve(option('deferred')) : null,
+  });
+} catch (error) {
+  console.error(
+    `[tinvar:renderer] ${error instanceof DevServerRefused ? error.message : (error?.stack ?? error)}`,
+  );
+  process.exit(error instanceof DevServerRefused ? 78 : 1);
+}
+
+const renderer = await createRenderer({
+  socketPath,
+  appEntry: new URL('../src/dev-app.js', import.meta.url).pathname,
+  codec: option('codec') ?? process.env.TINVAR_RENDERER_CODEC ?? 'msgpack',
+  checkEnvironment: process.env.TINVAR_ALLOW_UNSCRUBBED_ENV !== '1',
+});
+
+console.log(
+  `[tinvar:renderer] dev server on ${dev.url}, listening on ${renderer.socketPath} (${renderer.codec}, development)`,
+);
+
+let stopping = false;
+const shutDown = async () => {
+  if (stopping) return;
+  stopping = true;
+  await Promise.allSettled([renderer.close(), dev.close()]);
+  process.exit(0);
+};
+
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, shutDown);

package/bin/renderer-probe.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Whether a renderer pool is up: its supervisor running, and at least one
+// renderer answering a health frame -- which proves its event loop turns, as
+// a connection alone does not (ADR 0028). The probe of the renderers'
+// container in the two-container shape (ADR 0071), run as their own user.
+//
+//   node packages/renderer/bin/renderer-probe.js [POOL]
+//
+// POOL defaults to TINVAR_SOCKET. Exits 0 and names the renderer that
+// answered, or 1 and says why not.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { PID_FILE, checkHealth, readPid } from '../src/pool.js';
+
+const pool = process.argv[2] ?? process.env.TINVAR_SOCKET;
+
+function fail(reason) {
+  console.error(`[tinvar:renderer] not ready: ${reason}`);
+  process.exit(1);
+}
+
+if (!pool) fail('name the pool directory, or set TINVAR_SOCKET');
+
+const supervisor = readPid(path.join(pool, PID_FILE));
+if (supervisor === null) fail(`${pool} has no supervisor's pid file`);
+try {
+  // This probe runs as the pool's user, so a supervisor it cannot signal is
+  // not the pool's.
+  process.kill(supervisor, 0);
+} catch {
+  fail(`the supervisor named in ${pool} (pid ${supervisor}) is not running as this user`);
+}
+
+let sockets;
+try {
+  sockets = fs.readdirSync(pool).filter((name) => name.endsWith('.sock'));
+} catch (error) {
+  fail(`${pool} cannot be listed: ${error.message}`);
+}
+
+const reasons = [];
+for (const name of sockets) {
+  try {
+    const answer = await checkHealth(path.join(pool, name), { timeoutMs: 2_000 });
+    console.log(`ready: ${name} answered (pid ${answer.pid}, ${answer.inFlight} in flight)`);
+    process.exit(0);
+  } catch (error) {
+    reasons.push(`${name}: ${error.message}`);
+  }
+}
+fail(sockets.length === 0 ? `no renderer is listening in ${pool}` : reasons.join('; '));

package/bin/renderer.js

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+// Starts the renderer on a Unix socket, or a pool of renderers in a directory.
+//
+//   node packages/renderer/bin/renderer.js <socket-path> <app-rsc-entry>
+//     [--codec=msgpack|json-lines] [--dev] [--exit-with-stdin] [--exit-with-pid=PID] [--drain-timeout=SECONDS]
+//     [--socket-group=GROUP]
+//
+//   node packages/renderer/bin/renderer.js <directory> <app-rsc-entry> --processes=N [...]
+//
+// With --processes, this process supervises N sandboxed renderers, one
+// socket each in <directory>, which PHP reads as the pool (see
+// src/pool.js and ADR 0028). SIGTERM drains and stops; SIGUSR2 restarts the
+// pool one renderer at a time, for a deploy. The spec's lifecycle commands
+// (renderer:start, :stop, :check) drive it through bin/tinvar.
+//
+// --socket-group is for a renderer run as a user of its own, with PHP as
+// another: each socket is shared with GROUP (0660) and the directory it is
+// in too (0750), so PHP's user, in the group, can connect, and no one else
+// can (src/socket-group.js). The service manager decides who this process
+// runs as; nothing here changes user.
+
+// SIGUSR1 opens Node's debugger, and nothing in the permission model stops a
+// process signalling another: the sandboxed renderer could send it to this
+// process -- its unsandboxed parent -- and run any code there through the
+// debugger port, reading the app key or anything else. A listener of our own
+// replaces that default, here and in the child. (Equivalent to
+// --disable-sigusr1, which a running process cannot add to itself.)
+process.on('SIGUSR1', () => {});
+
+// Set before the app is imported: React picks its build at import time, and a
+// development build serializes component source and per-component timing rows
+// into the RSC payload. That is useful in dev and misleading everywhere else --
+// it tripled the payload and made render size vary request to request.
+if (!process.env.NODE_ENV) {
+  process.env.NODE_ENV = process.argv.includes('--dev') ? 'development' : 'production';
+}
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  DEFAULT_DRAIN_MS,
+  assertScrubbedEnvironment,
+  createRenderer,
+  shareDirectory,
+} from '../src/server.js';
+import { resolveSocketGroup } from '../src/socket-group.js';
+import {
+  isSandboxed,
+  lockNetwork,
+  real,
+  relaunchSandboxed,
+  sandboxFlags,
+  scrubEnvironment,
+  spawnSandboxed,
+  watchTether,
+} from '../src/sandbox.js';
+
+const positional = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+const options = process.argv.slice(2).filter((a) => a.startsWith('--'));
+
+const socketPath = positional[0] ?? process.env.TINVAR_RENDERER_SOCKET;
+const appEntry = positional[1] ?? process.env.TINVAR_APP_ENTRY;
+const codec =
+  options.find((f) => f.startsWith('--codec='))?.slice(8) ?? process.env.TINVAR_RENDERER_CODEC ?? 'msgpack';
+
+const usage =
+  'usage: renderer.js <socket-path | directory> <app-rsc-entry> [--processes=N] [--codec=msgpack|json-lines] ' +
+  '[--dev] [--exit-with-stdin] [--exit-with-pid=PID] [--drain-timeout=SECONDS] [--socket-group=GROUP]';
+
+/** The options a sandboxed renderer is started with: the socket group as the number it was resolved to. */
+function launched(given) {
+  return [
+    ...given.filter((o) => !o.startsWith('--socket-group=')),
+    ...(socketGroup === null ? [] : [`--socket-group=${socketGroup}`]),
+  ];
+}
+
+/** A whole-number option within bounds, or null when it is not given. */
+const whole = (name, min, max) => {
+  const given = options.find((f) => f.startsWith(`--${name}=`))?.slice(name.length + 3);
+  if (given === undefined) return null;
+  if (!/^[0-9]{1,6}$/.test(given) || Number(given) < min || Number(given) > max) {
+    console.error(`--${name} must be a whole number from ${min} to ${max}; got '${given}'.\n${usage}`);
+    process.exit(64);
+  }
+  return Number(given);
+};
+
+const processes = whole('processes', 1, 64);
+const drainSeconds = whole('drain-timeout', 0, 3600);
+const drainMs = drainSeconds === null ? DEFAULT_DRAIN_MS : drainSeconds * 1000;
+
+if (!socketPath || !appEntry) {
+  console.error(usage);
+  process.exit(64);
+}
+
+// Resolved once, here, to a number: the sandboxed child is handed the gid,
+// and may read no /etc/group to look a name up in.
+const socketGroup = (() => {
+  const given = options.find((f) => f.startsWith('--socket-group='))?.slice(15);
+  if (given === undefined) return null;
+  try {
+    return resolveSocketGroup(given);
+  } catch (error) {
+    console.error(`[tinvar:renderer] ${error.message}`);
+    process.exit(64);
+  }
+})();
+
+// For a supervisor that holds the other end of standard input and never
+// writes to it, as tinvar serve does. Killed outright, it can forward no
+// signal, but its end of the pipe closes: that ends the reason to serve, and
+// this process stops as a SIGTERM would stop it. Not in the sandboxed child,
+// whose standard input is its tether to this process (watchTether, below).
+if (options.includes('--exit-with-stdin') && !isSandboxed()) {
+  process.stdin.on('end', () => process.kill(process.pid, 'SIGTERM'));
+  process.stdin.resume();
+}
+
+// For a pool no one process holds the other end of: the test suite's, which
+// the first of its parallel workers to render starts and every worker uses
+// (ADR 0095). It serves while the run that started it does -- the process
+// whose pid is given, the parent of every worker -- and stops as a SIGTERM
+// would stop it once that process has gone, however it went.
+const exitWithPid = (() => {
+  const given = options.find((f) => f.startsWith('--exit-with-pid='))?.slice(16);
+  if (given === undefined) return null;
+  if (!/^[1-9][0-9]{0,9}$/.test(given) || Number(given) < 2) {
+    console.error(`--exit-with-pid must be the pid of a process other than init; got '${given}'.\n${usage}`);
+    process.exit(64);
+  }
+  return Number(given);
+})();
+if (exitWithPid !== null && !isSandboxed()) {
+  const watch = setInterval(() => {
+    try {
+      process.kill(exitWithPid, 0);
+    } catch (error) {
+      // EPERM is a process that is there, as another user.
+      if (error.code !== 'ESRCH') return;
+      clearInterval(watch);
+      process.kill(process.pid, 'SIGTERM');
+    }
+  }, 500);
+}
+
+// Not yet sandboxed: start again under the permission model and stand by
+// as its parent. TINVAR_RENDERER_UNSANDBOXED=1 opts out, for debugging --
+// loudly, and never in production, where a value left over in an env file
+// would otherwise switch the sandbox off without a word.
+const unsandboxed = !isSandboxed() && process.env.TINVAR_RENDERER_UNSANDBOXED === '1';
+// Any of the markers dev mode reads (dev-guard.js): an APP_ENV saying
+// production rules the escape hatches out as surely as a NODE_ENV does.
+const production = ['NODE_ENV', 'TINVAR_ENV', 'APP_ENV'].find(
+  (name) =>
+    String(process.env[name] ?? '')
+      .trim()
+      .toLowerCase() === 'production',
+);
+// TINVAR_ALLOW_UNSCRUBBED_ENV=1 skips the check that refuses a credential in
+// the renderer's environment: for debugging, never in production, where a
+// value left in an env file would hand secrets to every dependency unsaid.
+const unscrubbed = process.env.TINVAR_ALLOW_UNSCRUBBED_ENV === '1';
+if (unscrubbed && production !== undefined) {
+  console.error(
+    `[tinvar:renderer] TINVAR_ALLOW_UNSCRUBBED_ENV is refused in production (${production}=production).`,
+  );
+  process.exit(78);
+}
+if (unsandboxed) {
+  if (production !== undefined) {
+    console.error(
+      `[tinvar:renderer] TINVAR_RENDERER_UNSANDBOXED is refused in production (${production}=production).`,
+    );
+    process.exit(78);
+  }
+  // A pool is made of sandboxed renderers and nothing else; there is no
+  // unsandboxed pool to fall back to.
+  if (processes !== null) {
+    console.error(
+      '[tinvar:renderer] --processes runs sandboxed renderers, so it cannot be combined with TINVAR_RENDERER_UNSANDBOXED.',
+    );
+    process.exit(64);
+  }
+  console.error(
+    '[tinvar:renderer] WARNING: running WITHOUT the sandbox; every dependency can read any file.',
+  );
+  // Without the sandbox's files, but with its environment: a credential
+  // refused loudly, as a sandboxed launch refuses it, and everything else
+  // cut down to the allowlist the sandboxed child is given.
+  if (!unscrubbed) {
+    try {
+      assertScrubbedEnvironment();
+    } catch (error) {
+      console.error(`[tinvar:renderer] ${error.message}`);
+      process.exit(78);
+    }
+  }
+  scrubEnvironment();
+}
+
+// Read before the environment was scrubbed, which takes the variable with it.
+if (!isSandboxed() && !unsandboxed) {
+  // Checked here as well as in the child, which now sees only an allowlisted
+  // environment and so would pass whatever this process holds.
+  if (!unscrubbed) assertScrubbedEnvironment();
+
+  const entry = appEntry.startsWith('/') ? appEntry : new URL(appEntry, `file://${process.cwd()}/`).pathname;
+  const script = real(fileURLToPath(import.meta.url));
+  // Each renderer's allowlist names its own socket, so each gets its own.
+  const flagsFor = (socket) =>
+    sandboxFlags({
+      rendererRoot: fileURLToPath(new URL('..', import.meta.url)),
+      appEntry: entry,
+      socketPath: socket,
+      extraRead: (process.env.TINVAR_RENDERER_READ ?? '').split(':'),
+      appRoot: process.env.TINVAR_APP_ROOT || undefined,
+    });
+
+  if (processes !== null) {
+    const { prepareDirectory, runPool } = await import('../src/pool.js');
+    // Made and checked before anything starts, and named by its real path:
+    // each renderer's allowlist is written in real paths, as a single
+    // renderer's is.
+    try {
+      prepareDirectory(path.resolve(socketPath), { socketGroup });
+    } catch (error) {
+      console.error(`[tinvar:renderer] ${error.message}`);
+      process.exit(73);
+    }
+    const directory = real(socketPath);
+    // What each renderer is told is what a single launch passes on, less
+    // what only this process acts on.
+    const passed = launched(
+      options.filter(
+        (o) =>
+          !o.startsWith('--processes=') && o !== '--exit-with-stdin' && !o.startsWith('--exit-with-pid='),
+      ),
+    );
+
+    process.exit(
+      await runPool({
+        directory,
+        processes,
+        codec,
+        socketGroup,
+        timings: { drainMs },
+        // Detached: a terminal's Ctrl-C reaches this process alone, which
+        // then drains every renderer, rather than each renderer deciding for
+        // itself while this one is still restarting it.
+        spawn: (socket) =>
+          spawnSandboxed(script, [socket, real(entry), ...passed], flagsFor(socket), { detached: true }),
+      }),
+    );
+  }
+
+  const flags = flagsFor(socketPath);
+  // Created here, before the sandbox: inside it the renderer may write its
+  // socket and nothing else.
+  const { lstatSync, mkdirSync } = await import('node:fs');
+  const made = mkdirSync(path.dirname(path.resolve(socketPath)), { recursive: true, mode: 0o700 });
+  // A directory made here is shared as the socket will be; one that was
+  // there is the deployment's, as it was.
+  if (made !== undefined && socketGroup !== null) {
+    await shareDirectory(path.dirname(path.resolve(socketPath)), socketGroup);
+  }
+
+  // The child may read and write this one path. Something already there
+  // that is not a socket -- a symlink planted in a shared directory -- would
+  // be followed, so it is refused before the child exists.
+  const existing = (() => {
+    try {
+      return lstatSync(socketPath);
+    } catch {
+      return null;
+    }
+  })();
+  if (existing && !existing.isSocket()) {
+    console.error(
+      `[tinvar:renderer] Refusing ${socketPath}: something other than a socket is already there.`,
+    );
+    process.exit(73);
+  }
+
+  // The child is handed the real paths its allowlist was written for, as
+  // arguments -- whichever way they arrived here. Given through
+  // TINVAR_RENDERER_SOCKET or TINVAR_APP_ENTRY, they reached the child as
+  // written, and the allowlist (in real paths) refused them.
+  const args = [real(socketPath), real(entry), ...launched(options)];
+  process.exit(await relaunchSandboxed(script, args, flags));
+}
+
+// Inside the sandbox, before the app or any of its dependencies is imported.
+if (isSandboxed()) {
+  lockNetwork({
+    net: (await import('node:net')).default,
+    dgram: (await import('node:dgram')).default,
+    dns: (await import('node:dns')).default,
+    listenOn: socketPath,
+  });
+  // Named ESM imports of a builtin are a copy, refreshed only on request.
+  (await import('node:module')).syncBuiltinESMExports();
+}
+
+const renderer = await createRenderer({
+  socketPath,
+  appEntry: appEntry.startsWith('/') ? appEntry : new URL(appEntry, `file://${process.cwd()}/`).pathname,
+  codec,
+  checkEnvironment: !unscrubbed,
+  socketGroup,
+});
+
+console.log(
+  `[tinvar:renderer] listening on ${renderer.socketPath} (${renderer.codec}, ${process.env.NODE_ENV})`,
+);
+
+// Graceful: no new renders, the open ones finished, within the drain time.
+// Asked again -- a pool stopping, then its tether closing -- it is the same
+// drain.
+const shutDown = () => renderer.drain(drainMs).then(() => process.exit(0));
+
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, shutDown);
+
+// Launched by the sandbox's parent: when that process is gone, by any
+// signal, so is the reason to serve. Its end of the tether closes with it.
+if (isSandboxed()) watchTether(shutDown);

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@tinvar/renderer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "license": "MIT",
+  "files": [
+    "src",
+    "bin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./src/server.js",
+  "exports": {
+    ".": "./src/server.js",
+    "./vite": "./src/vite.js",
+    "./warm": {
+      "types": "./src/warm.d.ts",
+      "default": "./src/warm.js"
+    },
+    "./vitest": {
+      "types": "./src/vitest.d.ts",
+      "default": "./src/vitest.js"
+    },
+    "./eslint": "./src/eslint.js",
+    "./workbench": {
+      "types": "./src/workbench.d.ts",
+      "default": "./src/workbench.js"
+    }
+  },
+  "dependencies": {
+    "@msgpack/msgpack": "3.1.3",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "react-server-dom-webpack": "19.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitejs/plugin-rsc": "^0.5.38",
+    "vite": "^8.3.5"
+  },
+  "bin": {
+    "tinvar-renderer": "./bin/renderer.js"
+  }
+}