@volter/world-runtime 2.0.0

package/dist/src/runtime-test-support.js

@@ -0,0 +1,205 @@
+// Shared setup for the runtime test files. Extracted so runtime.test.ts could be split by
+// concern: 25 sequential tests in one process floored the gate at ~24s, and the gate shards
+// per FILE. Every helper lives here — including the five that used to sit BETWEEN tests,
+// whose loss broke the first attempt at this split.
+import { afterEach } from 'bun:test';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import net from 'node:net';
+import { downWorld, statusWorld } from "./runtime.js";
+import { stateDirName } from '@volter/world-core';
+/** Test-only seam (see runtime.ts `proxyDaemonDeadlineMs`): force the daemon-poll deadline to `ms`
+ * for the duration of `fn`, then restore whatever was there before — deterministic, no sleeps. */
+export async function withProxyDeadline(ms, fn) {
+    const prev = process.env.VOLTER_PROXY_DEADLINE_MS;
+    process.env.VOLTER_PROXY_DEADLINE_MS = String(ms);
+    try {
+        return await fn();
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.VOLTER_PROXY_DEADLINE_MS;
+        else
+            process.env.VOLTER_PROXY_DEADLINE_MS = prev;
+    }
+}
+/** Best-effort cleanup for the forced-timeout tests below: with the deadline forced to 0, the
+ * detached proxy-daemon child is still spawned and may go on to write `proxy.json` a little later
+ * (asynchronously, after our synchronous poll already gave up) — kill it so it doesn't linger as an
+ * orphan process once the test's tmp root is discarded. Never gates test pass/fail. */
+export async function reapLeakedProxyDaemon(root, name) {
+    const proxyJsonPath = join(root, stateDirName(), 'worlds', name, 'proxy.json');
+    const deadline = Date.now() + 3000;
+    while (Date.now() < deadline) {
+        if (existsSync(proxyJsonPath)) {
+            try {
+                const state = JSON.parse(readFileSync(proxyJsonPath, 'utf8'));
+                if (state.pid) {
+                    try {
+                        process.kill(state.pid, 'SIGTERM');
+                    }
+                    catch { /* already gone */ }
+                }
+            }
+            catch { /* ignore parse races */ }
+            return;
+        }
+        await new Promise((r) => setTimeout(r, 100));
+    }
+}
+/** A hostname under the IANA-reserved `.invalid` TLD (RFC 2606) — guaranteed to NEVER resolve, on
+ * any network, forever. Used as the "untwinned public host" below: it is unambiguously non-local
+ * (so `isLocalOrPrivateHost` never exempts it) and unambiguously not a vendor (so it is never
+ * redirected to a twin), and a real (non-strict-egress) attempt to reach it fails FAST on DNS
+ * resolution — offline and deterministic, no dependency on real internet access. */
+export const UNTWINNED_HOST = 'definitely-untwinned.invalid';
+/** Drive a raw CONNECT through the ambient redirect proxy and collect whatever bytes come back
+ * before the socket closes (or `timeoutMs` elapses, as a safety net — a blind-tunnel attempt to an
+ * unresolvable host closes with NO data at all, so this never actually waits the full timeout). */
+export function connectThroughProxy(port, host, targetHost, targetPort = 443, timeoutMs = 3000) {
+    return new Promise((resolvePromise, reject) => {
+        const sock = net.connect(port, host, () => {
+            sock.write(`CONNECT ${targetHost}:${targetPort} HTTP/1.1\r\nHost: ${targetHost}:${targetPort}\r\n\r\n`);
+        });
+        let data = '';
+        const timer = setTimeout(() => { sock.destroy(); resolvePromise(data); }, timeoutMs);
+        sock.on('data', (chunk) => { data += chunk.toString('utf8'); });
+        sock.on('close', () => { clearTimeout(timer); resolvePromise(data); });
+        sock.on('error', (err) => { clearTimeout(timer); reject(err); });
+    });
+}
+/** Force `opensslAvailable()` to false via its TEST-ONLY seam (see `redirect-proxy.ts`). A
+ * PATH-shim (fake `openssl` binary prepended to PATH) was tried first and does NOT reliably work
+ * here: `opensslAvailable()`'s `spawnSync('openssl', …)` call passes no explicit `env`, and this
+ * runtime resolves the executable against a PATH snapshotted at process start rather than a
+ * same-process `process.env.PATH` mutation made mid-test (verified: a fresh child process DOES
+ * see a shimmed PATH, but mutating PATH in the already-running test process does not change what
+ * THIS process's own `spawnSync` resolves) — so the deterministic, seam-based override is used. */
+export function withNoOpenssl() {
+    const previous = process.env.VOLTER_TEST_NO_OPENSSL;
+    process.env.VOLTER_TEST_NO_OPENSSL = '1';
+    return {
+        restore: () => {
+            if (previous === undefined)
+                delete process.env.VOLTER_TEST_NO_OPENSSL;
+            else
+                process.env.VOLTER_TEST_NO_OPENSSL = previous;
+        },
+    };
+}
+export const worlds = [];
+/**
+ * Register the teardown hook for the CALLING test file. Every file that pushes to `worlds` must
+ * call this at top level.
+ *
+ * It has to be a function call rather than a module-scope `afterEach`, and that distinction was an
+ * eight-file process leak. A hook registered while this module's body runs belongs to whichever
+ * file happened to import it FIRST; module caching means the body never runs again, so every other
+ * file got no hook at all. Each file individually looked clean — it was the first importer — and
+ * only a whole-directory run leaked, which is exactly the shape that reads as flakiness. The
+ * stray proxy daemons and tunnel stubs then held ports until unrelated HTTP tests started failing.
+ *
+ * Teardown also settles ALL worlds before reporting: the list is spliced empty up front, so a bare
+ * `for … await` loop that rejected on the first world abandoned the rest with nothing left holding
+ * a reference to them. Nothing about a world that failed to stop makes the next one less important
+ * to stop.
+ */
+export function useWorldCleanup() {
+    afterEach(async () => {
+        const pending = worlds.splice(0);
+        const failures = await Promise.allSettled(pending.map((w) => downWorld(w.name, w.root)));
+        const errors = failures.filter((f) => f.status === 'rejected');
+        // Reported, never swallowed: a world that cannot be torn down is a real finding about the
+        // runtime, and silently ignoring it is how this stayed invisible for so long.
+        if (errors.length) {
+            throw new Error(`world teardown failed for ${errors.length}/${pending.length} world(s): ${errors.map((e) => String(e.reason)).join('; ')}`);
+        }
+    });
+}
+export function writeRaceConfig(root, id) {
+    mkdirSync(join(root, 'worlds', 'configs'), { recursive: true });
+    writeFileSync(join(root, 'worlds', 'configs', `${id}.json`), JSON.stringify({
+        id,
+        services: [
+            {
+                id: 'app',
+                type: 'process',
+                command: 'node',
+                args: ['-e', "require('node:http').createServer((_req,res)=>res.end('ok')).listen(Number(process.env.PORT),'127.0.0.1')"],
+                env: { NODE_OPTIONS: '' },
+                portArg: false,
+                rootArg: false,
+            },
+        ],
+    }));
+}
+/** Bounded wait (no fixed sleeps) for SIGTERM'd services to actually exit after downWorld. */
+export async function waitForWorldDown(name, root) {
+    const deadline = Date.now() + 5_000;
+    while (Date.now() < deadline) {
+        if (!statusWorld(name, root).running)
+            return true;
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    return !statusWorld(name, root).running;
+}
+export function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// --- TWIN-60: `--mode sealed` must actually ENFORCE strict egress (VOLTER_TWIN_STRICT_EGRESS),
+// not just record intent (VOLTER_WORLD_SEALED) that nothing consumes. One vendor twin (s3) is
+// enough to exercise both enforcement points: the Node injector (control-plane/inject.cjs, HTTP
+// path) and the ambient TLS redirect proxy (redirect-proxy.ts, CONNECT path).
+export function writeSingleTwinConfig(root, id) {
+    mkdirSync(join(root, 'worlds', 'configs'), { recursive: true });
+    writeFileSync(join(root, 'worlds', 'configs', `${id}.json`), JSON.stringify({
+        id,
+        services: [
+            {
+                id: 's3',
+                command: 'node',
+                args: ['-e', "require('node:http').createServer((_req,res)=>res.end('s3')).listen(Number(process.env.PORT),'127.0.0.1')"],
+                env: { NODE_OPTIONS: '' },
+                injectEnv: 'S3_TWIN_URL',
+                portArg: false,
+                rootArg: false,
+            },
+        ],
+    }));
+}
+/** Twin + a second (non-twin) service — the proxy-attempt loop tries the ambient proxy again
+ * before starting each subsequent service, so this reaches the ambient proxy regardless of
+ * whether the single/last-service re-evaluation (TWIN-64) has landed yet — kept independent of
+ * that fix so this CONNECT-level test exercises TWIN-60's wiring in isolation. */
+export function writeTwinPlusAppConfig(root, id) {
+    mkdirSync(join(root, 'worlds', 'configs'), { recursive: true });
+    writeFileSync(join(root, 'worlds', 'configs', `${id}.json`), JSON.stringify({
+        id,
+        services: [
+            {
+                id: 's3',
+                command: 'node',
+                args: ['-e', "require('node:http').createServer((_req,res)=>res.end('s3')).listen(Number(process.env.PORT),'127.0.0.1')"],
+                env: { NODE_OPTIONS: '' },
+                injectEnv: 'S3_TWIN_URL',
+                portArg: false,
+                rootArg: false,
+            },
+            {
+                id: 'app',
+                type: 'process',
+                command: 'node',
+                args: ['-e', "require('node:http').createServer((_req,res)=>res.end('ok')).listen(Number(process.env.PORT),'127.0.0.1')"],
+                env: { NODE_OPTIONS: '' },
+                portArg: false,
+                rootArg: false,
+            },
+        ],
+    }));
+}

package/dist/src/runtime.d.ts

@@ -0,0 +1,256 @@
+import { type CaTrustInputs } from './ca-trust.js';
+import type { WorldInstance, WorldIsolation, WorldMode, WorldRunOutcome } from './schema.js';
+/** The World's events file: every service's start and end, and the World's own stops, one JSON line each. */
+export declare function worldEventsPath(logs: string): string;
+export type UpWorldOptions = {
+    owner?: string;
+    name?: string;
+    root?: string;
+    mode?: WorldMode;
+    /** Overrides the config's `isolation` for this boot (e.g. force 'process' for a share world). */
+    isolation?: WorldIsolation;
+    envFile?: string;
+    share?: Omit<ShareWorldOptions, 'root' | 'service' | 'verifyPath'> & {
+        verifyPath?: string | false;
+    };
+    /** `checkout`: bring a stopped world back with its state — the data dir, marks, changesets and
+     *  episodes survive the boot; logs and the pid file start clean. Never the default: `up` starts
+     *  clean, and the world dir is the reproducible story. */
+    keepState?: boolean;
+};
+export type ShareWorldOptions = {
+    root?: string;
+    service?: string;
+    provider?: 'cloudflare-quick' | 'command';
+    command?: string;
+    args?: string[];
+    ephemeral?: boolean;
+    timeoutMs?: number;
+    verifyPath?: string | false;
+};
+export type ShareWorldServicesOptions = Omit<ShareWorldOptions, 'service' | 'verifyPath'> & {
+    service?: string;
+    verifyPath?: string | false;
+};
+export type WorldDoctorCheck = {
+    id: string;
+    ok: boolean;
+    message: string;
+};
+export type WorldDoctorReport = {
+    name: string;
+    ok: boolean;
+    checks: WorldDoctorCheck[];
+};
+export type RunWorldOptions = UpWorldOptions & {
+    keep?: boolean;
+    verbose?: boolean;
+};
+export type WorldUrlInfo = {
+    name: string;
+    mode: WorldMode;
+    services: Record<string, {
+        localUrl: string;
+        publicUrl?: string;
+        publicReady?: boolean;
+    }>;
+};
+/** Exported for the reflect attachment (reflect.ts), whose routes file lives in
+ * the instance dir — one layout owner, no duplicated path knowledge. */
+/** THE WORLD CLOCK file (TWIN-PROGRAMMING-MODEL P3): a single frozen ISO instant every twin
+ *  stamps from (kernel worldNow()); absent → real wall-clock. Written only by the
+ *  `volter-world clock` operator door — time is physics, advanced explicitly, never drifting. */
+export declare function clockFile(root: string, name: string): string;
+export declare function instanceDir(root: string, name: string): string;
+export type SharingClaim = {
+    token: string;
+    pid: number;
+    hostname: string;
+    serviceId?: string;
+    claimedAt: string;
+    heartbeatAt: string;
+};
+/** Exported for direct drive: the liveness rule, pure over a claim. */
+export declare function sharingClaimAlive(claim: SharingClaim): boolean;
+/** The process's environment as the world admits it: what `stripEnv` names stays outside. */
+export declare function admittedEnv(strip: string[] | undefined, env?: NodeJS.ProcessEnv): Record<string, string>;
+export declare function saveWorldInstance(instance: WorldInstance): void;
+export declare function upWorld(configId: string, options?: UpWorldOptions, abort?: AbortSignal): Promise<WorldInstance>;
+export declare function downWorld(name: string, root?: string, options?: {
+    graceMs?: number;
+    purge?: boolean;
+    expectedCreatedAt?: string;
+}): Promise<{
+    name: string;
+    stopped: number[];
+    escalated: number[];
+    externalStopped: string[];
+    externalErrors: string[];
+    notSignalled?: string[];
+    purged?: string;
+}>;
+/** A service's state as a process, not only its leader: `lingering` is a service whose World parent ended while its
+ *  process group still holds live processes (a server's workers, a runtime's child), which `down` still stops. */
+export type ServiceState = 'running' | 'stopped' | 'lingering' | 'gave-up' | 'external';
+export declare function statusWorld(name: string, root?: string, options?: {
+    readOnly?: boolean;
+    light?: boolean;
+}): WorldInstance & {
+    running: boolean;
+    livePids: number[];
+    serviceStates: Record<string, ServiceState>;
+    degraded: boolean;
+};
+export type WorldCleanupEntry = {
+    name: string;
+    path: string;
+    eligible: boolean;
+    reason: string;
+    stoppedAt?: string;
+    logicalBytes?: number;
+    removed?: boolean;
+};
+/** Preview by default. Apply holds up's lock across fresh eligibility checking and deletion.
+ * Never call down here: that would turn a stale preview into permission to kill a new World. */
+export declare function pruneWorlds(options?: {
+    root?: string;
+    name?: string;
+    apply?: boolean;
+}): {
+    root: string;
+    apply: boolean;
+    entries: WorldCleanupEntry[];
+};
+export declare function parseCloudflareQuickPublicUrl(candidate: string): string | undefined;
+export declare function shareWorld(name: string, options?: ShareWorldOptions): Promise<WorldInstance>;
+export declare function shareWorldServices(name: string, options?: ShareWorldServicesOptions): Promise<WorldInstance>;
+/** TWIN-62: `unshare` must give tunnels the same contract plain `downWorld` already gives owned
+ * services — SIGTERM, confirm dead (escalating to SIGKILL past the grace), and only THEN erase the
+ * tunnel facts/pids. A best-effort SIGTERM with no confirmation can leave a `cloudflared` that
+ * ignores SIGTERM serving the public URL forever while instance.json (and the pids file) say
+ * nothing is shared — the exact "half-shared" state docs/concepts/worlds.md promises cannot exist. Stays
+ * synchronous (via `killSurvivorsAfterGraceSync`) to match the existing signature/call sites
+ * (the CLI does not await it). Returns the instance plus the tunnel pids that needed escalating,
+ * for callers that want to report it. */
+export declare function unshareWorld(name: string, options?: {
+    root?: string;
+    service?: string;
+    graceMs?: number;
+}): WorldInstance & {
+    escalated: number[];
+};
+export declare function doctorWorld(name: string, options?: {
+    root?: string;
+    verifyPublic?: boolean;
+    timeoutMs?: number;
+}): Promise<WorldDoctorReport>;
+export declare function urlsWorld(name: string, root?: string): WorldUrlInfo;
+/**
+ * The clean (unquoted) base URL(s) of a RUNNING world's services — the `volter-world url`
+ * surface. Resolved from the generated instance, so callers never shell-parse `world.env`
+ * (its values are single-quoted). One `{ id, url }` when `service` is named; every
+ * URL-bearing service otherwise ('external' services have no assigned URL — their endpoints
+ * are discovered env vars, so they are omitted from the list and refused by name).
+ */
+export declare function urlWorld(name: string, options?: {
+    service?: string;
+    root?: string;
+}): Array<{
+    id: string;
+    url: string;
+}>;
+export declare function runWorld(configId: string, command: string[], options?: RunWorldOptions): Promise<{
+    instance: WorldInstance;
+    exitCode: number;
+    outcome: WorldRunOutcome;
+}>;
+/** Internal task entry. The lifetime owner exists before admission/startup. Cancellation during
+ * boot is latched and handled after startup settles, so no abandoned startup can create a late
+ * service after teardown. Persistent --keep runs use the caller directly. */
+export declare function runWorldOwned(configId: string, command: string[], options: RunWorldOptions, abort?: AbortSignal): Promise<{
+    instance: WorldInstance;
+    exitCode: number;
+    outcome: WorldRunOutcome;
+}>;
+export declare function listWorlds(root?: string): Array<{
+    name: string;
+    running: boolean;
+    degraded?: boolean;
+    config?: string;
+}>;
+/** Runs the command in the world's env in the foreground and resolves to its exit code. The child is
+ *  awaited, not blocked on: a runtime that runs no synchronous child (the browser engine) still runs
+ *  this one, and the caller sees no difference — stdio is inherited either way. */
+export declare function runWithWorldEnv(name: string, command: string[], root?: string, options?: {
+    cwd?: string;
+    verbose?: boolean;
+}): Promise<number>;
+/** Local CLI attachment with one instance-bound consumer record per concurrent command.
+ * The synchronous SDK method remains compatible; its consumers are explicitly untracked. */
+export type ConsumerRetirement = {
+    id: string;
+    owner?: string;
+    retired: boolean;
+    reason: string;
+};
+/**
+ * The owner's explicit resolution of uncertain attachments (never automatic, never implied by age).
+ * A record is retired only when it belongs to this host and the running instance, its runner and
+ * its command are both gone (ESRCH), and no live process remains in the command's process group
+ * (`survivingOwnedGroups`, the lifecycle's own retirement evidence); anything else is kept with the
+ * reason, surviving members named by their group. Active consumers are never touched.
+ */
+export declare function retireWorldConsumers(name: string, root?: string, options?: {
+    consumer?: string;
+}): ConsumerRetirement[];
+export declare function attachWorld(name: string, command: string[], root?: string, options?: {
+    cwd?: string;
+    owner?: string;
+    verbose?: boolean;
+}): Promise<number>;
+/** The shell + env + cwd a `volter-world shell` subshell launches with (extracted for testability):
+ * the world env (twin `*_URL`s + fake keys + the Node injector + cliRedirect endpoint vars) on top
+ * of the caller's env, plus `VOLTER_WORLD` so a prompt can show which world is active. The ambient
+ * TLS-proxy env (HTTPS_PROXY + the CA-trust vars) is layered in by `shellWorld` once the proxy is up,
+ * since starting a server is async; this pure helper stays synchronous + side-effect-free for tests. */
+export declare function worldShellEnv(name: string, root?: string): {
+    shell: string;
+    cwd: string;
+    env: Record<string, string>;
+};
+/** Drop into an interactive subshell with the world active — the contained sibling of `activate`
+ * (which wires your CURRENT shell + sets the `(world:<name>)` prompt marker). The subshell gets the
+ * world env AND, when openssl is available, an in-process ambient TLS redirect proxy: unmodified
+ * `gh`/`stripe`/`curl`/app in the subshell transparently hit the twins. Vendor calls in this subshell
+ * land in the twins; `exit` restores normal (the proxy + its session CA are torn down). The CA is
+ * trusted ONLY via this subshell's env — never installed system-wide. See docs/guides/route-a-cli-through-the-world.md. */
+export declare function shellWorld(name: string, root?: string): Promise<number>;
+/** Ensure a DETACHED ambient-redirect proxy daemon is running for this world (used by `activate`,
+ * which only emits a script and can't host an in-process server for the life of the shell). Idempotent:
+ * reuses a live daemon. Returns its proxy env, or null if openssl is missing (env-only fallback). The
+ * daemon is recorded in `proxy.json` and stopped by `down`. */
+export declare function ensureWorldProxy(name: string, root?: string, caller?: CaTrustInputs): {
+    url: string;
+    caCertPath: string;
+    env: Record<string, string>;
+} | null;
+/** The detached proxy daemon's body (invoked as its own process by `ensureWorldProxy`). Starts the
+ * redirect proxy bound to an ephemeral port, records its pid/url/CA in `proxy.json`, and stays up
+ * until killed by `down`. Exported so the daemon entry file can delegate to it. */
+export declare function runProxyDaemon(name: string, root?: string, envFile?: string): Promise<void>;
+/**
+ * Emit a POSIX (bash/zsh) script to `eval` that ACTIVATES the world in the current shell — a
+ * virtualenv for vendor APIs. It exports the world env (twin `*_URL`s + fake keys + the Node
+ * injector + any `cliRedirect` endpoint vars), prepends `(world:<name>)` to the prompt so you can
+ * always see you're pointed at twins (a safety signal, not cosmetic), and defines a `deactivate`
+ * function that restores the prompt and unsets the vars. Usage: `eval "$(volter-world activate dev)"`.
+ *
+ * It ALSO starts (idempotently) the ambient TLS redirect proxy daemon for this world and exports
+ * `HTTPS_PROXY`/`HTTP_PROXY` + the CA-trust vars (`NODE_EXTRA_CA_CERTS`, `CURL_CA_BUNDLE`, …) so an
+ * UNMODIFIED `gh`/`stripe`/`curl`/app in the shell transparently hits the twins with zero per-tool
+ * config (WORLD_ACTIVATE.md tier 1). The session CA is trusted ONLY via these per-shell exports,
+ * never system-wide; `down` stops the daemon and drops the CA. If openssl is unavailable the script
+ * still emits the env-only redirect (Phase-1 behavior) — it just skips the proxy exports.
+ * See docs/guides/route-a-cli-through-the-world.md.
+ */
+export declare function activateScript(name: string, root?: string): string;