@volter/world-runtime 3.0.100 → 3.0.102

package/dist/src/cli-commands.js

@@ -57,7 +57,7 @@ function printHelp() {
                                                   # emission. Exit 0 = ready to \`up\`; exit 1 = the honest worklist.
                                                   # Deterministic: same repo + same pack catalog => identical bytes.
                                                   # init DIAGNOSES; it never boots — it prints the exact next commands
-  volter-world up <config> --env-out=<path> [--owner <label>] [--name <name>] [--mode local|share|sealed] [--isolation process|colocated|worker] [--keep-state] [--json] [--root <repo>]
+  volter-world up <config> --env-out=<path> [--owner <label>] [--name <name>] [--mode local|share|sealed] [--isolation process|colocated|worker] [--keep-state] [--app-url <url>] [--json] [--root <repo>]
   volter-world outdated <world> [--json]            — each mounted twin: pinned / mounted / catalog-current version and protocol standing (R17)
   volter-world audit <world> [--json]               — each mounted twin's grade, as the catalog records it (R17)
   volter-world down <name> [--grace-ms <ms>] [--purge] [--if-instance <token>] [--root <repo>]   # SIGTERM, then SIGKILL survivors after the grace (default 5000ms)

package/dist/src/configs.js

@@ -34,7 +34,7 @@ const LEGACY_NESTED = {
     bare: new Set(['name']), resources: new Set(['memoryMiB', 'writableStorageMiB']), catalog: new Set(['sha', 'protocol']),
     root: new Set(['url', 'deploy', 'refresh', 'scope']), refresh: new Set(['every', 'webhook']),
     external: new Set(['up', 'status', 'down', 'discover', 'readyWhen']), discover: new Set(['as', 'source', 'jsonPath', 'pattern']),
-    ready: new Set(['command', 'args', 'httpUrl', 'stdoutMatch', 'timeoutMs', 'intervalMs']), colocate: new Set(['module', 'export', 'scenarioPath']),
+    ready: new Set(['command', 'args', 'httpUrl', 'timeoutMs', 'intervalMs']), colocate: new Set(['module', 'export', 'scenarioPath']),
     share: new Set(['provider', 'command', 'args', 'ephemeral', 'services']), shareService: new Set(['id', 'verifyPath']),
 };
 function unknownKeys(value, known, allowComments = false) {

package/dist/src/mongodb-backing.d.ts

@@ -1,7 +1,8 @@
 import type { HostLaunch, InfraService } from './pglite-backing.js';
 /** PATH is the binary contract, as for the native PostgreSQL example and LiveKit. No acquisition at boot. */
 export declare function mongodbArgv(service: InfraService, data: string): string[];
-/** MongoDB's structured record comes from this child, not a listener already holding the port. */
-export declare function mongodbListening(log: string, port: number): boolean;
+/** Whether the server answering MongoDB's protocol on the port is this child: its own serverStatus names its pid. A
+ *  listener that is not answering yet, or another process's server on the port, is not. */
+export declare function mongodbServes(service: InfraService, pid: number): Promise<boolean>;
 /** Ping the server; initialize only an explicitly declared one-member set and await its primary. */
 export declare function mongodbReady(service: InfraService, launch: HostLaunch, deadline: number, initialize?: boolean): Promise<void>;

package/dist/src/mongodb-backing.js

@@ -3,17 +3,22 @@ export function mongodbArgv(service, data) {
     return ['mongod', '--bind_ip', '127.0.0.1', '--port', String(service.hostPort), '--dbpath', data,
         ...(service.replicaSet ? ['--replSet', service.replicaSet] : [])];
 }
-/** MongoDB's structured record comes from this child, not a listener already holding the port. */
-export function mongodbListening(log, port) {
-    return log.split('\n').some((line) => {
-        try {
-            const record = JSON.parse(line);
-            return record.id === 23016 && record.msg === 'Waiting for connections' && record.attr?.port === port;
-        }
-        catch {
-            return false;
-        } // Non-JSON log lines are not the structured readiness record.
-    });
+/** Whether the server answering MongoDB's protocol on the port is this child: its own serverStatus names its pid. A
+ *  listener that is not answering yet, or another process's server on the port, is not. */
+export async function mongodbServes(service, pid) {
+    const { MongoClient } = await import('mongodb');
+    const client = new MongoClient(`mongodb://127.0.0.1:${service.hostPort}`, { directConnection: true, timeoutMS: 1000, serverSelectionTimeoutMS: 1000 });
+    try {
+        await client.connect();
+        const status = await client.db('admin').command({ serverStatus: 1 });
+        return Number(status.pid) === pid;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
 }
 /** Ping the server; initialize only an explicitly declared one-member set and await its primary. */
 export async function mongodbReady(service, launch, deadline, initialize = true) {

package/dist/src/pglite-backing.js

@@ -12,7 +12,8 @@
 // services only. A definition declaring mysql without a container runtime is
 // refused with the kinds named, never half-booted. Redis never reaches it: every
 // redis service is the redis twin's (redis-backing.ts).
-import { appendFileSync, closeSync, cpSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { appendFileSync, closeSync, cpSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { connect } from 'node:net';
 import { dirname, join } from 'node:path';
 import { spawn } from 'node:child_process';
@@ -22,7 +23,7 @@ import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnRecei
 import { errorMessage } from "./error-message.js";
 import { fileURLToPath } from 'node:url';
 import { parse } from 'yaml';
-import { mongodbArgv, mongodbListening, mongodbReady } from "./mongodb-backing.js";
+import { mongodbArgv, mongodbReady, mongodbServes } from "./mongodb-backing.js";
 /** Read the generated definition's loopback port mappings. MongoDB may explicitly request
  *  one replica-set member through its Compose-compatible command; other mongod options are refused. */
 export function parseInfraDefinition(text) {
@@ -149,13 +150,52 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export function unsupportedKinds(services) {
     return [...new Set(services.filter((s) => CONTAINERLESS[s.kind] === undefined).map((s) => s.kind))];
 }
-/** The line each host prints once ITS OWN listener is bound: readiness is taken from the child, never
- *  from a connect to the port, which any other process holding the port would answer. */
-function readyLine(port) {
-    return `serving postgres wire protocol on 127.0.0.1:${port}`;
+/**
+ * What `up` means for a managed database (architecture, managed infrastructure): it answers its own protocol on its
+ * port, as pg_isready and a compose healthcheck ask, and the answer is this host's. Readiness never reads a log line.
+ * The PGlite host writes its own listener receipt once its socket is bound ({version, pid, port, boot}, pglite-host.mjs
+ * --listening-file); MongoDB's server names its own pid in serverStatus. The log is for people.
+ */
+function listeningReceiptPath(pidFile) {
+    return pidFile.replace(/\.pid$/, '.listening.json');
+}
+function listeningReceipt(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const value = JSON.parse(text);
+        if (value.version !== 1 || !Number.isSafeInteger(value.pid) || !Number.isSafeInteger(value.port))
+            return undefined;
+        return { pid: value.pid, port: value.port, boot: typeof value.boot === 'string' ? value.boot : null };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Postgres's own first exchange: an SSLRequest answered with one byte, 'N' or 'S' (pg_isready's question). */
+function postgresAnswers(port) {
+    return new Promise((resolve) => {
+        const socket = connect({ host: '127.0.0.1', port, timeout: 1000 });
+        socket.once('connect', () => socket.write(Buffer.from([0, 0, 0, 8, 0x04, 0xd2, 0x16, 0x2f])));
+        socket.once('data', (chunk) => { socket.destroy(); resolve(chunk[0] === 0x4e || chunk[0] === 0x53); });
+        socket.on('error', () => resolve(false));
+        socket.on('timeout', () => { socket.destroy(); resolve(false); });
+    });
 }
-function logSince(log, offset) {
-    return readFileSync(log).subarray(offset).toString('utf8');
+/** Whether this host serves: its own receipt names it on the port (for this boot, when one is given), and the port
+ *  answers the service's protocol. */
+async function hostServes(service, pidFile, pid, boot) {
+    if (service.kind === 'mongodb')
+        return mongodbServes(service, pid);
+    const receipt = listeningReceipt(listeningReceiptPath(pidFile));
+    if (!receipt || receipt.pid !== pid || receipt.port !== service.hostPort || (boot !== undefined && receipt.boot !== boot))
+        return false;
+    return postgresAnswers(service.hostPort);
 }
 /**
  * A World's PostgreSQL cluster prepared before its first boot (architecture, managed infrastructure; ADR 0018).
@@ -274,8 +314,10 @@ export async function pgliteUp(services, dataDir, launch = {}) {
                 appendFileSync(log, `${placed.note}\n`);
                 launch.note?.(placed.note);
             }
-            const offset = existsSync(log) ? statSync(log).size : 0;
-            const [command, ...args] = placed.placed ? [...argv, '--prepared'] : argv;
+            // This boot's token, which the host writes into its listener receipt; an earlier receipt is never this one's.
+            const boot = randomUUID();
+            rmSync(listeningReceiptPath(pidFile), { force: true });
+            const [command, ...args] = [...(placed.placed ? [...argv, '--prepared'] : argv), ...(service.kind === 'postgres' ? ['--listening-file', listeningReceiptPath(pidFile), '--boot', boot] : [])];
             // a real fd, not a pipe: the host must outlive this process untethered
             const logFd = openSync(log, 'a');
             const child = spawn(command, args, {
@@ -305,10 +347,10 @@ export async function pgliteUp(services, dataDir, launch = {}) {
             publishProcessReceipt(pidFile, `${child.pid}\n`);
             launch.note?.(`${name} spawned`);
             const deadline = Date.now() + READY_TIMEOUT_MS;
-            const line = readyLine(service.hostPort);
-            // ready when OUR child says its listener is bound (a squatter that took the port after the check
-            // above makes the child fail its bind and exit, never print this) and the port answers
-            while (!(alive(child.pid) && (service.kind === 'mongodb' ? mongodbListening(logSince(log, offset), service.hostPort) : logSince(log, offset).includes(line)) && await listening(service.hostPort))) {
+            // Ready when the port answers the service's protocol and the answer is this child's: its own receipt (PGlite)
+            // or its own serverStatus (MongoDB). A squatter that took the port after the check above makes the child fail
+            // its bind and exit, and never answers as this child.
+            while (!(alive(child.pid) && await hostServes(service, pidFile, child.pid, service.kind === 'postgres' ? boot : undefined))) {
                 if (spawnError)
                     throw spawnError;
                 if (!alive(child.pid))
@@ -317,7 +359,6 @@ export async function pgliteUp(services, dataDir, launch = {}) {
                     throw new Error(`${name} did not serve port ${service.hostPort} within ${READY_TIMEOUT_MS / 1000}s — see ${log}`);
                 // an aborted boot (Ctrl-C during up) stops waiting; the catch below ends what this up started
                 launch.signal?.throwIfAborted();
-                // the ready line is a small log read, and the port is asked only once it is there
                 await sleep(25);
             }
             launch.note?.(`${name} serving on 127.0.0.1:${service.hostPort}`);
@@ -349,7 +390,7 @@ export async function pgliteStatus(services, dataDir) {
         const ownership = hostOwnership(pidFile);
         if (ownership.errors.length)
             throw new AggregateError(ownership.errors, 'Managed infrastructure ownership uncertain; retry down');
-        if (!ownership.readyReceipt || !ownership.pid || !alive(ownership.pid) || !(await listening(service.hostPort)))
+        if (!ownership.readyReceipt || !ownership.pid || !alive(ownership.pid) || !(await hostServes(service, pidFile, ownership.pid)))
             continue;
         if (ownership.identity)
             await verifySpawnIdentity(ownership.identity);

package/dist/src/pglite-host.mjs

@@ -63,7 +63,7 @@
 // Randomness remains the host's own; no database schema objects are installed.
 import { errorMessage } from './error-message.mjs';
 import net from 'node:net';
-import { mkdirSync, readFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import clockForm from '@volter/world-core/world-clock';
 import { fromNodeSocket } from 'pg-gateway/node';
 import { BackendError } from 'pg-gateway';
@@ -122,6 +122,12 @@ function arg(name) {
 // path a serving host takes, close it cleanly and exit without listening. The World's image build runs it on the
 // host so the tab opens an existing cluster (pglite-backing.ts, pglitePrepare).
 const preparing = process.argv.includes('--prepare');
+// --listening-file <path> --boot <token>: once the listener is bound, the host writes its own receipt there
+// ({version, pid, port, boot}); the backing reads it as this host's ownership of the port (pglite-backing.ts). Readiness
+// is the port answering Postgres's own protocol; the stdout line is for people only.
+const optional = (name) => { const index = process.argv.indexOf(name); return index >= 0 ? process.argv[index + 1] : undefined; };
+const listeningFile = optional('--listening-file');
+const bootToken = optional('--boot');
 // --prepared: the data directory is a cluster `--prepare` made for this declared identity (pglite-backing.ts checks
 // its stamp before passing this), so the declared database and role exist and the maintenance open is skipped.
 const prepared = process.argv.includes('--prepared');
@@ -649,6 +655,11 @@ if (preparing) void dbReady.then(async (db) => {
 else void dbReady.then(() => {
   clearInterval(initKeepAlive);
   server.listen(port, '127.0.0.1', () => {
+    if (listeningFile) {
+      const temporary = `${listeningFile}.${process.pid}.tmp`;
+      writeFileSync(temporary, `${JSON.stringify({ version: 1, pid: process.pid, port, boot: bootToken ?? null })}\n`, { mode: 0o600 });
+      renameSync(temporary, listeningFile);
+    }
     process.stdout.write(`pglite-host serving postgres wire protocol on 127.0.0.1:${port}\n`);
   });
 });

package/dist/src/process-signal.mjs

@@ -20,10 +20,19 @@ export async function processBirth(pid) {
     } catch { return undefined; }
   }
   return new Promise(resolve => {
-    const child = spawn('ps', ['-o', 'pid=,lstart=', '-p', String(pid)], {
-      windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'],
-      env: { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' },
-    });
+    // A probe that cannot run is a birth unknown, never a lifecycle failure: spawn throws synchronously where the
+    // process may not exec `ps` at all (setuid root on macOS, which a sandbox-exec profile refuses: EPERM), and reports
+    // other failures as 'error' (below). Either way the identity is the pid without a start time.
+    let child;
+    try {
+      child = spawn('ps', ['-o', 'pid=,lstart=', '-p', String(pid)], {
+        windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'],
+        env: { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' },
+      });
+    } catch {
+      resolve(undefined);
+      return;
+    }
     let output = '', settled = false;
     const finish = value => { if (!settled) { settled = true; clearTimeout(timer); child.stdout.destroy(); resolve(value); } };
     // This is our still-held inspector, not a PID from a receipt.

package/dist/src/redis-backing.js

@@ -55,6 +55,33 @@ function listening(port) {
         socket.on('timeout', () => { socket.destroy(); resolve(false); });
     });
 }
+/** Whether the Redis answering on the port is this child (architecture D9): its own INFO server names its process_id, as
+ *  Redis's does. A port that answers as another process, or does not answer yet, is not this child's. */
+function redisServes(port, pid) {
+    return new Promise((resolve) => {
+        const socket = connect({ host: '127.0.0.1', port, timeout: 1000 });
+        let reply = '';
+        socket.once('connect', () => socket.write('*2\r\n$4\r\nINFO\r\n$6\r\nserver\r\n'));
+        socket.on('data', (chunk) => {
+            reply += chunk.toString('latin1');
+            // a bulk string: $<length>\r\n<body>\r\n
+            const head = /^\$(\d+)\r\n/.exec(reply);
+            if (!head) {
+                if (!reply.startsWith('$') || reply.includes('\r\n')) {
+                    socket.destroy();
+                    resolve(false);
+                }
+                return;
+            }
+            if (Buffer.byteLength(reply, 'latin1') < head[0].length + Number(head[1]) + 2)
+                return;
+            socket.destroy();
+            resolve(Number(/(?:^|\r\n)process_id:(\d+)\r\n/.exec(reply.slice(head[0].length))?.[1]) === pid);
+        });
+        socket.on('error', () => resolve(false));
+        socket.on('timeout', () => { socket.destroy(); resolve(false); });
+    });
+}
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export async function redisTwinUp(services, dataDir, cli, launch = {}) {
     for (const service of services) {
@@ -99,13 +126,13 @@ export async function redisTwinUp(services, dataDir, cli, launch = {}) {
             publishProcessReceipt(spawnReceiptPath(pidFile), JSON.stringify(identity) + '\n');
             publishProcessReceipt(pidFile, `${held.child.pid}\n`);
             const deadline = Date.now() + READY_TIMEOUT_MS;
-            while (!(await listening(service.hostPort)) || !alive(held.child.pid)) {
+            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(200);
+                await sleep(25);
             }
             launch.signal?.throwIfAborted();
             held.child.unref();
@@ -129,7 +156,8 @@ export async function redisTwinStatus(services, dataDir) {
         const pidFile = pidPath(dataDir, service);
         if (!existsSync(pidFile))
             continue;
-        if (alive(Number(readFileSync(pidFile, 'utf8').trim())) && await listening(service.hostPort))
+        const pid = Number(readFileSync(pidFile, 'utf8').trim());
+        if (alive(pid) && await redisServes(service.hostPort, pid))
             ready += 1;
     }
     return ready;