@volter/world-runtime 3.0.163 → 3.0.165

package/src/redis-backing.ts

@@ -8,41 +8,15 @@
 // 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 (the Redis pack's storage module). It needs nothing
 // installed: no container runtime, no redis-server binary.
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync } from 'node:fs';
+//
+// The lifecycle (start, ownership, readiness, retirement) is every twin-served service's and lives in
+// twin-backing.ts, and the pack that serves the kind is found there from pack facts (`managedService`), not named
+// here. This file is what is Redis's own in the runtime: the two questions asked in Redis's protocol.
 import { connect } from 'node:net';
-import { dirname, join } from 'node:path';
-import { commandLifetime, COMMAND_GRACE_MS, COMMAND_CONFIRM_MS } from './command-lifetime.ts';
-import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnReceiptPath, signalOwnedProcess } from './process-receipt.ts';
-import { spawn, type ChildProcess } from 'node:child_process';
-import { survivingOwnedGroups } from './process-groups.ts';
-import { errorMessage } from './error-message.ts';
-import { findInstalledPackage, packCli } from './catalog.ts';
-import { vendorPackageDir } from '@volter/world-core/runtime';
+import { join } from 'node:path';
+import { managedDirectory, managedTwin, twinBackingCli, twinBackingDown, twinBackingStatus, twinBackingUp, type ManagedProtocol, type TwinServedBacking } from './twin-backing.ts';
 import type { HostLaunch, InfraService } from './pglite-backing.ts';
 
-interface RedisHost { child: ChildProcess; lifetime: ReturnType<typeof commandLifetime>; closed: boolean }
-const hosts = new Map<string, RedisHost>();
-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 = vendorPackageDir(dir, 'redis') ?? 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 (error) { if ((error as NodeJS.ErrnoException).code === 'ESRCH') return false; throw error; }
-}
-
 function listening(port: number): Promise<boolean> {
   return new Promise((resolve) => {
     const socket = connect({ host: '127.0.0.1', port, timeout: 1000 });
@@ -75,108 +49,17 @@ function redisServes(port: number, pid: number): Promise<boolean> {
   });
 }
 
-const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+export const REDIS_PROTOCOL: ManagedProtocol = { name: 'Redis', answers: listening, serves: redisServes };
+const twin = (): TwinServedBacking => {
+  const found = managedTwin('redis', REDIS_PROTOCOL);
+  if (!found) throw new Error('no pack declares the redis kind (managedService) in pack facts');
+  return found;
+};
 
-export async function redisTwinUp(services: InfraService[], dataDir: string, cli: string, launch: HostLaunch = {}): Promise<void> {
-  for (const service of services) {
-    const pidFile = pidPath(dataDir, service);
-    if (hosts.has(pidFile) || existsSync(pidFile) || existsSync(spawnReceiptPath(pidFile))) {
-      await redisTwinDown([service], dataDir);
-    }
-    // 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'];
-    let held: RedisHost | undefined;
-    try {
-      try {
-        const child = spawn(process.execPath, [...runtime, cli, 'serve', '--port', String(service.hostPort), '--root', root], {
-          env: launch.env ?? process.env, detached: true, windowsHide: true, stdio: ['ignore', logFd, logFd],
-        });
-        // Retain BEFORE descriptor close, birth capture or either publication can fail.
-        held = { child, lifetime: commandLifetime(child, launch.signal), closed: false };
-        const observed = held;
-        child.once('close', () => { observed.closed = true; });
-        child.on('error', () => {}); // lifetime joins spawn failure and close
-        hosts.set(pidFile, held);
-      } finally { closeSync(logFd); }
-      if (!held.child.pid) throw new Error('Redis child did not start');
-      const identity = await held.lifetime.identity;
-      if (!identity?.start) throw new Error('Redis birth capture failed; retiring held child');
-      publishProcessReceipt(spawnReceiptPath(pidFile), JSON.stringify(identity) + '\n');
-      publishProcessReceipt(pidFile, `${held.child.pid}\n`);
-      const deadline = Date.now() + READY_TIMEOUT_MS;
-      while (!alive(held.child.pid) || !(await redisServes(service.hostPort, held.child.pid))) {
-        if (!alive(held.child.pid)) throw new Error(`redis exited before serving — see ${log}`);
-        launch.signal?.throwIfAborted();
-        if (Date.now() > deadline) throw new Error(`redis did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
-        await sleep(25);
-      }
-      launch.signal?.throwIfAborted();
-      held.child.unref();
-    } catch (error) {
-      if (held) {
-        try { await redisTwinDown([service], dataDir); }
-        catch (cleanup) { throw new AggregateError([error, cleanup], 'Redis startup and retirement failed; ownership retained'); }
-      }
-      throw error;
-    }
-  }
-}
-
-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;
-    const pid = Number(readFileSync(pidFile, 'utf8').trim());
-    if (alive(pid) && await redisServes(service.hostPort, pid)) ready += 1;
-  }
-  return ready;
-}
-
-export async function redisTwinDown(services: InfraService[], dataDir: string): Promise<void> {
-  for (const service of services) {
-    const pidFile = pidPath(dataDir, service);
-    const recorded = readProcessReceipt(pidFile, text => {
-      const pid = Number(text.trim());
-      if (!Number.isInteger(pid) || pid <= 0) throw new Error('Invalid Redis ownership PID');
-      return pid;
-    });
-    const identity = readSpawnReceipt(pidFile);
-    const held = hosts.get(pidFile);
-    if (recorded.error || identity.error) process.stderr.write(`${errorMessage(new AggregateError([recorded.error, identity.error].filter(Boolean), 'Redis ownership uncertain; retrying established ownership'))}\n`);
-    if (held) {
-      const retired = () => held!.closed && (!held!.child.pid || !survivingOwnedGroups([held!.child.pid]).length);
-      if (!retired()) {
-        held.child.ref(); held.lifetime.cancel('SIGTERM');
-        try { await held.lifetime.finish(); }
-        catch (error) { if (!retired()) throw error; }
-      }
-    } else {
-      if (!recorded.present && !identity.present) continue;
-      const pid = identity.value?.pid ?? recorded.value;
-      if (!pid) throw new AggregateError([recorded.error, identity.error].filter(Boolean), 'Redis ownership uncertain; receipts retained');
-      if (recorded.value && identity.value && recorded.value !== identity.value.pid) throw new Error('Redis ownership receipts disagree; retirement refused; receipts retained');
-      const live = () => survivingOwnedGroups([pid]).length > 0;
-      for (const [signal, limit] of [['SIGTERM', COMMAND_GRACE_MS], ['SIGKILL', COMMAND_CONFIRM_MS]] as const) {
-        if (!live()) break;
-        await signalOwnedProcess(identity.value, signal, true);
-        const deadline = Date.now() + limit;
-        while (live() && Date.now() < deadline) await sleep(20);
-      }
-      if (live()) throw new Error('Redis retirement unconfirmed; receipts retained');
-    }
-    rmSync(pidFile, { force: true });
-    rmSync(spawnReceiptPath(pidFile), { force: true });
-    hosts.delete(pidFile);
-  }
-}
+/** The redis twin's cli: installed beside this runtime (its node_modules walk), else beside the World's config. */
+export const redisTwinCli = (from: string[]): string | undefined => { const found = managedTwin('redis', REDIS_PROTOCOL); return found && twinBackingCli(found, from); };
+/** 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, managedDirectory('redis'));
+export const redisTwinUp = (services: InfraService[], dataDir: string, cli: string, launch: HostLaunch = {}): Promise<void> => twinBackingUp(twin(), services, dataDir, cli, launch);
+export const redisTwinStatus = (services: InfraService[], dataDir: string): Promise<number> => twinBackingStatus(twin(), services, dataDir);
+export const redisTwinDown = (services: InfraService[], dataDir: string): Promise<void> => twinBackingDown(twin(), services, dataDir);