@volter/twin-world 0.1.0 → 0.1.2

package/src/pglite-host.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// One managed-infrastructure postgres service, served without a container:
+// PGlite (real Postgres compiled to WASM) behind a pg-gateway wire-protocol
+// front. Spawned by `volter-world-managed-infra` when the pglite backing is
+// selected; never operated directly (the same contract as the compose file).
+//
+// Plain .mjs under node, deliberately: PGlite's WASM init does not complete
+// under bun, and under node its create() promise only progresses while
+// something holds the event loop — an interval carries the init, and the TCP
+// server starts listening only once the backend is ready, so a port that
+// answers is a port that serves.
+//
+// PGlite is a SINGLE-SESSION backend, so this host serializes connections
+// with a transaction-affinity lock: a connection acquires the global lock at
+// its first protocol message and keeps it for as long as the backend reports
+// an open transaction (ReadyForQuery status != 'I'). Without the hold, two
+// pooled clients interleave into one session and a ROLLBACK on one swallows
+// the other's writes. A connection that dies mid-transaction is rolled back
+// before the lock is released.
+//
+// Identity is aliased, not faked: trust auth accepts the world's declared
+// user/password/database, but the backend is PGlite's single `postgres`
+// database — apps that introspect current_database() will see that. Worlds
+// accept this; an app needing true multi-database Postgres needs the
+// container backing.
+import net from 'node:net';
+import { mkdirSync } from 'node:fs';
+import { PGlite } from '@electric-sql/pglite';
+import { fromNodeSocket } from 'pg-gateway/node';
+
+function arg(name) {
+  const index = process.argv.indexOf(name);
+  const value = index >= 0 ? process.argv[index + 1] : undefined;
+  if (!value) {
+    process.stderr.write(`pglite-host: ${name} is required\n`);
+    process.exit(2);
+  }
+  return value;
+}
+
+const port = Number(arg('--port'));
+const dataDir = arg('--data');
+if (!Number.isInteger(port) || port < 1 || port > 65535) {
+  process.stderr.write('pglite-host: --port must be 1-65535\n');
+  process.exit(2);
+}
+
+mkdirSync(dataDir, { recursive: true });
+// stdio may be a log fd whose reader is gone; never die on a status line
+process.stdout.on('error', () => {});
+process.stderr.on('error', () => {});
+// PGlite's create() only progresses while something holds the event loop;
+// listening starts AFTER readiness so "port answers" means "serves queries"
+const initKeepAlive = setInterval(() => {}, 500);
+const dbReady = PGlite.create({ dataDir });
+dbReady.catch((error) => {
+  process.stderr.write(`pglite-host: backend failed to start: ${error?.message ?? error}\n`);
+  process.exit(1);
+});
+
+// ---- transaction-affinity lock ---------------------------------------------
+let holder = null;
+const waiters = [];
+async function acquire(token) {
+  while (holder !== null && holder !== token) {
+    await new Promise((resolve) => waiters.push(resolve));
+  }
+  holder = token;
+}
+function release(token) {
+  if (holder !== token) return;
+  holder = null;
+  const next = waiters.shift();
+  if (next) next();
+}
+
+/** The transaction status of the LAST ReadyForQuery ('Z') message in a raw
+ * protocol response, or null when the response carries none (mid-pipeline:
+ * the sender keeps the lock). 'I' = idle, 'T' = in transaction, 'E' = failed
+ * transaction. */
+function lastReadyStatus(response) {
+  let status = null;
+  let offset = 0;
+  while (offset + 5 <= response.length) {
+    const type = response[offset];
+    const length = (response[offset + 1] << 24) | (response[offset + 2] << 16)
+      | (response[offset + 3] << 8) | response[offset + 4];
+    if (length < 4) break; // malformed; stop scanning rather than loop
+    if (type === 0x5a /* 'Z' */ && offset + 5 < response.length) {
+      status = String.fromCharCode(response[offset + 5]);
+    }
+    offset += 1 + length;
+  }
+  return status;
+}
+
+const server = net.createServer(async (socket) => {
+  const token = {};
+  let holding = false;
+  socket.on('close', () => {
+    if (!holding) return;
+    // the client vanished inside its transaction: roll it back, then let the
+    // next connection in — never leak a half-open transaction into a stranger
+    void dbReady
+      .then((db) => db.query('ROLLBACK'))
+      .catch(() => {})
+      .then(() => {
+        holding = false;
+        release(token);
+      });
+  });
+  socket.on('error', () => { /* close handler owns cleanup */ });
+  await fromNodeSocket(socket, {
+    serverVersion: '18.3 (PGlite)',
+    auth: { method: 'trust' },
+    async onMessage(data, { isAuthenticated }) {
+      if (!isAuthenticated) return undefined; // gateway owns startup/auth traffic
+      const db = await dbReady;
+      await acquire(token);
+      holding = true;
+      const response = await db.execProtocolRaw(data);
+      const status = lastReadyStatus(response);
+      if (status === 'I') {
+        holding = false;
+        release(token);
+      }
+      return response;
+    },
+  });
+});
+
+void dbReady.then(() => {
+  clearInterval(initKeepAlive);
+  server.listen(port, '127.0.0.1', () => {
+    process.stdout.write(`pglite-host serving postgres wire protocol on 127.0.0.1:${port}\n`);
+  });
+});
+
+for (const signal of ['SIGTERM', 'SIGINT']) {
+  process.on(signal, () => {
+    server.close(() => {
+      void dbReady.then((db) => db.close()).finally(() => process.exit(0));
+    });
+    // a hung close must not make `down` hang the world
+    setTimeout(() => process.exit(0), 3000).unref();
+  });
+}

package/src/prerequisites.ts

@@ -1,9 +1,6 @@
-import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
-export type PrerequisiteId = 'docker';
+export type PrerequisiteId = 'local-execution';
 
 export type PrerequisiteCheck = {
   id: PrerequisiteId;
@@ -26,75 +23,35 @@ const realRunner: Runner = (cmd, args) => {
   };
 };
 
-function trim(value: string): string {
-  return value.trim();
-}
-
-function dockerContextHost(runner: Runner): { context?: string; host?: string } {
-  const contextResult = runner('docker', ['context', 'show']);
-  const context = contextResult.status === 0 ? trim(contextResult.stdout) : undefined;
-  if (!context) return {};
-
-  const inspect = runner('docker', ['context', 'inspect', context]);
-  if (inspect.status !== 0 || !inspect.stdout.trim()) return { context };
-  try {
-    const parsed = JSON.parse(inspect.stdout) as Array<{ Endpoints?: { docker?: { Host?: string } } }>;
-    return { context, host: parsed[0]?.Endpoints?.docker?.Host };
-  } catch {
-    return { context };
-  }
-}
-
-function commonDockerGuidance(details: Record<string, string>): string[] {
-  const guidance = [
-    'Start the computer-native Docker-compatible runtime before running this world.',
-    'If you are an AI agent running this command, it is your job to start that local runtime now; do not hand this back to the user unless the runtime cannot be started from the machine.',
-    'Agents should boot the runtime installed on this machine: `colima start` for Colima, open/start Docker Desktop for Docker Desktop, or start the native Docker service on Linux.',
-  ];
-
-  if (details.context || details.host) {
-    guidance.push(`Active Docker context${details.context ? ` '${details.context}'` : ''}${details.host ? ` points at ${details.host}` : ''}.`);
-  }
-
-  const colimaSocket = join(homedir(), '.colima', 'default', 'docker.sock');
-  if (existsSync(colimaSocket)) {
-    guidance.push(`A Colima socket exists at ${colimaSocket}; if the Docker context points elsewhere, update the context or export DOCKER_HOST=unix://${colimaSocket}.`);
-  }
-
-  return guidance;
-}
-
-export function checkDockerRuntime(runner: Runner = realRunner): PrerequisiteCheck {
+/** Private implementation probe behind the public World capability name. Its implementation and
+ * diagnostics never become instructions for application agents. */
+export function checkLocalExecution(runner: Runner = realRunner): PrerequisiteCheck {
   const info = runner('docker', ['info']);
   if (info.status === 0) {
     return {
-      id: 'docker',
+      id: 'local-execution',
       ok: true,
-      label: 'Docker-compatible daemon',
-      message: 'Docker-compatible daemon is reachable.',
+      label: 'Local execution',
+      message: 'Local execution capacity is available.',
       guidance: [],
     };
   }
 
-  const context = dockerContextHost(runner);
-  const details: Record<string, string> = {};
-  if (context.context) details.context = context.context;
-  if (context.host) details.host = context.host;
-  if (info.stderr.trim()) details.error = info.stderr.trim();
-
   return {
-    id: 'docker',
+    id: 'local-execution',
     ok: false,
-    label: 'Docker-compatible daemon',
-    message: 'Docker-compatible daemon is not reachable.',
-    guidance: commonDockerGuidance(details),
-    details,
+    label: 'Local execution',
+    message: 'Local execution capacity is unavailable.',
+    guidance: [
+      'Run the World through `volter-world up`, then use `volter-world doctor <world>` and its declared service log if startup still fails.',
+      'Do not start, inspect, or clean up a backing runtime separately; the declared World service owns it.',
+    ],
   };
 }
 
 export function checkPrerequisites(ids: PrerequisiteId[], runner: Runner = realRunner): PrerequisiteCheck[] {
   return ids.map((id) => {
-    if (id === 'docker') return checkDockerRuntime(runner);
+    if (id === 'local-execution') return checkLocalExecution(runner);
     throw new Error(`Unknown prerequisite: ${id}`);
   });
 }