@volter/world-runtime 2.0.0 → 2.0.1

package/src/redis-backing.ts

@@ -0,0 +1,107 @@
+// The containerless backing for a World's managed REDIS: the redis twin (@volter/twin-redis) serving Redis's
+// own protocol on the loopback port the definition declares, its keys held in the World's tree under
+// VOLTER_WORLD_DATA. Chosen by `volter-world-infra` for every redis service unless the operator forces the
+// container backing (VOLTER_WORLD_INFRA_BACKING=docker); the definition, the injected REDIS_URL and the declared
+// service contract are the same either way, as the boundary comment in infra-cli.ts promises.
+//
+// Why the twin and not a container: a World's state branches, checkpoints and rolls back as one tree, and a Redis
+// in a container is state outside it (a branch of the World would share the container's queue and cache). The
+// twin keeps each key a subject of the World (packages/twin/redis/src/redis-storage.ts). It needs nothing
+// installed: no container runtime, no redis-server binary.
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { findInstalledPackage, packCli } from './catalog.ts';
+import type { InfraService } from './pglite-backing.ts';
+
+const PACKAGE = '@volter/twin-redis';
+const READY_TIMEOUT_MS = 60_000;
+
+/** The redis twin's cli: installed beside this runtime (its node_modules walk), else beside the World's config. */
+export function redisTwinCli(from: string[]): string | undefined {
+  for (const dir of from) {
+    const found = findInstalledPackage(dir, PACKAGE);
+    const cli = found === undefined ? undefined : packCli(found);
+    if (cli !== undefined && existsSync(cli)) return cli;
+  }
+  return undefined;
+}
+
+const pidPath = (dataDir: string, service: InfraService): string => join(dataDir, `redis-twin-${service.hostPort}.pid`);
+/** Where the service's keys live: the World's tree for the `redis` service, under the World's data. */
+export const redisTwinRoot = (dataDir: string): string => join(dataDir, 'redis-twin');
+
+function alive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function listening(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = connect({ host: '127.0.0.1', port, timeout: 1000 });
+    // a port that answers PING with PONG is this service; anything else is not ready (or not ours)
+    socket.once('connect', () => socket.write('PING\r\n'));
+    socket.once('data', (chunk) => { socket.destroy(); resolve(chunk.toString('latin1').startsWith('+PONG')); });
+    socket.on('error', () => resolve(false));
+    socket.on('timeout', () => { socket.destroy(); resolve(false); });
+  });
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export async function redisTwinUp(services: InfraService[], dataDir: string, cli: string): Promise<void> {
+  for (const service of services) {
+    const pidFile = pidPath(dataDir, service);
+    if (existsSync(pidFile) && alive(Number(readFileSync(pidFile, 'utf8').trim())) && await listening(service.hostPort)) continue;
+    // a port that already answers is another process's (another World's twin, a redis-server): serving there would
+    // hand this World's app someone else's keys, so it is refused, never taken as ready
+    if (await listening(service.hostPort)) throw new Error(`port ${service.hostPort} already serves Redis for another process`);
+    const root = redisTwinRoot(dataDir);
+    mkdirSync(root, { recursive: true });
+    const log = join(dataDir, `redis-twin-${service.hostPort}.log`);
+    mkdirSync(dirname(log), { recursive: true });
+    // a real fd, not a pipe: the server outlives this process untethered
+    const logFd = openSync(log, 'a');
+    // the runtime this runs on: Bun runs the pack's TypeScript as it is; Node (volter-world-infra's shebang) needs
+    // type transformation, not only stripping (the kernel declares constructor parameter properties)
+    const runtime = typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined' || !cli.endsWith('.ts') ? [] : ['--experimental-transform-types', '--no-warnings'];
+    const child = spawn(process.execPath, [...runtime, cli, 'serve', '--port', String(service.hostPort), '--root', root], {
+      detached: true,
+      stdio: ['ignore', logFd, logFd],
+    });
+    child.unref();
+    closeSync(logFd);
+    writeFileSync(pidFile, `${child.pid}\n`);
+    const deadline = Date.now() + READY_TIMEOUT_MS;
+    while (!(await listening(service.hostPort)) || !alive(child.pid!)) {
+      if (!alive(child.pid!)) throw new Error(`redis exited before serving — see ${log}`);
+      if (Date.now() > deadline) throw new Error(`redis did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
+      await sleep(200);
+    }
+  }
+}
+
+export async function redisTwinStatus(services: InfraService[], dataDir: string): Promise<number> {
+  let ready = 0;
+  for (const service of services) {
+    const pidFile = pidPath(dataDir, service);
+    if (!existsSync(pidFile)) continue;
+    if (alive(Number(readFileSync(pidFile, 'utf8').trim())) && await listening(service.hostPort)) ready += 1;
+  }
+  return ready;
+}
+
+export async function redisTwinDown(services: InfraService[], dataDir: string): Promise<void> {
+  for (const service of services) {
+    const pidFile = pidPath(dataDir, service);
+    if (!existsSync(pidFile)) continue;
+    const pid = Number(readFileSync(pidFile, 'utf8').trim());
+    if (alive(pid)) {
+      try { process.kill(pid, 'SIGTERM'); } catch { /* already gone */ }
+      const deadline = Date.now() + 5000;
+      while (alive(pid) && Date.now() < deadline) await sleep(100);
+      if (alive(pid)) { try { process.kill(pid, 'SIGKILL'); } catch { /* raced */ } }
+    }
+    rmSync(pidFile, { force: true });
+  }
+}

package/src/runtime.ts

@@ -17,7 +17,7 @@ import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { packFacts } from './pack-facts.ts';
 import { describeServiceEnd, readServiceEnd, serviceOutput } from './service-exit.ts';
 import { Socket } from 'node:net';
-import { getActiveWorldStore, withFileLock, stateDirName, PROTOCOL_VERSION, PROTOCOL_MAJOR, WORLD_BOOT_PATH, WORLD_ENV_NAMES_ENV } from '@volter/world-core';
+import { getActiveWorldStore, withFileLock, stateDirName, PROTOCOL_VERSION, PROTOCOL_MAJOR, WORLD_BOOT_PATH, WORLD_DATA_ENV, WORLD_ENV_NAMES_ENV } from '@volter/world-core';
 import type { PlanReviewRecord } from '@volter/world-core';
 import { loadWorldConfig } from './configs.ts';
 import { createWorldNetworkPolicy, WORLD_NETWORK_POLICY_ENV } from '@volter/world-core/network-policy';
@@ -798,7 +798,7 @@ async function runExternalCommand(
   command: string[], cwd: string, serviceId: string, phase: string,
   env: NodeJS.ProcessEnv = process.env, abort?: AbortSignal, timeoutMs = 60_000,
 ): Promise<{ stdout: string; stderr: string }> {
-  const [bin, ...args] = command;
+  const [bin, ...args] = ownCommand(command);
   if (!bin) throw new Error(`External service "${serviceId}": ${phase} command is empty`);
   if (!commandExists(bin)) throw new Error(`External service "${serviceId}": \`${bin}\` not found on PATH (the ${phase} command's tool is not installed)`);
   abort?.throwIfAborted();
@@ -832,7 +832,7 @@ async function runExternalUp(
   logPath: string,
   abort?: AbortSignal,
 ): Promise<string> {
-  const [bin, ...args] = command;
+  const [bin, ...args] = ownCommand(command);
   if (!bin) throw new Error(`External service "${serviceId}": up command is empty`);
   if (!commandExists(bin)) {
     throw new Error(`External service "${serviceId}": \`${bin}\` not found on PATH (the up command's tool is not installed)`);
@@ -1456,7 +1456,8 @@ export async function upWorld(configId: string, options: UpWorldOptions = {}, ab
       VOLTER_WORLD_MODE: mode,
       VOLTER_WORLD_CONFIG: loaded.path,
       VOLTER_WORLD_INSTANCE: instanceFile,
-      VOLTER_WORLD_DATA: data,
+      // every service's root is `<data>/<service id>`; the kernel finds another pack's store across them (A3, ownerStoreRoots)
+      [WORLD_DATA_ENV]: data,
       // the live env file this `up` writes: what a service that runs apps elsewhere (world-machine's guest) carries there
       VOLTER_WORLD_ENV_FILE: envFile,
       // THE WORLD CLOCK: every service stamps from this file via the kernel's worldNow();
@@ -2190,8 +2191,24 @@ function sleep(ms: number): Promise<void> {
 
 function commandExists(command: string): boolean {
   // Pass the live env so PATH reflects the current process (some runtimes snapshot env otherwise).
-  const result = spawnSync('which', [command], { stdio: 'ignore', env: process.env });
-  return result.status === 0;
+  return OWN_COMMANDS[command] !== undefined || onPath(command);
+}
+
+/** A lifecycle command naming this runtime's own bin (`volter-world-infra`, which `init` names in every managed
+ *  infrastructure's lifecycle) runs this runtime's own script with the executable running it, when nothing on PATH
+ *  answers the name: a bare `volter-world down` (no runner that put node_modules/.bin on PATH) failed "not found on
+ *  PATH" and left the infrastructure up. Only the name is mapped — no directory joins PATH — and a same-named
+ *  command on PATH still wins, as before. */
+const OWN_COMMANDS: Record<string, string> = { 'volter-world-infra': 'infra-cli' };
+export function ownCommand(command: string[]): string[] {
+  const [bin, ...args] = command;
+  const stem = bin === undefined ? undefined : OWN_COMMANDS[bin];
+  if (stem === undefined || onPath(bin!)) return command;
+  return [process.execPath, siblingScript(import.meta.url, stem), ...args];
+}
+
+function onPath(command: string): boolean {
+  return spawnSync('which', [command], { stdio: 'ignore', env: process.env }).status === 0;
 }
 
 function resolveWithPublicDns(hostname: string): string | undefined {
@@ -2505,7 +2522,8 @@ async function probeExternalOnce(
     if (!commandExists(ready.command)) {
       return { ok: false, message: `readiness command \`${ready.command}\` not found on PATH` };
     }
-    const result = spawnSync(ready.command, ready.args ?? [], {
+    const [probeBin, ...probeArgs] = ownCommand([ready.command, ...(ready.args ?? [])]);
+    const result = spawnSync(probeBin!, probeArgs, {
       cwd, encoding: 'utf8', env, timeout: DOCTOR_EXTERNAL_PROBE_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024,
     });
     if (result.status === 0) return { ok: true, message: 'probe ok (command)' };