@start9labs/start-sdk 1.5.2 → 2.0.0

package/lib/util/SubContainer.js

@@ -0,0 +1,862 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExitError = exports.SubContainerLazy = exports.SubContainerEager = exports.SubContainer = exports.execFile = void 0;
+const fs = __importStar(require("fs/promises"));
+const cp = __importStar(require("child_process"));
+const util_1 = require("util");
+const node_buffer_1 = require("node:buffer");
+const once_1 = require("@start9labs/start-core/util/once");
+const Drop_1 = require("@start9labs/start-core/util/Drop");
+exports.execFile = (0, util_1.promisify)(cp.execFile);
+const False = () => false;
+const TIMES_TO_WAIT_FOR_PROC = 100;
+// Returns whether the bind target was prepared as a file (vs a directory),
+// so callers can pass the matching `--file` flag. For `infer` this resolves
+// against the source, so it must be the single source of truth — `bind()`
+// keys `--file` off this rather than re-deciding.
+async function prepBind(from, to, type) {
+    const fromMeta = from ? await fs.stat(from).catch(_ => null) : null;
+    const toMeta = await fs.stat(to).catch(_ => null);
+    if (type === 'file' || (type === 'infer' && from && fromMeta?.isFile())) {
+        if (toMeta && toMeta.isDirectory())
+            await fs.rmdir(to);
+        if (from && !fromMeta) {
+            await fs.mkdir(from.replace(/\/[^\/]*\/?$/, ''), { recursive: true });
+            await fs.writeFile(from, '');
+        }
+        if (!toMeta) {
+            await fs.mkdir(to.replace(/\/[^\/]*\/?$/, ''), { recursive: true });
+            await fs.writeFile(to, '');
+        }
+        return true;
+    }
+    else {
+        if (toMeta && toMeta.isFile() && !toMeta.size)
+            await fs.rm(to);
+        if (from && !fromMeta)
+            await fs.mkdir(from, { recursive: true });
+        if (!toMeta)
+            await fs.mkdir(to, { recursive: true });
+        return false;
+    }
+}
+async function bind(from, to, type, idmap) {
+    const isFile = await prepBind(from, to, type);
+    // Inside the LXC subcontainer (which is itself idmapped), util-linux's
+    // `mount --bind -oX-mount.idmap=...` can't reliably set up a second,
+    // nested idmap. start-container's `bind-mount` subcommand performs the
+    // bind via direct syscalls (open_tree + mount_setattr + move_mount) so
+    // the SDK's idmap field on volume/asset/dependency mounts works.
+    const args = ['bind-mount', '--source', from, '--target', to, '--recursive'];
+    if (isFile) {
+        args.push('--file');
+    }
+    for (const i of idmap) {
+        args.push('--idmap', `${i.fromId}:${i.toId}:${i.range}`);
+    }
+    await (0, exports.execFile)('start-container', args);
+}
+/**
+ * Top-level factories for creating SubContainers. Prefer
+ * {@link SubContainer.of} (lazy) unless you need synchronous access to
+ * `rootfs` / `guid` / `subpath()` before running any methods — for that, use
+ * {@link SubContainer.eager}.
+ */
+exports.SubContainer = {
+    /**
+     * Create a {@link SubContainerLazy} that materializes its backing
+     * filesystem on first use. Synchronous return — no `Promise` wrapper.
+     *
+     * Identity is generated at this call and threaded through to the eager
+     * container produced by {@link SubContainerLazy.eager}.
+     *
+     * This is the default factory. Use it whenever the subcontainer might
+     * not actually be needed (the canonical case: `Daemons.dynamic` may diff
+     * a daemon away before it ever runs) and whenever you don't need sync
+     * access to `rootfs` / `guid` / `subpath()`.
+     *
+     * @param effects The effects context the subcontainer will run under
+     * @param image Image to launch from (must be declared in the manifest); `sharedRun` rbinds the host's `/run` if true
+     * @param mounts Initial mounts applied at materialization (declared so they participate in `Daemons.dynamic`'s `configHash`)
+     * @param name Debug/identification name (does not affect identity)
+     */
+    of(effects, image, mounts, name) {
+        return new SubContainerLazy(effects, image, mounts, name);
+    },
+    /**
+     * Create a {@link SubContainerEager}, materializing the backing
+     * filesystem immediately. Returns `Promise<SubContainerEager>`.
+     *
+     * Use when you need synchronous access to `rootfs` / `guid` /
+     * `subpath()` before running any methods (e.g. mounting paths from
+     * outside the container, init-time precheck), or when you want
+     * `effects.subcontainer.createFs` failures to surface here instead of at
+     * first method call.
+     *
+     * **Do not pass an eager SubContainer to `Daemons.dynamic`'s `fn`**.
+     * Eager handles created inside `fn` are wasted on re-runs that diff to
+     * "leave alone" — use {@link SubContainer.of} (lazy) for daemons under
+     * `Daemons.dynamic`.
+     *
+     * @param effects The effects context the subcontainer will run under
+     * @param image Image to launch from; `sharedRun` rbinds the host's `/run` if true
+     * @param mounts Mounts applied during construction
+     * @param name Debug/identification name (does not affect identity)
+     */
+    eager(effects, image, mounts, name) {
+        return SubContainerEager._of(effects, image, mounts, name, Symbol('subcontainer'));
+    },
+    /**
+     * Run a function with an ephemeral, eager subcontainer. The container
+     * is created before `fn` runs and destroyed in a `finally` block after.
+     * Use for one-off command execution that needs a fresh filesystem.
+     *
+     * @param effects The effects context the subcontainer will run under
+     * @param image Image to launch from; `sharedRun` rbinds the host's `/run` if true
+     * @param mounts Mounts applied during construction
+     * @param name Debug/identification name (does not affect identity)
+     * @param fn Function to invoke with the eager subcontainer
+     * @returns Whatever `fn` returns
+     */
+    async withTemp(effects, image, mounts, name, fn) {
+        const sub = await SubContainerEager._of(effects, image, mounts, name, Symbol('subcontainer'));
+        try {
+            return await fn(sub);
+        }
+        finally {
+            await sub.destroy();
+        }
+    },
+};
+/**
+ * Live eager subcontainers grouped by the effects context that created them.
+ * Any still alive when that context leaves (e.g. a subcontainer created in
+ * `main` but never explicitly destroyed) is torn down via the armed
+ * `onLeaveContext` hook instead of lingering until GC runs its `Drop`
+ * finalizer.
+ *
+ * One hook is armed per distinct effects object — on the first subcontainer
+ * created under it — and each subcontainer removes itself on destroy, so
+ * repeated short-lived containers (`withTemp`, per-poll health checks) don't
+ * accumulate registrations. Destroying via `destroy()` keeps the hold model
+ * intact: a container still held by a running daemon defers teardown until
+ * the daemon's own context-leave releases it.
+ */
+const contextLiveSubcontainers = new WeakMap();
+function registerForContextCleanup(effects, sub) {
+    let live = contextLiveSubcontainers.get(effects);
+    if (!live) {
+        live = new Set();
+        contextLiveSubcontainers.set(effects, live);
+        effects.onLeaveContext(() => {
+            const remaining = contextLiveSubcontainers.get(effects);
+            if (!remaining)
+                return;
+            for (const c of [...remaining]) {
+                c.destroy().catch(e => console.error(e));
+            }
+        });
+    }
+    live.add(sub);
+}
+function unregisterFromContextCleanup(effects, sub) {
+    contextLiveSubcontainers.get(effects)?.delete(sub);
+}
+/**
+ * Want to limit what we can do in a container, so we want to launch a container with a specific image and the mounts.
+ *
+ * Eager subcontainer: its filesystem and leader process exist from
+ * construction. `rootfs` / `guid` / `subpath()` are synchronous.
+ *
+ * Construct via {@link SubContainer.eager} or {@link SubContainer.withTemp}.
+ */
+class SubContainerEager extends Drop_1.Drop {
+    constructor(effects, imageId, rootfs, guid, identity) {
+        super();
+        this.effects = effects;
+        this.imageId = imageId;
+        this.rootfs = rootfs;
+        this.guid = guid;
+        this.identity = identity;
+        this.destroyed = false;
+        this.destroyPending = false;
+        this.holdCount = 0;
+        this.leaderExited = false;
+        this.leaderExited = false;
+        this.leader = cp.spawn('start-container', ['subcontainer', 'launch', rootfs], {
+            killSignal: 'SIGKILL',
+            stdio: 'inherit',
+        });
+        this.leader.on('exit', () => {
+            this.leaderExited = true;
+        });
+        this.waitProc = (0, once_1.once)(() => new Promise(async (resolve, reject) => {
+            let count = 0;
+            while (!(await fs.stat(`${this.rootfs}/proc/1`).then(x => !!x, False))) {
+                if (count++ > TIMES_TO_WAIT_FOR_PROC) {
+                    console.debug('Failed to start subcontainer', {
+                        guid: this.guid,
+                        imageId: this.imageId,
+                        rootfs: this.rootfs,
+                    });
+                    return reject(new Error(`Failed to start subcontainer ${this.imageId}`));
+                }
+                await wait(1);
+            }
+            resolve(null);
+        }));
+    }
+    /**
+     * Internal factory. Accepts an explicit `identity` so a lazy handle can
+     * thread its identity through to the eager it materializes into.
+     * External callers use {@link SubContainer.eager} (which generates its
+     * own identity) or {@link SubContainer.of} (lazy).
+     */
+    static async _of(effects, image, mounts, name, identity) {
+        const { imageId, sharedRun } = image;
+        const [rootfs, guid] = await effects.subcontainer.createFs({
+            imageId,
+            name,
+        });
+        const res = new SubContainerEager(effects, imageId, rootfs, guid, identity);
+        // Arm context cleanup before mounting — if the try below throws,
+        // _destroyImmediate unregisters as it tears the partial container down.
+        registerForContextCleanup(effects, res);
+        try {
+            if (mounts) {
+                await res.mount(mounts);
+            }
+            const shared = ['dev', 'sys'];
+            if (!!sharedRun) {
+                shared.push('run');
+            }
+            await fs.mkdir(`${rootfs}/etc`, { recursive: true });
+            await fs.copyFile('/etc/resolv.conf', `${rootfs}/etc/resolv.conf`);
+            for (const dirPart of shared) {
+                const from = `/${dirPart}`;
+                const to = `${rootfs}/${dirPart}`;
+                await fs.mkdir(from, { recursive: true });
+                await fs.mkdir(to, { recursive: true });
+                await (0, exports.execFile)('mount', ['--rbind', from, to]);
+            }
+            return res;
+        }
+        catch (e) {
+            await res._destroyImmediate();
+            throw e;
+        }
+    }
+    /**
+     * Resolve a path within this subcontainer's rootfs (synchronous on eager).
+     *
+     * @param path Path relative to the rootfs (e.g. `"/etc/config.json"` or `"data/file"`)
+     */
+    subpath(path) {
+        return path.startsWith('/')
+            ? `${this.rootfs}${path}`
+            : `${this.rootfs}/${path}`;
+    }
+    /**
+     * Apply filesystem mounts (volumes, assets, dependencies) to
+     * this subcontainer.
+     *
+     * @param mounts The Mounts configuration to apply
+     * @returns This subcontainer instance for chaining
+     */
+    async mount(mounts) {
+        for (let mount of mounts.build()) {
+            let { options, mountpoint } = mount;
+            const path = mountpoint.startsWith('/')
+                ? `${this.rootfs}${mountpoint}`
+                : `${this.rootfs}/${mountpoint}`;
+            if (options.type === 'volume') {
+                const subpath = options.subpath
+                    ? options.subpath.startsWith('/')
+                        ? options.subpath
+                        : `/${options.subpath}`
+                    : '/';
+                const from = `/media/startos/volumes/${options.volumeId}${subpath}`;
+                await bind(from, path, options.filetype, options.idmap);
+            }
+            else if (options.type === 'assets') {
+                const subpath = options.subpath
+                    ? options.subpath.startsWith('/')
+                        ? options.subpath
+                        : `/${options.subpath}`
+                    : '/';
+                const from = `/media/startos/assets/${subpath}`;
+                await bind(from, path, options.filetype, options.idmap);
+            }
+            else if (options.type === 'pointer') {
+                await prepBind(null, path, 'directory');
+                // The host-side mount effect applies the SDK idmap in startd, which
+                // holds CAP_SYS_ADMIN over the source superblock's userns — the idmap
+                // can't be set from inside the LXC against a host-mounted filesystem.
+                await this.effects.mount({
+                    location: path,
+                    target: options,
+                });
+            }
+            else {
+                throw new Error(`unknown type ${options.type}`);
+            }
+        }
+        return this;
+    }
+    /**
+     * Take a use-hold on this subcontainer. The container is destroyed
+     * when {@link destroy} has been called *and* the last hold is released,
+     * in either order.
+     *
+     * @returns A release function — call it to drop this hold
+     * @throws If this subcontainer has already been destroyed
+     */
+    hold() {
+        if (this.destroyed) {
+            throw new Error(`cannot hold subcontainer ${String(this.identity.description)}: already destroyed`);
+        }
+        this.holdCount++;
+        let released = false;
+        return async () => {
+            if (released)
+                return;
+            released = true;
+            this.holdCount--;
+            if (this.holdCount === 0 && this.destroyPending) {
+                await this._destroyImmediate();
+            }
+        };
+    }
+    /**
+     * Mark this subcontainer for destruction. Fires `destroyFs` immediately
+     * if no holds are outstanding; otherwise the final hold-release fires
+     * it. Idempotent.
+     */
+    async destroy() {
+        this.destroyPending = true;
+        if (this.holdCount === 0)
+            await this._destroyImmediate();
+    }
+    /**
+     * Detach from the creating context's `onLeaveContext` cleanup — drops this
+     * subcontainer from its context's live set so a context-leave no longer
+     * destroys it. The caller becomes responsible for calling {@link destroy}.
+     * Idempotent.
+     */
+    detach() {
+        unregisterFromContextCleanup(this.effects, this);
+    }
+    async _destroyImmediate() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        unregisterFromContextCleanup(this.effects, this);
+        const guid = this.guid;
+        await this.killLeader();
+        await this.effects.subcontainer.destroyFs({ guid });
+    }
+    async killLeader() {
+        if (this.leaderExited)
+            return null;
+        return new Promise((resolve, reject) => {
+            try {
+                let timeout = setTimeout(() => this.leader.kill('SIGKILL'), 30000);
+                this.leader.on('exit', () => {
+                    clearTimeout(timeout);
+                    resolve(null);
+                });
+                if (!this.leader.kill('SIGTERM')) {
+                    reject(new Error('kill(2) failed'));
+                }
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+    }
+    onDrop() {
+        if (!this.destroyed && this.holdCount === 0) {
+            console.log(`Cleaning up dangling subcontainer ${this.guid}`);
+            this._destroyImmediate().catch(e => console.error(e));
+        }
+    }
+    /**
+     * Run a command inside this subcontainer.
+     * Does NOT throw on non-zero exit (see {@link execFail}).
+     *
+     * @param command Argv array representing the command and its arguments
+     * @param options Optional environment, user, cwd, and stdin input
+     * @param timeoutMs How long to wait before SIGKILL (default 30 s, `null` for no timeout)
+     * @param abort Optional AbortController; aborting SIGKILLs the process
+     */
+    async exec(command, options, timeoutMs = 30000, abort) {
+        await this.waitProc();
+        const imageMeta = await fs
+            .readFile(`/media/startos/images/${this.imageId}.json`, {
+            encoding: 'utf8',
+        })
+            .catch(() => '{}')
+            .then(JSON.parse);
+        let extra = [];
+        let user = imageMeta.user || 'root';
+        if (options?.user) {
+            user = options.user;
+            delete options.user;
+        }
+        let workdir = imageMeta.workdir || '/';
+        if (options?.cwd) {
+            workdir = options.cwd;
+            delete options.cwd;
+        }
+        if (options?.env) {
+            for (let [k, v] of Object.entries(options.env)) {
+                extra.push(`--env=${k}=${v}`);
+            }
+        }
+        const child = cp.spawn('start-container', [
+            'subcontainer',
+            'exec',
+            `--env-file=/media/startos/images/${this.imageId}.env`,
+            `--user=${user}`,
+            `--workdir=${workdir}`,
+            ...extra,
+            this.rootfs,
+            ...command,
+        ], options || {});
+        abort?.signal.addEventListener('abort', () => child.kill('SIGKILL'));
+        if (options?.input) {
+            await new Promise((resolve, reject) => {
+                try {
+                    child.stdin.on('error', e => reject(e));
+                    child.stdin.write(options.input, e => {
+                        if (e) {
+                            reject(e);
+                        }
+                        else {
+                            resolve(null);
+                        }
+                    });
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+            await new Promise((resolve, reject) => {
+                try {
+                    child.stdin.end(resolve);
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+        }
+        const stdout = { data: '' };
+        const stderr = { data: '' };
+        const appendData = (appendTo) => (chunk) => {
+            if (typeof chunk === 'string' || chunk instanceof node_buffer_1.Buffer) {
+                appendTo.data += chunk.toString();
+            }
+            else {
+                console.error('received unexpected chunk', chunk);
+            }
+        };
+        return new Promise((resolve, reject) => {
+            child.on('error', reject);
+            let killTimeout;
+            if (timeoutMs !== null && child.pid) {
+                killTimeout = setTimeout(() => child.kill('SIGKILL'), timeoutMs);
+            }
+            child.stdout.on('data', appendData(stdout));
+            child.stderr.on('data', appendData(stderr));
+            child.on('exit', (code, signal) => {
+                clearTimeout(killTimeout);
+                const result = {
+                    exitCode: code,
+                    exitSignal: signal,
+                    stdout: stdout.data,
+                    stderr: stderr.data,
+                };
+                resolve({
+                    throw: () => !code && !signal
+                        ? { stdout: stdout.data, stderr: stderr.data }
+                        : (() => {
+                            throw new ExitError(command[0], result);
+                        })(),
+                    ...result,
+                });
+            });
+        });
+    }
+    /**
+     * Run a command inside this subcontainer, throwing on non-zero exit.
+     *
+     * @param command Argv array representing the command and its arguments
+     * @param options Optional environment, user, cwd, and stdin input
+     * @param timeoutMs How long to wait before SIGKILL (default 30 s, `null` for no timeout)
+     * @param abort Optional AbortController; aborting SIGKILLs the process
+     * @throws {@link ExitError} on non-zero exit code or signal termination
+     */
+    async execFail(command, options, timeoutMs, abort) {
+        return this.exec(command, options, timeoutMs, abort).then(res => res.throw());
+    }
+    /**
+     * Launch a command as the init (PID 1) process of the subcontainer.
+     * Replaces the current leader process.
+     *
+     * @param command Argv array representing the command and its arguments
+     * @param options Optional environment, working directory, and user overrides
+     */
+    async launch(command, options) {
+        await this.waitProc();
+        const imageMeta = await fs
+            .readFile(`/media/startos/images/${this.imageId}.json`, {
+            encoding: 'utf8',
+        })
+            .catch(() => '{}')
+            .then(JSON.parse);
+        let extra = [];
+        let user = imageMeta.user || 'root';
+        if (options?.user) {
+            user = options.user;
+            delete options.user;
+        }
+        let workdir = imageMeta.workdir || '/';
+        if (options?.cwd) {
+            workdir = options.cwd;
+            delete options.cwd;
+        }
+        if (options?.env) {
+            for (let [k, v] of Object.entries(options.env).filter(([_, v]) => v != undefined)) {
+                extra.push(`--env=${k}=${v}`);
+            }
+        }
+        await this.killLeader();
+        this.leaderExited = false;
+        this.leader = cp.spawn('start-container', [
+            'subcontainer',
+            'launch',
+            `--env-file=/media/startos/images/${this.imageId}.env`,
+            `--user=${user}`,
+            `--workdir=${workdir}`,
+            ...extra,
+            this.rootfs,
+            ...command,
+        ], { ...options, stdio: 'inherit' });
+        this.leader.on('exit', () => {
+            this.leaderExited = true;
+        });
+        return this.leader;
+    }
+    /**
+     * Spawn a command inside the subcontainer as a non-init process.
+     *
+     * @param command Argv array representing the command and its arguments
+     * @param options Optional environment, working directory, user, and stdio overrides
+     */
+    async spawn(command, options = { stdio: 'inherit' }) {
+        await this.waitProc();
+        const imageMeta = await fs
+            .readFile(`/media/startos/images/${this.imageId}.json`, {
+            encoding: 'utf8',
+        })
+            .catch(() => '{}')
+            .then(JSON.parse);
+        let extra = [];
+        let user = imageMeta.user || 'root';
+        if (options?.user) {
+            user = options.user;
+            delete options.user;
+        }
+        let workdir = imageMeta.workdir || '/';
+        if (options.cwd) {
+            workdir = options.cwd;
+            delete options.cwd;
+        }
+        if (options?.env) {
+            for (let [k, v] of Object.entries(options.env).filter(([_, v]) => v != undefined)) {
+                extra.push(`--env=${k}=${v}`);
+            }
+        }
+        return cp.spawn('start-container', [
+            'subcontainer',
+            'exec',
+            `--env-file=/media/startos/images/${this.imageId}.env`,
+            `--user=${user}`,
+            `--workdir=${workdir}`,
+            ...extra,
+            this.rootfs,
+            ...command,
+        ], options);
+    }
+    /**
+     * Write a file to the subcontainer's filesystem.
+     *
+     * @param path Path relative to the subcontainer rootfs (e.g. `"/etc/config.json"`)
+     * @param data The data to write
+     * @param options Optional write options (same as `node:fs/promises` `writeFile`)
+     */
+    async writeFile(path, data, options) {
+        const fullPath = this.subpath(path);
+        const dir = fullPath.replace(/\/[^/]*\/?$/, '');
+        await fs.mkdir(dir, { recursive: true });
+        return fs.writeFile(fullPath, data, options);
+    }
+}
+exports.SubContainerEager = SubContainerEager;
+/**
+ * Lazy subcontainer: a handle whose backing filesystem is materialized on
+ * first use (or explicit {@link SubContainerLazy.eager}). The narrow types
+ * for `rootfs` / `guid` / `subpath()` are `Promise<...>`.
+ *
+ * Construct via {@link SubContainer.of}. Identity is generated at
+ * construction and preserved across materialization.
+ *
+ * Sharing across consumers: pass the same `SubContainerLazy` to multiple
+ * `addDaemon` calls. The first consumer to call a method (or `.eager()`)
+ * triggers materialization; all consumers end up holding the same
+ * underlying {@link SubContainerEager}.
+ */
+class SubContainerLazy extends Drop_1.Drop {
+    constructor(effects, image, mounts, name) {
+        super();
+        this.effects = effects;
+        this.identity = Symbol('subcontainer');
+        this.materialized = null;
+        this.destroyPending = false;
+        this.detachPending = false;
+        this.imageId = image.imageId;
+        this.sharedRun = image.sharedRun ?? false;
+        this.mounts = mounts;
+        this.name = name;
+    }
+    /**
+     * Materialize the underlying eager subcontainer (idempotent) and return
+     * it. Subsequent calls return the same instance. Useful when you need
+     * the synchronous `SubContainerEager` interface (e.g. sync `rootfs` /
+     * `subpath()`) — for ordinary command execution, just call `.exec()` /
+     * `.writeFile()` directly and the lazy handle materializes internally.
+     */
+    eager() {
+        return (this.materialized ??= SubContainerEager._of(this.effects, { imageId: this.imageId, sharedRun: this.sharedRun }, this.mounts, this.name, this.identity).then(async (eager) => {
+            if (this.destroyPending)
+                await eager.destroy();
+            else if (this.detachPending)
+                eager.detach();
+            return eager;
+        }));
+    }
+    /** Absolute path to the materialized subcontainer's rootfs. Triggers materialization on first access. */
+    get rootfs() {
+        return this.eager().then(e => e.rootfs);
+    }
+    /** OS-level guid. Triggers materialization on first access. */
+    get guid() {
+        return this.eager().then(e => e.guid);
+    }
+    /**
+     * Resolve a path within the subcontainer's rootfs. Triggers
+     * materialization on first call.
+     *
+     * @param path Path relative to the rootfs
+     */
+    async subpath(path) {
+        return (await this.eager()).subpath(path);
+    }
+    /**
+     * Apply filesystem mounts to this subcontainer (materializes on first
+     * call). Mounts beyond the ones declared at construction are not part
+     * of `Daemons.dynamic`'s `configHash`.
+     *
+     * @param mounts The Mounts configuration to apply
+     * @returns This lazy handle, for chaining
+     */
+    async mount(mounts) {
+        await (await this.eager()).mount(mounts);
+        return this;
+    }
+    /**
+     * Take a use-hold on this subcontainer. Materializes the underlying
+     * eager subcontainer asynchronously and places the hold on it.
+     *
+     * The returned release function is safe to call before materialization
+     * completes — it cancels the pending hold so a never-materialized lazy
+     * (the canonical "left alone" case in `Daemons.dynamic`) stays cheap.
+     *
+     * @returns A release function — call it to drop this hold
+     */
+    hold() {
+        // Acquire the hold on the eager once materialized. Until then we record
+        // a "pending" intent so destroy() honors any outstanding holds even on
+        // a never-materialized handle.
+        let released = false;
+        let underlyingRelease = null;
+        const eagerPromise = this.eager();
+        const acquired = eagerPromise
+            .then(eager => {
+            if (released)
+                return;
+            underlyingRelease = eager.hold();
+        })
+            .catch(e => {
+            released = true;
+            throw e;
+        });
+        return async () => {
+            if (released)
+                return;
+            released = true;
+            try {
+                await acquired;
+            }
+            catch (_) {
+                // materialization failed; nothing to release
+                return;
+            }
+            if (underlyingRelease)
+                await underlyingRelease();
+        };
+    }
+    /**
+     * Mark this subcontainer for destruction. If already materialized, the
+     * underlying eager's destroy is invoked (which respects outstanding
+     * holds). If never materialized, the destroy pending flag is set so
+     * that any future materialization fires destroy immediately.
+     */
+    async destroy() {
+        this.destroyPending = true;
+        if (this.materialized)
+            await (await this.materialized).destroy();
+    }
+    /**
+     * Detach from the creating context's `onLeaveContext` cleanup. If already
+     * materialized, detaches the underlying eager; otherwise records the intent
+     * so materialization detaches immediately. Idempotent.
+     */
+    detach() {
+        this.detachPending = true;
+        if (this.materialized) {
+            this.materialized.then(e => e.detach()).catch(e => console.error(e));
+        }
+    }
+    /**
+     * Run a command inside this subcontainer (materializes on first call).
+     * Does NOT throw on non-zero exit (see {@link execFail}).
+     *
+     * @param command Argv array representing the command and its arguments
+     * @param options Optional environment, user, cwd, and stdin input
+     * @param timeoutMs How long to wait before SIGKILL (default 30 s, `null` for no timeout)
+     * @param abort Optional AbortController; aborting SIGKILLs the process
+     */
+    async exec(command, options, timeoutMs = 30000, abort) {
+        return (await this.eager()).exec(command, options, timeoutMs, abort);
+    }
+    /**
+     * Run a command inside this subcontainer, throwing on non-zero exit
+     * (materializes on first call).
+     *
+     * @param command Argv array representing the command and its arguments
+     * @param options Optional environment, user, cwd, and stdin input
+     * @param timeoutMs How long to wait before SIGKILL (default 30 s, `null` for no timeout)
+     * @param abort Optional AbortController; aborting SIGKILLs the process
+     * @throws {@link ExitError} on non-zero exit code or signal termination
+     */
+    async execFail(command, options, timeoutMs, abort) {
+        return (await this.eager()).execFail(command, options, timeoutMs, abort);
+    }
+    /**
+     * Launch a command as the init (PID 1) process of the subcontainer
+     * (materializes on first call).
+     *
+     * @param command Argv array representing the command and its arguments
+     * @param options Optional environment, working directory, and user overrides
+     */
+    async launch(command, options) {
+        return (await this.eager()).launch(command, options);
+    }
+    /**
+     * Spawn a command inside the subcontainer as a non-init process
+     * (materializes on first call).
+     *
+     * @param command Argv array representing the command and its arguments
+     * @param options Optional environment, working directory, user, and stdio overrides
+     */
+    async spawn(command, options) {
+        return (await this.eager()).spawn(command, options);
+    }
+    /**
+     * Write a file to the subcontainer's filesystem (materializes on first call).
+     *
+     * @param path Path relative to the subcontainer rootfs (e.g. `"/etc/config.json"`)
+     * @param data The data to write
+     * @param options Optional write options (same as `node:fs/promises` `writeFile`)
+     */
+    async writeFile(path, data, options) {
+        return (await this.eager()).writeFile(path, data, options);
+    }
+    onDrop() {
+        if (this.materialized) {
+            this.materialized.then(e => e.destroy()).catch(e => console.error(e));
+        }
+    }
+}
+exports.SubContainerLazy = SubContainerLazy;
+function wait(time) {
+    return new Promise(resolve => setTimeout(resolve, time));
+}
+/**
+ * Error thrown when a subcontainer command exits with a non-zero code or
+ * signal. Contains the full result including stdout, stderr, exit code,
+ * and exit signal.
+ */
+class ExitError extends Error {
+    constructor(command, result) {
+        let message;
+        if (result.exitCode) {
+            message = `${command} failed with exit code ${result.exitCode}: ${result.stderr}`;
+        }
+        else if (result.exitSignal) {
+            message = `${command} terminated with signal ${result.exitSignal}: ${result.stderr}`;
+        }
+        else {
+            message = `${command} succeeded: ${result.stdout}`;
+        }
+        super(message);
+        this.command = command;
+        this.result = result;
+    }
+}
+exports.ExitError = ExitError;
+//# sourceMappingURL=SubContainer.js.map