matchlock-sdk 0.1.25 → 0.1.27

package/README.md

@@ -45,6 +45,8 @@ try {
 }
 ```
 
+`client.launch(...)` starts image ENTRYPOINT/CMD in detached mode. Use `client.create(...)` when you want a VM without auto-starting image command.
+
 Callback-based interception:
 
 ```ts
@@ -75,8 +77,9 @@ const sandbox = new Sandbox("alpine:latest").withNetworkInterception({
 - Fluent sandbox builder (`Sandbox`) with network, secrets, mounts, env, VFS hooks, image config
 - Typed network interception rules and local callback hooks via `withNetworkInterception(...)`
 - Supports fully offline mode via `.withNoNetwork()` (no guest NIC / no egress)
-- JSON-RPC `create`, `exec`, `exec_stream`, `write_file`, `read_file`, `list_files`, `port_forward`, `cancel`, `close`
-- Streaming stdout/stderr via `execStream`
+- JSON-RPC `create`, `exec`, `exec_stream`, `exec_pipe`, `exec_tty`, `write_file`, `read_file`, `list_files`, `port_forward`, `cancel`, `close`
+- Streaming stdout/stderr via `execStream` and bidirectional stdin/stdout/stderr via `execPipe`
+- Interactive PTY shell/commands via `execInteractive` (stdin/stdout + resize events)
 - Local VFS callbacks (`hook`, `dangerousHook`, `mutateHook`, `actionHook`)
 - Port forwarding API parity (`portForward`, `portForwardWithAddresses`)
 - Lifecycle control (`close`, `remove`, `vmId`)

package/dist/client/create.d.ts

@@ -0,0 +1,4 @@
+import type { CreateOptions } from "../types";
+import type { JSONObject, WireNetworkInterceptionConfig, WireVFSInterceptionConfig } from "./wire";
+export declare function validateCreateOptions(options: CreateOptions): void;
+export declare function buildCreateParams(options: CreateOptions, wireVFS: WireVFSInterceptionConfig | undefined, wireNetworkInterception: WireNetworkInterceptionConfig | undefined): JSONObject;

package/dist/client/create.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCreateOptions = validateCreateOptions;
+exports.buildCreateParams = buildCreateParams;
+const errors_1 = require("../errors");
+const utils_1 = require("./utils");
+function validateCreateOptions(options) {
+    if (!options.image) {
+        throw new errors_1.MatchlockError("image is required (e.g., alpine:latest)");
+    }
+    if ((options.networkMtu ?? 0) < 0) {
+        throw new errors_1.MatchlockError("network mtu must be > 0");
+    }
+    if (options.noNetwork &&
+        ((options.allowedHosts?.length ?? 0) > 0 ||
+            (options.secrets?.length ?? 0) > 0 ||
+            options.forceInterception === true ||
+            options.networkInterception !== undefined)) {
+        throw new errors_1.MatchlockError("no network cannot be combined with allowed hosts, secrets, forced interception, or network interception rules");
+    }
+}
+function buildCreateParams(options, wireVFS, wireNetworkInterception) {
+    const resources = {
+        cpus: options.cpus || utils_1.DEFAULT_CPUS,
+        memory_mb: options.memoryMb || utils_1.DEFAULT_MEMORY_MB,
+        disk_size_mb: options.diskSizeMb || utils_1.DEFAULT_DISK_SIZE_MB,
+        timeout_seconds: options.timeoutSeconds || utils_1.DEFAULT_TIMEOUT_SECONDS,
+    };
+    const params = {
+        image: options.image ?? "",
+        resources,
+    };
+    if (options.privileged) {
+        params.privileged = true;
+    }
+    const network = buildCreateNetworkParams(options, wireNetworkInterception);
+    if (network) {
+        params.network = network;
+    }
+    if ((options.mounts && Object.keys(options.mounts).length > 0) ||
+        options.workspace ||
+        wireVFS) {
+        const vfs = {};
+        if (options.mounts && Object.keys(options.mounts).length > 0) {
+            const mounts = {};
+            for (const [guestPath, config] of Object.entries(options.mounts)) {
+                const mount = {
+                    type: config.type ?? "memory",
+                };
+                if (config.hostPath) {
+                    mount.host_path = config.hostPath;
+                }
+                if (config.readonly) {
+                    mount.readonly = true;
+                }
+                mounts[guestPath] = mount;
+            }
+            vfs.mounts = mounts;
+        }
+        if (options.workspace) {
+            vfs.workspace = options.workspace;
+        }
+        if (wireVFS) {
+            vfs.interception = wireVFS;
+        }
+        params.vfs = vfs;
+    }
+    if (options.env && Object.keys(options.env).length > 0) {
+        params.env = options.env;
+    }
+    if (options.imageConfig) {
+        const imageConfig = {};
+        if (options.imageConfig.user) {
+            imageConfig.user = options.imageConfig.user;
+        }
+        if (options.imageConfig.workingDir) {
+            imageConfig.working_dir = options.imageConfig.workingDir;
+        }
+        if (options.imageConfig.entrypoint) {
+            imageConfig.entrypoint = [...options.imageConfig.entrypoint];
+        }
+        if (options.imageConfig.cmd) {
+            imageConfig.cmd = [...options.imageConfig.cmd];
+        }
+        if (options.imageConfig.env) {
+            imageConfig.env = { ...options.imageConfig.env };
+        }
+        params.image_config = imageConfig;
+    }
+    if (options.launchEntrypoint) {
+        params.launch_entrypoint = true;
+    }
+    return params;
+}
+function resolveCreateBlockPrivateIPs(opts) {
+    if (opts.blockPrivateIPsSet) {
+        return { value: !!opts.blockPrivateIPs, hasOverride: true };
+    }
+    if (opts.blockPrivateIPs) {
+        return { value: true, hasOverride: true };
+    }
+    return { value: false, hasOverride: false };
+}
+function buildCreateNetworkParams(opts, wireInterception) {
+    const hasAllowedHosts = (opts.allowedHosts?.length ?? 0) > 0;
+    const hasAddHosts = (opts.addHosts?.length ?? 0) > 0;
+    const hasSecrets = (opts.secrets?.length ?? 0) > 0;
+    const hasDNSServers = (opts.dnsServers?.length ?? 0) > 0;
+    const hasHostname = (opts.hostname?.length ?? 0) > 0;
+    const hasMTU = (opts.networkMtu ?? 0) > 0;
+    const hasNoNetwork = opts.noNetwork === true;
+    const hasForceInterception = opts.forceInterception === true;
+    const hasNetworkInterception = wireInterception !== undefined;
+    const blockPrivate = resolveCreateBlockPrivateIPs(opts);
+    const includeNetwork = hasAllowedHosts ||
+        hasAddHosts ||
+        hasSecrets ||
+        hasDNSServers ||
+        hasHostname ||
+        hasMTU ||
+        hasNoNetwork ||
+        blockPrivate.hasOverride ||
+        hasForceInterception ||
+        hasNetworkInterception;
+    if (!includeNetwork) {
+        return undefined;
+    }
+    if (hasNoNetwork) {
+        const network = {
+            no_network: true,
+        };
+        if (hasAddHosts) {
+            network.add_hosts = (opts.addHosts ?? []).map((mapping) => ({
+                host: mapping.host,
+                ip: mapping.ip,
+            }));
+        }
+        if (hasDNSServers) {
+            network.dns_servers = opts.dnsServers ?? [];
+        }
+        if (hasHostname) {
+            network.hostname = opts.hostname ?? "";
+        }
+        return network;
+    }
+    const network = {
+        allowed_hosts: opts.allowedHosts ?? [],
+        block_private_ips: blockPrivate.hasOverride ? blockPrivate.value : true,
+    };
+    if (hasForceInterception || hasNetworkInterception) {
+        network.intercept = true;
+    }
+    if (hasNetworkInterception) {
+        network.interception = wireInterception;
+    }
+    if (hasAddHosts) {
+        network.add_hosts = (opts.addHosts ?? []).map((mapping) => ({
+            host: mapping.host,
+            ip: mapping.ip,
+        }));
+    }
+    if (hasSecrets) {
+        const secrets = {};
+        for (const secret of opts.secrets ?? []) {
+            secrets[secret.name] = {
+                value: secret.value,
+                hosts: secret.hosts ?? [],
+            };
+        }
+        network.secrets = secrets;
+    }
+    if (hasDNSServers) {
+        network.dns_servers = opts.dnsServers ?? [];
+    }
+    if (hasHostname) {
+        network.hostname = opts.hostname ?? "";
+    }
+    if (hasMTU) {
+        network.mtu = opts.networkMtu ?? 0;
+    }
+    return network;
+}

package/dist/client/exec.d.ts

@@ -0,0 +1,29 @@
+import type { ExecInteractiveOptions, ExecInteractiveResult, ExecOptions, ExecPipeOptions, ExecPipeResult, ExecResult, ExecStreamOptions, ExecStreamResult, RequestOptions, StreamReader, StreamWriter } from "../types";
+import type { JSONObject, JSONValue } from "./wire";
+type NotificationHandler = (method: string, params: JSONObject) => void;
+type SendRequestFunc = (method: string, params?: JSONObject, options?: RequestOptions, onNotification?: NotificationHandler) => Promise<JSONValue>;
+type SendFireAndForgetFunc = (method: string, params?: JSONObject) => Promise<void>;
+export declare class ExecAPI {
+    private readonly sendRequest;
+    private readonly sendFireAndForget;
+    constructor(sendRequest: SendRequestFunc, sendFireAndForget: SendFireAndForgetFunc);
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    execWithDir(command: string, workingDir?: string, options?: RequestOptions): Promise<ExecResult>;
+    execStream(command: string, options?: ExecStreamOptions): Promise<ExecStreamResult>;
+    execStreamWithDir(command: string, workingDir?: string, stdout?: StreamWriter, stderr?: StreamWriter, options?: RequestOptions): Promise<ExecStreamResult>;
+    execPipe(command: string, options?: ExecPipeOptions): Promise<ExecPipeResult>;
+    execPipeWithDir(command: string, workingDir?: string, stdin?: StreamReader, stdout?: StreamWriter, stderr?: StreamWriter, options?: RequestOptions): Promise<ExecPipeResult>;
+    execInteractive(command: string, options?: ExecInteractiveOptions): Promise<ExecInteractiveResult>;
+    private createReadySignal;
+    private createStopSignal;
+    private decodeBase64;
+    private isAsyncIterable;
+    private isIterable;
+    private toAsyncIterable;
+    private pumpExecInput;
+    private pumpTTYResize;
+    private nextAsyncItem;
+    private closeAsyncIterator;
+    private writeStreamChunk;
+}
+export {};

package/dist/client/exec.js

@@ -0,0 +1,356 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecAPI = void 0;
+const utils_1 = require("./utils");
+class ExecAPI {
+    sendRequest;
+    sendFireAndForget;
+    constructor(sendRequest, sendFireAndForget) {
+        this.sendRequest = sendRequest;
+        this.sendFireAndForget = sendFireAndForget;
+    }
+    async exec(command, options = {}) {
+        return this.execWithDir(command, options.workingDir ?? "", options);
+    }
+    async execWithDir(command, workingDir = "", options = {}) {
+        const params = { command };
+        if (workingDir) {
+            params.working_dir = workingDir;
+        }
+        const result = (0, utils_1.asObject)(await this.sendRequest("exec", params, options));
+        return {
+            exitCode: (0, utils_1.asNumber)(result.exit_code),
+            stdout: Buffer.from((0, utils_1.asString)(result.stdout), "base64").toString("utf8"),
+            stderr: Buffer.from((0, utils_1.asString)(result.stderr), "base64").toString("utf8"),
+            durationMs: (0, utils_1.asNumber)(result.duration_ms),
+        };
+    }
+    async execStream(command, options = {}) {
+        return this.execStreamWithDir(command, options.workingDir ?? "", options.stdout, options.stderr, options);
+    }
+    async execStreamWithDir(command, workingDir = "", stdout, stderr, options = {}) {
+        const params = { command };
+        if (workingDir) {
+            params.working_dir = workingDir;
+        }
+        const onNotification = (method, payload) => {
+            const data = (0, utils_1.asString)(payload.data);
+            if (!data) {
+                return;
+            }
+            let decoded;
+            try {
+                decoded = Buffer.from(data, "base64");
+            }
+            catch {
+                return;
+            }
+            if (method === "exec_stream.stdout") {
+                this.writeStreamChunk(stdout, decoded);
+            }
+            else if (method === "exec_stream.stderr") {
+                this.writeStreamChunk(stderr, decoded);
+            }
+        };
+        const result = (0, utils_1.asObject)(await this.sendRequest("exec_stream", params, options, onNotification));
+        return {
+            exitCode: (0, utils_1.asNumber)(result.exit_code),
+            durationMs: (0, utils_1.asNumber)(result.duration_ms),
+        };
+    }
+    async execPipe(command, options = {}) {
+        return this.execPipeWithDir(command, options.workingDir ?? "", options.stdin, options.stdout, options.stderr, options);
+    }
+    async execPipeWithDir(command, workingDir = "", stdin, stdout, stderr, options = {}) {
+        const params = { command };
+        if (workingDir) {
+            params.working_dir = workingDir;
+        }
+        const stop = this.createStopSignal();
+        const ready = this.createReadySignal();
+        const inputPump = this.pumpExecInput(stdin, ready.promise, stop, "exec_pipe.stdin", "exec_pipe.stdin_eof");
+        const onNotification = (method, payload) => {
+            if (method === "exec_pipe.ready") {
+                const reqID = (0, utils_1.asNumber)(payload.id, -1);
+                if (reqID >= 0) {
+                    ready.markReady(reqID);
+                }
+                return;
+            }
+            const data = (0, utils_1.asString)(payload.data);
+            if (!data) {
+                return;
+            }
+            const decoded = this.decodeBase64(data);
+            if (!decoded) {
+                return;
+            }
+            if (method === "exec_pipe.stdout") {
+                this.writeStreamChunk(stdout, decoded);
+            }
+            else if (method === "exec_pipe.stderr") {
+                this.writeStreamChunk(stderr, decoded);
+            }
+        };
+        try {
+            const result = (0, utils_1.asObject)(await this.sendRequest("exec_pipe", params, options, onNotification));
+            return {
+                exitCode: (0, utils_1.asNumber)(result.exit_code),
+                durationMs: (0, utils_1.asNumber)(result.duration_ms),
+            };
+        }
+        finally {
+            stop.stop();
+            ready.markReady(undefined);
+            await inputPump.catch(() => undefined);
+        }
+    }
+    async execInteractive(command, options = {}) {
+        const rows = (options.rows ?? 24) > 0 ? options.rows ?? 24 : 24;
+        const cols = (options.cols ?? 80) > 0 ? options.cols ?? 80 : 80;
+        const params = {
+            command,
+            rows,
+            cols,
+        };
+        if (options.workingDir) {
+            params.working_dir = options.workingDir;
+        }
+        const stop = this.createStopSignal();
+        const ready = this.createReadySignal();
+        const inputPump = this.pumpExecInput(options.stdin, ready.promise, stop, "exec_tty.stdin", "exec_tty.stdin_eof");
+        const resizePump = this.pumpTTYResize(options.resize, ready.promise, stop);
+        const onNotification = (method, payload) => {
+            if (method === "exec_tty.ready") {
+                const reqID = (0, utils_1.asNumber)(payload.id, -1);
+                if (reqID >= 0) {
+                    ready.markReady(reqID);
+                }
+                return;
+            }
+            if (method !== "exec_tty.stdout") {
+                return;
+            }
+            const data = (0, utils_1.asString)(payload.data);
+            if (!data) {
+                return;
+            }
+            const decoded = this.decodeBase64(data);
+            if (!decoded) {
+                return;
+            }
+            this.writeStreamChunk(options.stdout, decoded);
+        };
+        try {
+            const result = (0, utils_1.asObject)(await this.sendRequest("exec_tty", params, options, onNotification));
+            return {
+                exitCode: (0, utils_1.asNumber)(result.exit_code),
+                durationMs: (0, utils_1.asNumber)(result.duration_ms),
+            };
+        }
+        finally {
+            stop.stop();
+            ready.markReady(undefined);
+            await Promise.all([
+                inputPump.catch(() => undefined),
+                resizePump.catch(() => undefined),
+            ]);
+        }
+    }
+    createReadySignal() {
+        let resolved = false;
+        let resolveFn = () => { };
+        const promise = new Promise((resolve) => {
+            resolveFn = resolve;
+        });
+        return {
+            promise,
+            markReady: (reqID) => {
+                if (resolved) {
+                    return;
+                }
+                resolved = true;
+                resolveFn(reqID);
+            },
+        };
+    }
+    createStopSignal() {
+        let stopped = false;
+        let resolveFn = () => { };
+        const promise = new Promise((resolve) => {
+            resolveFn = resolve;
+        });
+        return {
+            promise,
+            isStopped: () => stopped,
+            stop: () => {
+                if (stopped) {
+                    return;
+                }
+                stopped = true;
+                resolveFn();
+            },
+        };
+    }
+    decodeBase64(data) {
+        try {
+            return Buffer.from(data, "base64");
+        }
+        catch {
+            return undefined;
+        }
+    }
+    isAsyncIterable(value) {
+        if (!value || typeof value !== "object") {
+            return false;
+        }
+        return typeof value[Symbol.asyncIterator] === "function";
+    }
+    isIterable(value) {
+        if (!value || typeof value !== "object") {
+            return false;
+        }
+        return typeof value[Symbol.iterator] === "function";
+    }
+    toAsyncIterable(value) {
+        if (this.isAsyncIterable(value)) {
+            return value;
+        }
+        return (async function* toAsync() {
+            for (const item of value) {
+                yield item;
+            }
+        })();
+    }
+    async pumpExecInput(stdin, readyPromise, stop, chunkMethod, eofMethod) {
+        const reqID = await Promise.race([
+            readyPromise,
+            stop.promise.then(() => undefined),
+        ]);
+        if (stop.isStopped() || reqID === undefined) {
+            return;
+        }
+        if (!stdin) {
+            await this.sendFireAndForget(eofMethod, { id: reqID }).catch(() => undefined);
+            return;
+        }
+        let shouldSendEOF = true;
+        try {
+            const chunks = this.isAsyncIterable(stdin) || this.isIterable(stdin)
+                ? this.toAsyncIterable(stdin)
+                : undefined;
+            if (!chunks) {
+                return;
+            }
+            const iterator = chunks[Symbol.asyncIterator]();
+            try {
+                for (;;) {
+                    const next = await this.nextAsyncItem(iterator, stop.promise);
+                    if (!next) {
+                        shouldSendEOF = false;
+                        return;
+                    }
+                    if (next.done) {
+                        return;
+                    }
+                    if (stop.isStopped()) {
+                        shouldSendEOF = false;
+                        return;
+                    }
+                    const chunk = next.value;
+                    let encoded = "";
+                    try {
+                        encoded = (0, utils_1.toBuffer)(chunk).toString("base64");
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (!encoded) {
+                        continue;
+                    }
+                    await this.sendFireAndForget(chunkMethod, {
+                        id: reqID,
+                        data: encoded,
+                    }).catch(() => undefined);
+                }
+            }
+            finally {
+                this.closeAsyncIterator(iterator);
+            }
+        }
+        finally {
+            if (shouldSendEOF && !stop.isStopped()) {
+                await this.sendFireAndForget(eofMethod, { id: reqID }).catch(() => undefined);
+            }
+        }
+    }
+    async pumpTTYResize(resize, readyPromise, stop) {
+        if (!resize) {
+            return;
+        }
+        const reqID = await Promise.race([
+            readyPromise,
+            stop.promise.then(() => undefined),
+        ]);
+        if (stop.isStopped() || reqID === undefined) {
+            return;
+        }
+        const sizes = this.toAsyncIterable(resize);
+        const iterator = sizes[Symbol.asyncIterator]();
+        try {
+            for (;;) {
+                const next = await this.nextAsyncItem(iterator, stop.promise);
+                if (!next || next.done || stop.isStopped()) {
+                    return;
+                }
+                const size = next.value;
+                if (!Array.isArray(size) || size.length < 2) {
+                    continue;
+                }
+                const rows = Math.trunc(Number(size[0]));
+                const cols = Math.trunc(Number(size[1]));
+                if (!Number.isFinite(rows) || !Number.isFinite(cols) || rows <= 0 || cols <= 0) {
+                    continue;
+                }
+                await this.sendFireAndForget("exec_tty.resize", {
+                    id: reqID,
+                    rows,
+                    cols,
+                }).catch(() => undefined);
+            }
+        }
+        finally {
+            this.closeAsyncIterator(iterator);
+        }
+    }
+    async nextAsyncItem(iterator, stopPromise) {
+        const nextPromise = iterator.next();
+        const result = await Promise.race([
+            nextPromise.then((next) => ({ kind: "next", next })),
+            stopPromise.then(() => ({ kind: "stopped" })),
+        ]);
+        if (result.kind === "stopped") {
+            void nextPromise.catch(() => undefined);
+            return undefined;
+        }
+        return result.next;
+    }
+    closeAsyncIterator(iterator) {
+        const close = iterator.return;
+        if (typeof close !== "function") {
+            return;
+        }
+        void Promise.resolve(close.call(iterator)).catch(() => undefined);
+    }
+    writeStreamChunk(writer, chunk) {
+        if (!writer) {
+            return;
+        }
+        if (typeof writer === "function") {
+            void writer(chunk);
+            return;
+        }
+        writer.write(chunk);
+    }
+}
+exports.ExecAPI = ExecAPI;

package/dist/client/network-hooks.d.ts

@@ -0,0 +1,20 @@
+import { type NetworkInterceptionConfig } from "../types";
+import type { CompiledNetworkHook, WireNetworkInterceptionConfig } from "./wire";
+export declare class NetworkHooks {
+    private networkHooks;
+    private networkHookServer;
+    private networkHookSocketPath;
+    private networkHookTempDir;
+    compile(cfg: NetworkInterceptionConfig | undefined): [
+        WireNetworkInterceptionConfig | undefined,
+        Map<string, CompiledNetworkHook>
+    ];
+    start(hooks: Map<string, CompiledNetworkHook>): Promise<string>;
+    stop(): Promise<void>;
+    private serveNetworkHookSocket;
+    private handleNetworkHookSocketLine;
+    private invokeNetworkHook;
+    private networkHookResultToWire;
+    private toStringMap;
+    private toStringSliceMap;
+}