@volter/world-machine 2.0.0

package/dist/src/gc.d.ts

@@ -0,0 +1,25 @@
+import type { MachineConfig } from './config.js';
+import { type HostSession } from './host.js';
+/** What `serve` registers for a service root: the World's branch directory when the root is a branch's
+ *  service data directory (`<app>/.volter/worlds/<branch>/data/<service>`), else the root itself. */
+export declare function registration(root: string): string;
+export declare function register(session: HostSession, root: string): Promise<void>;
+export type GcReport = {
+    roots: string[];
+    dropped: string[];
+    branches: number;
+    live: number;
+    deletedSnapshots: string[];
+    deletedBases: string[];
+    deletedTrees: string[];
+    expired: string[];
+    kept: {
+        pending: string[];
+        loaded: string[];
+    };
+    usedBefore: number;
+    usedAfter: number;
+    freedBytes: number;
+    trimmed: string;
+};
+export declare function collect(config: MachineConfig, session: HostSession, own?: string): Promise<GcReport>;

package/dist/src/gc.js

@@ -0,0 +1,131 @@
+// Snapshot retention: a snapshot is kept while any existing branch's machine ledger (its whole view,
+// the parent's history included) names it; everything else in the store goes. Each snapshot directory
+// is self-contained (its memory and disk are reflink copies, never references to another directory), so
+// deleting one never breaks another.
+//
+// The store is shared by every World whose machine runs on this host, so each `serve` registers its
+// World in the store (`roots.json`: the World's branch directory, `<app>/.volter/worlds`, or the
+// service root itself when it is not laid out that way). A collection reads every registered World's
+// branches (a registration whose directory is gone is dropped), and deletes:
+//   - snapshot directories no ledger names, unless a checkpoint is still writing them (`.pending`) or a
+//     slot's machine was loaded from them;
+//   - warm bases no kept snapshot was built on (on the container backend, none a branch's head was not taken on: its
+//     snapshots never read their base), unless it is this configuration's base, a slot's machine was loaded from it,
+//     or it is still being built;
+//   - the container backend's filled trees (tree-<hash>) but this configuration's and those a kept base was made from;
+// then trims the store's filesystem so the space goes back to the host. A ledger that cannot be read
+// stops the collection: nothing is deleted on a partial view.
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { wholeLog } from '@volter/world-core';
+import { q } from "./host.js";
+import { headSnapshot, LEDGER } from "./ledger.js";
+import { containerHashes } from "./container.js";
+import { baseHash } from "./machine.js";
+import { thinned } from "./thin.js";
+/** What `serve` registers for a service root: the World's branch directory when the root is a branch's
+ *  service data directory (`<app>/.volter/worlds/<branch>/data/<service>`), else the root itself. */
+export function registration(root) {
+    const m = /^(.*\/\.volter\/worlds)\/[^/]+\/data\/[^/]+\/?$/.exec(root);
+    return m ? m[1] : root;
+}
+/** Every machine service root a registration covers. */
+function machineRoots(registered) {
+    if (basename(registered) === 'worlds') {
+        return readdirSync(registered)
+            .filter((b) => !b.startsWith('.'))
+            .map((b) => join(registered, b, 'data', LEDGER))
+            .filter((r) => existsSync(r) && statSync(r).isDirectory());
+    }
+    return [registered];
+}
+export async function register(session, root) {
+    await session.call(`wm_register ${q(registration(root))}`);
+}
+export async function collect(config, session, own) {
+    const store = await session.call('wm_store_list');
+    const roots = store.roots.filter((r) => existsSync(r));
+    const dropped = store.roots.filter((r) => !roots.includes(r));
+    const liveDirs = new Set();
+    const liveBases = new Set();
+    const heads = new Set();
+    const ownDirs = new Set();
+    const othersDirs = new Set();
+    const keepDirs = new Set();
+    let branches = 0;
+    for (const registered of roots) {
+        const mine = own !== undefined && registered === registration(own);
+        for (const r of machineRoots(registered)) {
+            branches++;
+            let log;
+            try {
+                log = wholeLog(LEDGER, r);
+            }
+            catch (error) {
+                throw new Error(`world-machine gc: cannot read the machine ledger at ${r} (${error.message}); nothing was deleted`);
+            }
+            for (const e of log) {
+                if (e.op !== 'set' || e.subject.type !== 'snapshot')
+                    continue;
+                const f = e.fields;
+                if (f.dir) {
+                    liveDirs.add(basename(f.dir));
+                    (mine ? ownDirs : othersDirs).add(basename(f.dir));
+                }
+                if (f.dir && e.fields.keep)
+                    keepDirs.add(basename(f.dir));
+                // a Firecracker snapshot is kept with the base it was built on; a container snapshot never reads its base (a
+                // restore reads the snapshot's own tree and dump, and a machine with no head the configured base), so there only
+                // the configured base, heads' bases (below) and a running machine's stay
+                if (f.base && config.backend !== 'container')
+                    liveBases.add(f.base);
+            }
+            const head = headSnapshot(r);
+            if (head)
+                heads.add(basename(head.dir));
+            // on the container backend the base a branch's head was taken on stays (another World on this store, configured
+            // otherwise, starts a branch with no head from it); a base only older heads named goes once each moves on
+            if (head?.base && config.backend === 'container')
+                liveBases.add(head.base);
+        }
+    }
+    // Retention (config `retain`): every branch's head stays (a World resumes at it), and the newest `retain` others (with
+    // `thin`, also the newest of each hour for a day and of each day for a month, and every snapshot taken with `keep`); the
+    // rest are let go though a ledger names them, and recorded so that a restore of one says it expired
+    // Only the calling World's own snapshots are counted: `retain` is its configuration, and another World on the store
+    // keeps its own, including a snapshot both name (a World's ledgers copied from another). They are ranked by when the host took them (the time in the snapshot's id), never by the World's
+    // clock, which a World can freeze (every mark would tie).
+    const expired = [];
+    if (config.retain && own) {
+        const present = new Set(store.snapshots);
+        const taken = (d) => { const m = /^snap-([0-9a-z]+)-/.exec(d); return m ? parseInt(m[1], 36) : 0; };
+        const others = [...ownDirs].filter((d) => !heads.has(d) && !othersDirs.has(d) && present.has(d)).sort((a, b) => taken(b) - taken(a) || b.localeCompare(a));
+        // thinned with age (thin.ts), or the newest `retain` only
+        const stay = config.thin ? thinned(others.map((d) => ({ dir: d, takenMs: taken(d), keep: keepDirs.has(d) })), Date.now(), { retain: config.retain }) : new Set(others.slice(0, config.retain));
+        for (const d of others)
+            if (!stay.has(d)) {
+                liveDirs.delete(d);
+                expired.push(d);
+            }
+    }
+    const loaded = new Set(store.loaded.map((p) => basename(p.replace(/\/+$/, ''))));
+    const pending = new Set(store.pending);
+    const hashes = config.backend === 'container' ? await containerHashes(config, session) : { base: await baseHash(config, session), tree: '' };
+    const configured = `base-${hashes.base}`;
+    const deletedSnapshots = store.snapshots.filter((s) => !liveDirs.has(s) && !pending.has(s) && !loaded.has(s));
+    const deletedBases = store.bases.filter((b) => !liveBases.has(b) && b !== configured && !loaded.has(b) && !b.endsWith('.building'));
+    // the container backend's filled trees (tree-<hash>): only this configuration's is kept (a base's own root.img shares
+    // its blocks, so a tree whose image or fill moved on holds only what nothing else does)
+    // (bases being built included: each names its tree from its first step; a tree being saved is tree-<hash>.part-<slot>)
+    const keptTrees = new Set(store.bases.filter((b) => !deletedBases.includes(b)).map((b) => store.baseTrees[b]).filter(Boolean));
+    const treeOf = (t) => t.replace(/\.part-[a-z0-9-]+$/, '');
+    const deletedTrees = store.trees.filter((t) => treeOf(t) !== `tree-${hashes.tree}` && !keptTrees.has(treeOf(t)));
+    const paths = [...deletedSnapshots.map((s) => `snapshots/${s}`), ...deletedBases, ...deletedTrees];
+    const expiring = expired.filter((d) => deletedSnapshots.includes(d));
+    const done = await session.call(`${expiring.length ? `printf '%s\\n' ${expiring.map(q).join(' ')} >> "$WM_STORE/expired.list"\n` : ''}wm_gc_delete ${q(JSON.stringify(dropped))} ${paths.map(q).join(' ')}`);
+    return {
+        roots, dropped, branches, live: liveDirs.size, deletedSnapshots, deletedBases, deletedTrees, expired: expiring,
+        kept: { pending: [...pending], loaded: [...loaded] },
+        usedBefore: done.usedBefore, usedAfter: done.usedAfter, freedBytes: Math.max(0, done.usedBefore - done.usedAfter), trimmed: done.trimmed,
+    };
+}

package/dist/src/host.d.ts

@@ -0,0 +1,49 @@
+import type { MachineConfig } from './config.js';
+export declare const GUEST_AGENT: string;
+/** world-core's zero-edit redirect (a real SDK's vendor host to its twin, by the *_TWIN_URL variables) and the files it
+ *  loads, written into the guest at GUEST_INJECT_DIR at every start and restore: an app in the machine reaches the twins
+ *  as `volter world run` does. */
+export declare const GUEST_INJECT_DIR = "/opt/volter-world";
+export declare const GUEST_INJECT: Record<string, string>;
+/** Every login shell in the guest exports the World's env file (KEY=value lines, written at each start and restore). */
+export declare const GUEST_PROFILE = "[ -r /etc/world.env ] && while IFS= read -r l; do case \"$l\" in ''|'#'*) ;; *=*) export \"$l\" ;; esac; done < /etc/world.env";
+/** A sub-millisecond wall clock on the World's host. */
+export declare const hostNowMs: () => number;
+/** Single-quote a string for bash. */
+export declare const q: (s: string) => string;
+export declare class HostSession {
+    private readonly config;
+    private child;
+    private buffer;
+    private waiter;
+    private queue;
+    /** The machine host's clock minus this host's, in seconds; measured at open and before each clock step. */
+    offsetS: number;
+    constructor(config: MachineConfig);
+    private spawnShell;
+    private open;
+    private drain;
+    /** Set while the store-wide collection runs (gc): it is no operation on the slot, and must not wait on one. */
+    unlocked: boolean;
+    private rawRun;
+    /** Run a script on the machine host, one at a time; resolves with its status and output. */
+    run(script: string): Promise<{
+        status: number;
+        out: string;
+    }>;
+    /** Run host.sh calls, each printing an `@{json}` result line; the results merge in order. An
+     *  `error` field, or a nonzero status, is thrown with the output. */
+    call<T = Record<string, unknown>>(script: string): Promise<T>;
+    /** The machine host's clock against this host's: the exchange with the shortest round trip of
+     *  five bounds the error by half that round trip. */
+    measureOffset(): Promise<{
+        offsetMs: number;
+        rttMs: number;
+    }>;
+    /** measureOffset, serialized with every other operation. */
+    offset(): Promise<{
+        offsetMs: number;
+        rttMs: number;
+    }>;
+    close(): void;
+}

package/dist/src/host.js

@@ -0,0 +1,163 @@
+// The machine host: where Firecracker runs. On Linux it is this box; on a Mac it is a Lima (>= 2) VM
+// with nested virtualization, reached over Lima's own ssh config. Either way the service holds ONE
+// persistent bash session on it (a new ssh or bash per operation cost 75-125 ms on a loaded Mac) with
+// host.sh sourced, and every operation is one round trip over that session.
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const HOST_LIB = readFileSync(new URL('./host.sh', import.meta.url), 'utf8');
+/** The container backend's functions, sourced after HOST_LIB when the config names that backend. */
+const CT_LIB = readFileSync(new URL('./ct.sh', import.meta.url), 'utf8');
+const AGENT_CLIENT = readFileSync(new URL('./agentc.py', import.meta.url), 'utf8');
+/** The container backend's page composer (compose.py), run detached on the host after each mark. */
+const COMPOSER = readFileSync(new URL('./compose.py', import.meta.url), 'utf8');
+/** The container backend's port publisher (publish.py), run detached on the host while the machine runs. */
+const PUBLISHER = readFileSync(new URL('./publish.py', import.meta.url), 'utf8');
+export const GUEST_AGENT = readFileSync(new URL('./agent.py', import.meta.url), 'utf8');
+/** world-core's zero-edit redirect (a real SDK's vendor host to its twin, by the *_TWIN_URL variables) and the files it
+ *  loads, written into the guest at GUEST_INJECT_DIR at every start and restore: an app in the machine reaches the twins
+ *  as `volter world run` does. */
+export const GUEST_INJECT_DIR = '/opt/volter-world';
+const core = (spec) => readFileSync(fileURLToPath(import.meta.resolve(`@volter/world-core/${spec}`)), 'utf8');
+export const GUEST_INJECT = {
+    'inject.cjs': core('inject'), 'network-policy.cjs': core('network-policy'), 'app-route.cjs': core('app-route'),
+    'vendor-hosts.cjs': core('vendor-hosts'),
+    'generated/pack-facts.json': core('generated/pack-facts.json'),
+};
+/** Every login shell in the guest exports the World's env file (KEY=value lines, written at each start and restore). */
+export const GUEST_PROFILE = `[ -r /etc/world.env ] && while IFS= read -r l; do case "$l" in ''|'#'*) ;; *=*) export "$l" ;; esac; done < /etc/world.env`;
+/** A sub-millisecond wall clock on the World's host. */
+export const hostNowMs = () => performance.timeOrigin + performance.now();
+/** Single-quote a string for bash. */
+export const q = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+export class HostSession {
+    config;
+    child;
+    buffer = '';
+    waiter;
+    queue = Promise.resolve();
+    /** The machine host's clock minus this host's, in seconds; measured at open and before each clock step. */
+    offsetS = 0;
+    constructor(config) {
+        this.config = config;
+    }
+    // Its own process group: the World stops a service by signalling its group, and the session must
+    // outlive that signal long enough to release the slot (it was cut mid-script, leaving the slot
+    // claimed). It still ends with this process: its stdin closes and the shell reads EOF.
+    spawnShell() {
+        const h = this.config.host;
+        if (h.kind === 'linux')
+            return spawn('bash', ['--noprofile', '--norc'], { stdio: 'pipe', detached: true });
+        const cfg = join(h.limaHome, h.instance, 'ssh.config');
+        return spawn('ssh', ['-F', cfg, '-T', '-o', 'ServerAliveInterval=10', `lima-${h.instance}`, 'bash --noprofile --norc'], { stdio: 'pipe', detached: true });
+    }
+    async open() {
+        const child = this.spawnShell();
+        this.child = child;
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => { this.buffer += chunk; this.drain(); });
+        child.stderr.on('data', (chunk) => { this.buffer += chunk; });
+        child.on('exit', (code) => {
+            if (this.child === child)
+                this.child = undefined;
+            const w = this.waiter;
+            this.waiter = undefined;
+            w?.reject(new Error(`the machine host session ended (exit ${code}): ${this.buffer.slice(-400)}`));
+        });
+        const c = this.config;
+        const vars = { WM_STORE: c.store, WM_SLOT: c.slot, WM_FC: c.firecracker, WM_SE: c.snapshotEditor, WM_KEY: c.sshKey, WM_TAP: c.tap, WM_HOSTIP: c.hostIp, WM_GUESTIP: c.guestIp };
+        if (c.backend === 'container') {
+            vars.WM_BINDS = JSON.stringify(c.binds);
+            if (c.export)
+                vars.WM_EXPORT = JSON.stringify(c.export);
+        }
+        // `~/` in a configured path is the machine host's home, expanded there.
+        const assign = Object.entries(vars).map(([k, v]) => `${k}=${v.startsWith('~/') ? `"$HOME"/${q(v.slice(2))}` : q(v)}`).join('\n');
+        await this.rawRun(`${assign}\n${HOST_LIB}\n${c.backend === 'container' ? `${CT_LIB}\n` : ''}wm_init && mkdir -p "$WM_SLOTDIR" && ${c.backend === 'container' ? 'exec 9>>"$WM_SLOTDIR/slot.lock" && WM_LOCKED=1 && ' : ''}cat > "$WM_SLOTDIR/agentc.py" <<'__WM_AGENTC__'\n${AGENT_CLIENT}\n__WM_AGENTC__\n${c.backend === 'container' ? `cat > "$WM_SLOTDIR/compose.py.$$" <<'__WM_COMPOSE__' && mv -f "$WM_SLOTDIR/compose.py.$$" "$WM_SLOTDIR/compose.py"\n${COMPOSER}\n__WM_COMPOSE__\ncat > "$WM_SLOTDIR/publish.py.$$" <<'__WM_PUBLISH__' && mv -f "$WM_SLOTDIR/publish.py.$$" "$WM_SLOTDIR/publish.py"\n${PUBLISHER}\n__WM_PUBLISH__\n` : ''}`);
+        await this.measureOffset();
+    }
+    drain() {
+        const w = this.waiter;
+        if (!w)
+            return;
+        const at = this.buffer.indexOf(w.marker);
+        if (at < 0)
+            return;
+        const rest = this.buffer.slice(at + w.marker.length);
+        const nl = rest.indexOf('\n');
+        if (nl < 0)
+            return;
+        const status = Number(rest.slice(0, nl).trim());
+        const out = this.buffer.slice(0, at);
+        this.buffer = rest.slice(nl + 1);
+        this.waiter = undefined;
+        w.resolve({ status, out });
+    }
+    /** Set while the store-wide collection runs (gc): it is no operation on the slot, and must not wait on one. */
+    unlocked = false;
+    rawRun(script) {
+        const child = this.child;
+        if (!child)
+            return Promise.reject(new Error('no machine host session'));
+        const marker = `__WM_DONE_${randomBytes(6).toString('hex')}__`;
+        return new Promise((resolve, reject) => {
+            this.waiter = { marker, resolve, reject };
+            this.buffer = '';
+            // a function, so a script may `return` its status
+            // With the slot's lock open (the container backend, from init on), one operation at a time across every service on
+            // the slot: a World's branch runs the machine being left and the branch's own machine side by side (a retake's
+            // prepare, then adopt), and each must see the slot as the other left it. The lock is taken for the operation and
+            // released after it, however it ends; a background process that inherited it does not keep it.
+            child.stdin.write(`__wm_op() {\n${script}\n}\nif [ -n "\${WM_LOCKED:-}" ] && [ -z "${this.unlocked ? '1' : ''}" ]; then flock -w 120 9 || { echo '@{"error":"the machine slot stayed busy for 120 s (another World operating it)"}'; false; }; fi && __wm_op 2>&1 < /dev/null; __wm_rc=$?; [ -n "\${WM_LOCKED:-}" ] && flock -u 9; printf '\\n%s %d\\n' ${marker} $__wm_rc\n`);
+        });
+    }
+    /** Run a script on the machine host, one at a time; resolves with its status and output. */
+    run(script) {
+        const next = this.queue.then(async () => {
+            if (!this.child)
+                await this.open();
+            return this.rawRun(script);
+        });
+        this.queue = next.catch(() => undefined);
+        return next;
+    }
+    /** Run host.sh calls, each printing an `@{json}` result line; the results merge in order. An
+     *  `error` field, or a nonzero status, is thrown with the output. */
+    async call(script) {
+        const { status, out } = await this.run(script);
+        const results = out.split('\n').filter((l) => l.startsWith('@{')).map((l) => JSON.parse(l.slice(1)));
+        const failed = results.find((r) => typeof r.error === 'string');
+        if (failed)
+            throw new Error(failed.error);
+        if (status !== 0 || !results.length)
+            throw new Error(`machine host: \`${script.split('\n')[0]}\` exited ${status}: ${out.trim().slice(-600)}`);
+        return Object.assign({}, ...results);
+    }
+    /** The machine host's clock against this host's: the exchange with the shortest round trip of
+     *  five bounds the error by half that round trip. */
+    async measureOffset() {
+        let best;
+        for (let i = 0; i < 5; i++) {
+            const t0 = hostNowMs();
+            const { out } = await this.rawRun('date +%s%N');
+            const t1 = hostNowMs();
+            const remote = Number(out.trim().split('\n').pop()) / 1e6;
+            const sample = { offset: remote - (t0 + t1) / 2, rtt: t1 - t0 };
+            if (!best || sample.rtt < best.rtt)
+                best = sample;
+        }
+        this.offsetS = best.offset / 1000;
+        return { offsetMs: Math.round(best.offset * 100) / 100, rttMs: Math.round(best.rtt * 100) / 100 };
+    }
+    /** measureOffset, serialized with every other operation. */
+    offset() {
+        const next = this.queue.then(async () => { if (!this.child)
+            await this.open(); return this.measureOffset(); });
+        this.queue = next.catch(() => undefined);
+        return next;
+    }
+    close() { this.child?.stdin.end(); this.child?.kill(); this.child = undefined; }
+}