@mastra/docker 0.8.0-alpha.0 → 0.8.0-alpha.2

package/dist/index.js

@@ -1,10 +1,111 @@
 import { posix } from "path";
 import { isDeepStrictEqual } from "util";
-import { MastraSandbox, ProcessHandle, SandboxError, SandboxNotReadyError, SandboxProcessManager } from "@mastra/core/workspace";
+import { MastraSandbox, ProcessHandle, SandboxAbortError, SandboxError, SandboxNotReadyError, SandboxProcessManager, validateSandboxFileMode } from "@mastra/core/workspace";
 import Docker from "dockerode";
 import { pack } from "tar-stream";
+import { randomUUID } from "crypto";
 //#region src/sandbox/process-manager.ts
 /**
+* Docker Process Manager
+*
+* Implements SandboxProcessManager for Docker containers.
+* Uses `container.exec()` to run commands inside a long-lived container.
+* Each spawned process gets a dedicated exec instance with separate
+* stdout/stderr streams.
+*/
+/**
+* Directory (inside the container) where each spawned process records the PGID
+* of its process group. Created with mode 700 so only the (root) exec user can
+* write the PGID files.
+*/
+const PROC_DIR = "/tmp/.mastra-proc";
+/**
+* Wrapper (run as the exec command) that places the user command in its own
+* process group and records the group's PGID so kill() can signal the whole
+* group later.
+*
+* Docker's exec-inspect `Pid` is a host/daemon-namespace PID and cannot be used
+* with an in-container `kill`, so we need a container-namespace identity. We use
+* a *kernel-enforced* process group as that identity:
+*
+*   1. `setsid -w` re-execs the command as a new session/process-group leader,
+*      so its PID == PGID. Every descendant inherits that PGID (unless it calls
+*      `setsid` itself) and stays reachable even if it re-parents to PID 1.
+*      `-w` keeps the wrapper (and thus the exec) alive for the whole lifetime
+*      and propagates the child's exit status — without it `setsid` forks and
+*      returns immediately, so the exec would appear to finish while the real
+*      work keeps running.
+*   2. The leader writes its own PID (`$$`) — the PGID — to a private file that
+*      only this process wrote, so the identity is kernel-owned and cannot be
+*      forged by another container process.
+*
+* If `setsid -w` is unavailable in the image (e.g. BusyBox), we degrade
+* gracefully: the command runs directly and we record its PID so kill() can
+* still signal it (descendant coverage is then best-effort). The probe
+* `setsid -w true` also covers images without setsid at all.
+*
+* Positional args: $1 = pgid file path, $2 = user command. The script text is a
+* static constant; runtime values travel only as argv, never interpolated into
+* the command string.
+*/
+const SPAWN_WRAPPER = `
+umask 077
+d="\${1%/*}"
+mkdir -p "$d" 2>/dev/null
+chmod 700 "$d" 2>/dev/null
+if setsid -w true >/dev/null 2>&1; then
+  exec setsid -w sh -c 'echo $$ > "$1" || exit 126; sh -c "$2"; ret=$?; rm -f "$1" 2>/dev/null; exit $ret' sh "$1" "$2"
+fi
+echo $$ > "$1" || exit 126
+sh -c "$2"
+ret=$?
+rm -f "$1" 2>/dev/null
+exit $ret
+`;
+/**
+* Kill script: read the recorded PGID and SIGKILL the whole process group.
+* A negative PID targets the kernel-owned process group, so descendants that
+* re-parented to PID 1 are still caught. We SIGSTOP the
+* group first to freeze fork races, then SIGKILL. The file may not exist yet if
+* kill races the leader's first write, so we briefly wait for it.
+*
+* Positional arg: $1 = pgid file path (static script; no interpolation).
+*/
+const KILL_SCRIPT = `
+f="$1"
+i=0
+while [ ! -r "$f" ] && [ "$i" -lt 40 ]; do sleep 0.05; i=$((i + 1)); done
+# If the PGID was never recorded (file absent/unreadable after the wait, or
+# empty), we have no group to signal or verify — report failure rather than
+# falsely claiming the tree was terminated.
+[ -r "$f" ] || exit 1
+pgid=$(cat "$f" 2>/dev/null)
+rm -f "$f" 2>/dev/null
+[ -n "$pgid" ] || exit 1
+kill -STOP -"$pgid" 2>/dev/null
+kill -KILL -"$pgid" 2>/dev/null
+# Fallback for images without setsid: the leader is not a group leader, so also
+# signal it directly.
+kill -KILL "$pgid" 2>/dev/null
+# Verify the group is actually gone before reporting success. kill -0 probes
+# for the group's existence without sending a signal, and we poll while it
+# still reports the group alive. When the probe finally fails we must inspect
+# why: ESRCH ("no such process") means every member was reaped, so report
+# success; EPERM or any other error means termination is unconfirmed (e.g. a
+# member dropped privileges and became unsignalable), so exit nonzero and let
+# kill() report failure instead of falsely claiming the tree was terminated.
+j=0
+while err=$(kill -0 -"$pgid" 2>&1); do
+  j=$((j + 1))
+  [ "$j" -ge 40 ] && exit 1
+  sleep 0.05
+done
+case "$err" in
+  *[Ss]uch\\ process*) exit 0 ;;
+  *) exit 1 ;;
+esac
+`;
+/**
 * Wraps a Docker exec instance to conform to Mastra's ProcessHandle.
 * Not exported — internal to this module.
 *
@@ -24,13 +125,16 @@ var DockerProcessHandle = class extends ProcessHandle {
 	_waitPromise = null;
 	_stdinStream = null;
 	_execStream = null;
-	constructor(exec, container, startTime, stdinStream, options) {
+	/** @internal Container path of the file holding this process group's PGID. */
+	_pgidFile;
+	constructor(exec, container, startTime, stdinStream, pgidFile, options) {
 		super(options);
 		this.pid = exec.id;
 		this._exec = exec;
 		this._container = container;
 		this._startTime = startTime;
 		this._stdinStream = stdinStream;
+		this._pgidFile = pgidFile;
 	}
 	get exitCode() {
 		return this._exitCode;
@@ -61,37 +165,28 @@ var DockerProcessHandle = class extends ProcessHandle {
 	async kill() {
 		if (this._exitCode !== void 0) return false;
 		try {
-			let info = await this._inspectExec();
-			if (!info.Running || !info.Pid) {
-				await new Promise((r) => setTimeout(r, 50));
-				info = await this._inspectExec();
-			}
-			if (!info.Running) {
-				this._killed = true;
-				this._destroyStream();
-				return false;
-			}
-			const pid = info.Pid;
-			if (!pid) {
-				this._killed = true;
-				this._destroyStream();
-				return false;
-			}
-			await (await this._container.exec({
+			const killExec = await this._container.exec({
 				Cmd: [
 					"sh",
 					"-c",
-					`kill -9 -${pid} 2>/dev/null || kill -9 ${pid}`
+					KILL_SCRIPT,
+					"sh",
+					this._pgidFile
 				],
 				AttachStdout: false,
 				AttachStderr: false
-			})).start({});
+			});
+			await killExec.start({});
+			let killInfo = await killExec.inspect();
+			while (killInfo.Running) {
+				await new Promise((resolve) => setTimeout(resolve, 10));
+				killInfo = await killExec.inspect();
+			}
+			if (killInfo.ExitCode !== 0) throw new Error(`kill helper exited with code ${killInfo.ExitCode}`);
 			this._killed = true;
 			this._destroyStream();
 			return true;
 		} catch (error) {
-			this._killed = true;
-			this._destroyStream();
 			const msg = error instanceof Error ? error.message.toLowerCase() : "";
 			if (!msg.includes("no such process") && !msg.includes("esrch")) console.warn(`[DockerProcessManager] kill(${this.pid}) failed unexpectedly:`, error);
 			return false;
@@ -145,11 +240,15 @@ var DockerProcessManager = class extends SandboxProcessManager {
 	}
 	async spawn(command, options = {}) {
 		const container = this.container;
+		const pgidFile = `${PROC_DIR}/${randomUUID()}`;
 		const envArray = Object.entries({ ...options.env }).filter((entry) => entry[1] !== void 0).map(([k, v]) => `${k}=${v}`);
 		const exec = await container.exec({
 			Cmd: [
 				"sh",
 				"-c",
+				SPAWN_WRAPPER,
+				"sh",
+				pgidFile,
 				command
 			],
 			AttachStdout: true,
@@ -164,7 +263,7 @@ var DockerProcessManager = class extends SandboxProcessManager {
 			stdin: true
 		});
 		const startTime = Date.now();
-		const handle = new DockerProcessHandle(exec, container, startTime, stream, options);
+		const handle = new DockerProcessHandle(exec, container, startTime, stream, pgidFile, options);
 		handle._setExecStream(stream);
 		const waitPromise = new Promise((resolve) => {
 			const buffer = [];
@@ -240,8 +339,15 @@ var DockerProcessManager = class extends SandboxProcessManager {
 				if (handle.exitCode === void 0) {
 					handle._killed = true;
 					handle._timedOut = true;
-					handle.kill().catch(() => {});
-					handle._destroyStream();
+					const forceClose = () => {
+						if (handle.exitCode === void 0) {
+							handle._killed = true;
+							handle._destroyStream();
+						}
+					};
+					handle.kill().then((killed) => {
+						if (!killed) forceClose();
+					}).catch(forceClose);
 				}
 			}, resolvedTimeout);
 			waitPromise.then(() => clearTimeout(timer));
@@ -334,12 +440,14 @@ var DockerSandbox = class DockerSandbox extends MastraSandbox {
 	_cpuQuota;
 	_cpuPeriod;
 	_pidsLimit;
+	_init;
 	_readonlyRootfs;
 	_capDrop;
 	_capAdd;
 	_securityOpt;
 	_ulimits;
 	_tmpfs;
+	_mounts;
 	_labels;
 	_instructionsOverride;
 	_constructorOptions;
@@ -373,12 +481,14 @@ var DockerSandbox = class DockerSandbox extends MastraSandbox {
 		this._cpuQuota = options.cpuQuota;
 		this._cpuPeriod = options.cpuPeriod;
 		this._pidsLimit = options.pidsLimit;
+		this._init = options.init ?? true;
 		this._readonlyRootfs = options.readonlyRootfs;
 		this._capDrop = options.capDrop;
 		this._capAdd = options.capAdd;
 		this._securityOpt = options.securityOpt;
 		this._ulimits = options.ulimits;
 		this._tmpfs = options.tmpfs;
+		this._mounts = options.mounts;
 		this.setWorkingDirectory(options.workingDirectory ?? options.workingDir ?? "/workspace");
 		this._labels = {
 			...options.labels,
@@ -460,12 +570,14 @@ var DockerSandbox = class DockerSandbox extends MastraSandbox {
 				CpuQuota: this._cpuQuota,
 				CpuPeriod: this._cpuPeriod,
 				PidsLimit: this._pidsLimit,
+				Init: this._init,
 				ReadonlyRootfs: this._readonlyRootfs,
 				CapDrop: this._capDrop,
 				CapAdd: this._capAdd,
 				SecurityOpt: this._securityOpt,
 				Ulimits: this._ulimits?.map(toDockerUlimit),
-				Tmpfs: this._tmpfs
+				Tmpfs: this._tmpfs,
+				Mounts: this._mounts?.map(toDockerMount)
 			},
 			OpenStdin: true,
 			Tty: false
@@ -519,7 +631,8 @@ var DockerSandbox = class DockerSandbox extends MastraSandbox {
 			["CapAdd", this._capAdd],
 			["SecurityOpt", this._securityOpt],
 			["Ulimits", this._ulimits],
-			["Tmpfs", this._tmpfs]
+			["Tmpfs", this._tmpfs],
+			["Mounts", this._mounts?.map(toDockerMount)]
 		];
 		if (this._privilegedWasSet || hostConfig?.Privileged === true) entries.unshift(["Privileged", this._privileged]);
 		return entries.filter((entry) => isPresentHostConfigValue(entry[1]));
@@ -565,32 +678,60 @@ var DockerSandbox = class DockerSandbox extends MastraSandbox {
 	* - Existing destinations are overwritten (contents and mode).
 	* - Exact bytes are preserved for both `string` and `Buffer` content,
 	*   including empty files and binary data.
-	* - New files are created with mode `0644`; directories created implicitly
-	*   default to Docker's `0755`. Overwriting a file replaces its mode with `0644`.
+	* - New files use the per-file `mode` when provided (validated integer
+	*   `0o001`–`0o777`), otherwise `0644`; directories created implicitly default
+	*   to Docker's `0755`. Overwriting a file replaces its mode with the
+	*   requested `mode` (or `0644` when omitted).
 	* - Not atomic across files: on failure the promise rejects and earlier or
 	*   partially written files may remain.
 	*
+	* Cancellation (`options.abortSignal`):
+	* - If the signal is already aborted, rejects with {@link SandboxAbortError}
+	*   before creating the archive or starting the upload.
+	* - If the signal aborts during transfer, the underlying `putArchive` request
+	*   is terminated by destroying the tar stream (which ends the request body),
+	*   and the promise rejects with {@link SandboxAbortError}.
+	* - Upload and cancellation race: an upload that completes before the abort is
+	*   observed resolves normally.
+	* - No rollback: files Docker already received or extracted may remain. The
+	*   daemon may continue extraction after rejection, so the caller is
+	*   responsible for any cleanup or sandbox disposal.
+	* - Behavior is unchanged when no signal is supplied.
+	*
 	* @throws {SandboxNotReadyError} If the sandbox has not been started.
+	* @throws {SandboxAbortError} If the write is cancelled via `options.abortSignal`.
 	* @throws {SandboxError} If the archive upload fails.
 	*/
-	async writeFiles(files) {
+	async writeFiles(files, options) {
 		const container = this.container;
+		const signal = options?.abortSignal;
+		if (signal?.aborted) throw new SandboxAbortError("writeFiles");
 		if (files.length === 0) return;
 		const pack$1 = pack();
 		for (const file of files) {
+			if (file.mode !== void 0) validateSandboxFileMode(file.mode);
 			const resolved = posix.isAbsolute(file.path) ? posix.normalize(file.path) : posix.resolve(this.workingDirectory, file.path);
 			const data = Buffer.isBuffer(file.content) ? file.content : Buffer.from(file.content);
+			const mode = file.mode ?? 420;
 			pack$1.entry({
 				name: resolved.replace(/^\/+/, ""),
 				size: data.length,
-				mode: 420
+				mode
 			}, data);
 		}
 		pack$1.finalize();
+		const onAbort = () => pack$1.destroy();
+		if (signal) signal.addEventListener("abort", onAbort, { once: true });
 		try {
-			await container.putArchive(pack$1, { path: "/" });
+			await container.putArchive(pack$1, {
+				path: "/",
+				abortSignal: signal
+			});
 		} catch (error) {
+			if (signal?.aborted) throw new SandboxAbortError("writeFiles");
 			throw new SandboxError(`Failed to write files to sandbox: ${error instanceof Error ? error.message : String(error)}`, "EXECUTION_FAILED", { reason: "write_files_failed" });
+		} finally {
+			if (signal) signal.removeEventListener("abort", onAbort);
 		}
 	}
 	getInstructions(opts) {
@@ -767,6 +908,31 @@ function toDockerUlimit(ulimit) {
 		Hard: ulimit.hard
 	};
 }
+function toDockerMount(mount) {
+	const settings = {
+		Type: mount.type,
+		Target: mount.target,
+		Source: mount.type === "tmpfs" ? "" : mount.source
+	};
+	if (mount.readOnly !== void 0) settings.ReadOnly = mount.readOnly;
+	if (mount.type === "volume" && mount.volumeOptions) {
+		const { subpath, noCopy, labels } = mount.volumeOptions;
+		const volumeOptions = {};
+		if (subpath !== void 0) volumeOptions.Subpath = subpath;
+		if (noCopy !== void 0) volumeOptions.NoCopy = noCopy;
+		if (labels !== void 0) volumeOptions.Labels = labels;
+		if (Object.keys(volumeOptions).length > 0) settings.VolumeOptions = volumeOptions;
+	}
+	if (mount.type === "bind" && mount.bindOptions?.propagation !== void 0) settings.BindOptions = { Propagation: mount.bindOptions.propagation };
+	if (mount.type === "tmpfs" && mount.tmpfsOptions) {
+		const { sizeBytes, mode } = mount.tmpfsOptions;
+		const tmpfsOptions = {};
+		if (sizeBytes !== void 0) tmpfsOptions.SizeBytes = sizeBytes;
+		if (mode !== void 0) tmpfsOptions.Mode = mode;
+		if (Object.keys(tmpfsOptions).length > 0) settings.TmpfsOptions = tmpfsOptions;
+	}
+	return settings;
+}
 function toDockerSandboxOptionName(field) {
 	return {
 		Privileged: "privileged",
@@ -781,7 +947,8 @@ function toDockerSandboxOptionName(field) {
 		CapAdd: "capAdd",
 		SecurityOpt: "securityOpt",
 		Ulimits: "ulimits",
-		Tmpfs: "tmpfs"
+		Tmpfs: "tmpfs",
+		Mounts: "mounts"
 	}[field] ?? String(field);
 }
 //#endregion
@@ -892,6 +1059,87 @@ const dockerSandboxProvider = {
 				type: "object",
 				description: "tmpfs mount paths with options",
 				additionalProperties: { type: "string" }
+			},
+			mounts: {
+				type: "array",
+				description: "Mounts mapped 1:1 onto Docker HostConfig.Mounts (supports volume subpath)",
+				items: { oneOf: [
+					{
+						type: "object",
+						required: [
+							"type",
+							"target",
+							"source"
+						],
+						additionalProperties: false,
+						properties: {
+							type: { const: "volume" },
+							target: { type: "string" },
+							source: { type: "string" },
+							readOnly: { type: "boolean" },
+							volumeOptions: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									subpath: { type: "string" },
+									noCopy: { type: "boolean" },
+									labels: {
+										type: "object",
+										additionalProperties: { type: "string" }
+									}
+								}
+							}
+						}
+					},
+					{
+						type: "object",
+						required: [
+							"type",
+							"target",
+							"source"
+						],
+						additionalProperties: false,
+						properties: {
+							type: { const: "bind" },
+							target: { type: "string" },
+							source: { type: "string" },
+							readOnly: { type: "boolean" },
+							bindOptions: {
+								type: "object",
+								additionalProperties: false,
+								properties: { propagation: {
+									type: "string",
+									enum: [
+										"private",
+										"rprivate",
+										"shared",
+										"rshared",
+										"slave",
+										"rslave"
+									]
+								} }
+							}
+						}
+					},
+					{
+						type: "object",
+						required: ["type", "target"],
+						additionalProperties: false,
+						properties: {
+							type: { const: "tmpfs" },
+							target: { type: "string" },
+							readOnly: { type: "boolean" },
+							tmpfsOptions: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									sizeBytes: { type: "number" },
+									mode: { type: "number" }
+								}
+							}
+						}
+					}
+				] }
 			}
 		}
 	},