@hotcell/daemon 0.1.0

package/dist/driver/container.d.ts

@@ -0,0 +1,99 @@
+import Docker from "dockerode";
+import type { ExecEvent, ExecOptions, FileChangeEvent, FileInfo, ListFilesOptions, MkdirOptions, ReadFileOptions, StartProcessOptions, WaitForPortOptions, WatchOptions, WriteFileOptions } from "../types.js";
+import type { CreateOptions, Driver, ProcessLiveness, HostInfo, SandboxStats, StartProcessResult, TcpBridge, TerminalOptions, TerminalSession } from "./types.js";
+/**
+ * Container driver — backs each sandbox with a long-lived OCI container via the
+ * Docker Engine API. Maximum density and works identically on Linux and macOS
+ * (Docker Desktop / colima / Apple `container`'s Docker-compatible endpoint).
+ *
+ * The container is named deterministically from the sandbox id and kept alive
+ * (`sleep infinity` / image default) so the daemon can `exec` into it on demand
+ * — the same model Docker exec gives us for free in Phase 0, standing in for the
+ * dedicated in-sandbox agent that the microVM drivers will need.
+ */
+/** Egress-enforcement network settings, passed in from config by the driver factory. */
+export interface EgressNetConfig {
+    enforce: boolean;
+    network: string;
+    subnet: string;
+    /** Pinned DNS resolver IP, or "" for Docker's embedded resolver. */
+    dns: string;
+}
+export declare class ContainerDriver implements Driver {
+    readonly name = "container";
+    private docker;
+    private ensured;
+    private egress?;
+    private egressNetReady;
+    constructor(docker?: Docker, egress?: EgressNetConfig);
+    private containerName;
+    /** Deterministic name for the sandbox's persistent workspace volume. */
+    private volumeName;
+    ping(): Promise<void>;
+    hostInfo(): Promise<HostInfo>;
+    /**
+     * Create the egress-enforcement bridge network if missing (idempotent). Uses the
+     * configured subnet so the host firewall's `-s <subnet>` rules match, with the
+     * gateway pinned to `.1`. Safe to call repeatedly; a 409 (already exists) is fine.
+     */
+    private ensureEgressNetwork;
+    /** Create the workspace volume if it does not already exist (idempotent). */
+    private ensureVolume;
+    /** Pull the image if it is not already present locally. */
+    private ensureImage;
+    create(opts: CreateOptions): Promise<void>;
+    /**
+     * Clone a git repo into `/workspace` at create time so an agent comes up with
+     * the code in place. Installs git first if the image lacks it (the default
+     * slim image), then shallow-clones into a subdir named after the repo. A
+     * failure throws — unlike best-effort `setup`, the agent needs the code.
+     */
+    private cloneRepo;
+    /**
+     * Run declarative setup commands in order, once, after the container starts.
+     * Best-effort: a non-zero exit is logged but does not fail create. Kept out of
+     * `launchContainer` on purpose so it does not re-fire on `start()`/resume.
+     */
+    private runSetup;
+    start(opts: CreateOptions): Promise<void>;
+    stop(id: string): Promise<void>;
+    /** Shared create/start path: ensure image (+volume), then run the container. */
+    private launchContainer;
+    exec(id: string, command: string, opts: ExecOptions, onEvent: (e: ExecEvent) => void): Promise<number>;
+    /**
+     * Run a non-interactive command and capture its streams + exit code. Never
+     * throws on a non-zero exit — callers decide what a failure means.
+     */
+    private execCapture;
+    /**
+     * Run a non-interactive command and return its stdout as a UTF-8 string.
+     * Throws if the command exits non-zero.
+     */
+    private runAndCapture;
+    writeFile(id: string, opts: WriteFileOptions): Promise<void>;
+    readFile(id: string, opts: ReadFileOptions): Promise<string>;
+    mkdir(id: string, opts: MkdirOptions): Promise<void>;
+    listFiles(id: string, opts: ListFilesOptions): Promise<FileInfo[]>;
+    watchFiles(id: string, path: string, opts: WatchOptions & {
+        signal: AbortSignal;
+    }, onEvent: (e: FileChangeEvent) => void): Promise<void>;
+    startProcess(id: string, procId: string, command: string, opts: StartProcessOptions): Promise<StartProcessResult>;
+    listProcesses(id: string, procs: Array<{
+        procId: string;
+        pid: number;
+    }>): Promise<ProcessLiveness[]>;
+    killProcess(id: string, pid: number, signal?: string): Promise<void>;
+    streamProcessLogs(id: string, logPath: string, opts: {
+        follow: boolean;
+        signal: AbortSignal;
+    }, onData: (chunk: string) => void): Promise<void>;
+    waitForPort(id: string, port: number, opts: WaitForPortOptions): Promise<boolean>;
+    openTcpBridge(id: string, port: number, host: string): Promise<TcpBridge>;
+    openTerminal(id: string, opts: TerminalOptions): Promise<TerminalSession>;
+    createBackup(id: string, tarPath: string): Promise<{
+        bytes: number;
+    }>;
+    restoreBackup(id: string, tarPath: string): Promise<void>;
+    stats(id: string): Promise<SandboxStats>;
+    destroy(id: string): Promise<void>;
+}