@volter/world-runtime 2.0.0

package/dist/src/tcp-port.js

@@ -0,0 +1,36 @@
+import { createServer } from 'node:net';
+/** Select a port and exclude it from later selections. The probe closes before returning. */
+export async function allocatePort(excluded = new Set()) {
+    for (let attempt = 0; attempt < 32; attempt++) {
+        let port;
+        try {
+            port = await probePort();
+        }
+        catch (error) {
+            if (error.code === 'EADDRINUSE')
+                continue;
+            throw error;
+        }
+        if (excluded.has(port))
+            continue;
+        excluded.add(port);
+        return port;
+    }
+    throw new Error('Could not allocate a TCP port after 32 attempts');
+}
+function probePort() {
+    return new Promise((resolvePort, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        // Match serveHttp's default scope; a loopback-only probe can miss a wildcard listener.
+        server.listen(0, '0.0.0.0', () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                server.close(() => reject(new Error('Could not allocate a TCP port')));
+                return;
+            }
+            const port = address.port;
+            server.close((error) => error ? reject(error) : resolvePort(port));
+        });
+    });
+}

package/dist/src/up-task-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/up-task-worker.js

@@ -0,0 +1,61 @@
+import { recordWorldLifecycleEvent } from "./lifecycle-record.js";
+import { upWorld } from "./runtime.js";
+import { loadWorldConfig } from "./configs.js";
+const worldNameOf = (configId, root) => { try {
+    return loadWorldConfig(configId, root).config.id;
+}
+catch {
+    return configId;
+} };
+// The boot's owner (./up-task.ts). Only the caller's explicit cancel aborts the boot; a lost caller does not, and the
+// boot's outcome, which the caller can no longer print, goes to the lifecycle log.
+if (!process.send)
+    throw new Error('World boot owner requires its private lifetime channel');
+const abort = new AbortController();
+let started = false;
+let callerLost = false;
+process.on('disconnect', () => {
+    callerLost = true;
+    if (!started)
+        process.exit(0);
+});
+// A dead caller may also close the output reader. Reporting must not kill the boot.
+process.stdout.on('error', () => { });
+process.stderr.on('error', () => { });
+process.on('message', async (message) => {
+    const request = message;
+    if (request.type === 'cancel') {
+        abort.abort(request.signal);
+        return;
+    }
+    if (request.type !== 'start' || started)
+        return;
+    started = true;
+    let reply;
+    try {
+        reply = { instance: await upWorld(request.configId, request.options, abort.signal) };
+    }
+    catch (error) {
+        reply = { error: error instanceof Error ? error.message : String(error) };
+    }
+    if (callerLost && 'instance' in reply) {
+        try {
+            recordWorldLifecycleEvent(reply.instance.root, reply.instance.name, 'boot completed after its caller went away; the World is up');
+        }
+        catch { /* the World is up regardless */ }
+    }
+    if (callerLost && 'error' in reply) {
+        // The caller that would have printed the reason is gone; the lifecycle log keeps it (upWorld also records its own
+        // boot failure there, but a failure before the lifecycle claim would otherwise leave nothing).
+        try {
+            recordWorldLifecycleEvent(request.options.root ?? process.cwd(), request.options.name ?? worldNameOf(request.configId, request.options.root ?? process.cwd()), `boot failed after its caller went away: ${reply.error}`);
+        }
+        catch { /* nowhere left to write it */ }
+    }
+    if ('error' in reply && !process.connected)
+        process.stderr.write(`${reply.error}\n`);
+    if (process.connected)
+        process.send(reply, () => process.exit('error' in reply ? 1 : 0));
+    else
+        process.exit('error' in reply ? 1 : 0);
+});

package/dist/src/up-task.d.ts

@@ -0,0 +1,17 @@
+import type { UpWorldOptions } from './runtime.js';
+import type { WorldInstance } from './schema.js';
+export type UpTaskRequest = {
+    type: 'start';
+    configId: string;
+    options: UpWorldOptions;
+};
+export type UpTaskReply = {
+    instance: WorldInstance;
+} | {
+    error: string;
+};
+/** `up` from the CLI: the boot runs in an owner process outside the caller's process group (the shape of `run`'s
+ *  task owner, ./run-task.ts), so the boot does not depend on the caller's terminal. The caller's Ctrl-C or SIGTERM
+ *  cancels the boot, which rolls back; losing the caller (its terminal closed, the caller killed) does not: a World
+ *  is not the caller's to keep, so the boot completes and its outcome is written to the lifecycle log. */
+export declare function superviseWorldUp(configId: string, options: UpWorldOptions): Promise<WorldInstance>;

package/dist/src/up-task.js

@@ -0,0 +1,49 @@
+import { offSignal } from "./signals.js";
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { siblingScript } from "./sibling.js";
+/** `up` from the CLI: the boot runs in an owner process outside the caller's process group (the shape of `run`'s
+ *  task owner, ./run-task.ts), so the boot does not depend on the caller's terminal. The caller's Ctrl-C or SIGTERM
+ *  cancels the boot, which rolls back; losing the caller (its terminal closed, the caller killed) does not: a World
+ *  is not the caller's to keep, so the boot completes and its outcome is written to the lifecycle log. */
+export function superviseWorldUp(configId, options) {
+    return new Promise((done, reject) => {
+        const child = spawn(process.execPath, [siblingScript(import.meta.url, 'up-task-worker')], {
+            cwd: process.cwd(), env: process.env, detached: process.platform !== 'win32',
+            stdio: ['ignore', 'inherit', 'inherit', 'ipc'], serialization: 'json',
+        });
+        let reply;
+        let failure;
+        const cancel = (signal) => {
+            if (child.connected)
+                child.send({ type: 'cancel', signal }, error => { if (error)
+                    failure ??= error; });
+        };
+        const onInt = () => cancel('SIGINT');
+        const onTerm = () => cancel('SIGTERM');
+        process.on('SIGINT', onInt);
+        process.on('SIGTERM', onTerm);
+        child.on('error', error => { failure = error; });
+        child.on('message', message => { reply = message; });
+        child.once('spawn', () => {
+            const request = { type: 'start', configId, options: { ...options, root: resolve(options.root ?? process.cwd()) } };
+            child.send(request, error => { if (error) {
+                failure = error;
+                if (child.connected)
+                    child.disconnect();
+            } });
+        });
+        child.once('close', (code, signal) => {
+            offSignal('SIGINT', onInt);
+            offSignal('SIGTERM', onTerm);
+            if (failure)
+                reject(failure);
+            else if (reply && 'error' in reply)
+                reject(new Error(reply.error));
+            else if (reply && code === 0)
+                done(reply.instance);
+            else
+                reject(new Error(`World boot owner exited without a result (${signal ?? code}); inspect \`volter-world status\` and the lifecycle log`));
+        });
+    });
+}

package/dist/src/websocket-relay.d.ts

@@ -0,0 +1,3 @@
+import type { ServeHttpOptions } from '@volter/world-core';
+/** A message relay for the World's TLS fronts. Transport state is connection-local. */
+export declare function websocketRelay(targetFor: (request: Request) => string | undefined): NonNullable<ServeHttpOptions['upgrade']>;

package/dist/src/websocket-relay.js

@@ -0,0 +1,40 @@
+/** A message relay for the World's TLS fronts. Transport state is connection-local. */
+export function websocketRelay(targetFor) {
+    const sessions = new WeakMap();
+    return {
+        accepts: request => targetFor(request) !== undefined,
+        open(peer, request) {
+            const target = targetFor(request);
+            if (!target) {
+                peer.close(1011, 'no twin for request');
+                return;
+            }
+            const upstream = new WebSocket(target);
+            upstream.binaryType = 'arraybuffer';
+            const session = { upstream, pending: [] };
+            sessions.set(peer, session);
+            upstream.onopen = () => { for (const message of session.pending)
+                upstream.send(message); session.pending.length = 0; };
+            upstream.onmessage = event => { peer.send(typeof event.data === 'string' ? event.data : new Uint8Array(event.data)); };
+            upstream.onclose = event => { peer.close(event.code === 1006 ? 1011 : event.code, event.reason); };
+            upstream.onerror = () => { peer.close(1011, 'twin websocket error'); };
+        },
+        message(peer, data) {
+            const session = sessions.get(peer);
+            if (!session)
+                return;
+            if (session.upstream.readyState === WebSocket.OPEN)
+                session.upstream.send(data);
+            else
+                session.pending.push(data);
+        },
+        close(peer) {
+            const session = sessions.get(peer);
+            sessions.delete(peer);
+            if (session) {
+                session.pending.length = 0;
+                session.upstream.close();
+            }
+        },
+    };
+}