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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { DockerSandbox, type DockerSandboxOptions, type DockerTemplateSpec } from './sandbox/index.js';
+export { DockerSandbox, type DockerSandboxOptions, type DockerSandboxStartOptions, type DockerTemplateSpec, } from './sandbox/index.js';
 export { DockerProcessManager } from './sandbox/process-manager.js';
 export { dockerSandboxProvider } from './provider.js';
 export * from './template/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -7,6 +7,38 @@ import { createHash, randomUUID } from "crypto";
 import posixPath from "path/posix";
 import { Server, ServerCredentials } from "@grpc/grpc-js";
 import { execFile } from "child_process";
+//#region src/abort.ts
+function createAbortError(signal, operation) {
+	return new SandboxAbortError(operation, signal.reason);
+}
+function throwIfAborted(signal, operation) {
+	if (signal?.aborted) throw createAbortError(signal, operation);
+}
+function isAbortError(error) {
+	return error instanceof SandboxAbortError || error instanceof Error && (error.name === "AbortError" || "code" in error && error.code === "ABORT_ERR");
+}
+function normalizeAbortError(error, operation) {
+	return error instanceof SandboxAbortError ? error : isAbortError(error) ? new SandboxAbortError(operation, error) : error;
+}
+function waitForAbortable(promise, signal, operation, onAbort) {
+	throwIfAborted(signal, operation);
+	if (!signal) return promise;
+	return new Promise((resolve, reject) => {
+		const abort = () => {
+			onAbort?.();
+			reject(new SandboxAbortError(operation, signal.reason));
+		};
+		signal.addEventListener("abort", abort, { once: true });
+		promise.then((value) => {
+			signal.removeEventListener("abort", abort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", abort);
+			reject(normalizeAbortError(error, operation));
+		});
+	});
+}
+//#endregion
 //#region src/sandbox/process-manager.ts
 /**
 * Docker Process Manager
@@ -179,16 +211,20 @@ var DockerProcessHandle = class extends ProcessHandle {
 				AttachStdout: false,
 				AttachStderr: false
 			});
-			await killExec.start({});
-			let killInfo = await killExec.inspect();
-			while (killInfo.Running) {
-				await new Promise((resolve) => setTimeout(resolve, 10));
-				killInfo = await killExec.inspect();
+			const killStream = await killExec.start({});
+			try {
+				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;
+			} finally {
+				killStream.destroy();
 			}
-			if (killInfo.ExitCode !== 0) throw new Error(`kill helper exited with code ${killInfo.ExitCode}`);
-			this._killed = true;
-			this._destroyStream();
-			return true;
 		} catch (error) {
 			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);
@@ -245,6 +281,7 @@ var DockerProcessManager = class extends SandboxProcessManager {
 		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 attachStdin = options.stdinMode !== "ignore";
 		const exec = await container.exec({
 			Cmd: [
 				"sh",
@@ -256,17 +293,17 @@ var DockerProcessManager = class extends SandboxProcessManager {
 			],
 			AttachStdout: true,
 			AttachStderr: true,
-			AttachStdin: true,
+			AttachStdin: attachStdin,
 			Tty: false,
 			Env: envArray.length > 0 ? envArray : void 0,
 			WorkingDir: options.cwd
 		});
 		const stream = await exec.start({
 			hijack: true,
-			stdin: true
+			stdin: attachStdin
 		});
 		const startTime = Date.now();
-		const handle = new DockerProcessHandle(exec, container, startTime, stream, pgidFile, options);
+		const handle = new DockerProcessHandle(exec, container, startTime, attachStdin ? stream : null, pgidFile, options);
 		handle._setExecStream(stream);
 		const waitPromise = new Promise((resolve) => {
 			const buffer = [];
@@ -539,7 +576,9 @@ var DockerSandbox = class DockerSandbox extends MastraSandbox {
 		if (!this._container) throw new SandboxNotReadyError(this.id);
 		return this._container;
 	}
-	async start() {
+	async start(options = {}) {
+		const { abortSignal } = options;
+		throwIfAborted(abortSignal, "start Docker sandbox");
 		this.logger.debug(`${LOG_PREFIX} Starting sandbox ${this.id}...`);
 		const existing = await this._findExistingContainer();
 		if (existing) {
@@ -560,7 +599,7 @@ var DockerSandbox = class DockerSandbox extends MastraSandbox {
 			return;
 		}
 		this._warnOnPrivilegedHardeningConflict(this._privileged);
-		await this._resolveTemplate();
+		await this._resolveTemplate(abortSignal);
 		await this._ensureImage();
 		const envArray = Object.entries(this._env).map(([k, v]) => `${k}=${v}`);
 		const binds = Object.entries(this._volumes).map(([host, container]) => `${host}:${container}`);
@@ -820,10 +859,20 @@ var DockerSandbox = class DockerSandbox extends MastraSandbox {
 	* creates a container, so a resolver-form template re-resolves each time.
 	* Adopts the template's workdir unless the sandbox was given one explicitly.
 	*/
-	async _resolveTemplate() {
+	async _resolveTemplate(abortSignal) {
 		if (!this._templateSpec) return;
-		const template = typeof this._templateSpec === "function" ? await this._templateSpec() : this._templateSpec;
-		const result = await template.build({ docker: this._docker });
+		throwIfAborted(abortSignal, "start Docker sandbox");
+		let template;
+		try {
+			template = typeof this._templateSpec === "function" ? await this._templateSpec({ abortSignal }) : this._templateSpec;
+		} catch (error) {
+			throw normalizeAbortError(error, "start Docker sandbox");
+		}
+		throwIfAborted(abortSignal, "start Docker sandbox");
+		const result = await template.build({
+			docker: this._docker,
+			abortSignal
+		});
 		if (result.status !== "ready") throw new SandboxError(`Docker template build failed: ${result.error ?? "unknown error"}`, "START_FAILED", {
 			templateId: result.templateId,
 			reason: "template_build_failed"
@@ -1196,9 +1245,17 @@ const AUTH_CREDENTIALS_METHOD = "/moby.filesync.v1.Auth/Credentials";
 * Open a session that answers `GetSecret` from `secrets`. The returned id must
 * be sent as the `session` query parameter of the build request.
 */
-function openBuildSession(docker, secrets) {
+function openBuildSession(docker, secrets, abortSignal) {
+	throwIfAborted(abortSignal, "build Docker template");
 	const id = randomUUID();
 	return new Promise((resolve, reject) => {
+		let settled = false;
+		const abort = () => {
+			if (settled || !abortSignal) return;
+			settled = true;
+			reject(createAbortError(abortSignal, "build Docker template"));
+		};
+		abortSignal?.addEventListener("abort", abort, { once: true });
 		docker.modem.dial({
 			method: "POST",
 			path: "/session",
@@ -1214,8 +1271,14 @@ function openBuildSession(docker, secrets) {
 				500: "server error"
 			}
 		}, (err, socket) => {
+			if (settled) {
+				socket?.end?.();
+				return;
+			}
+			settled = true;
+			abortSignal?.removeEventListener("abort", abort);
 			if (err) {
-				reject(err);
+				reject(abortSignal?.aborted ? createAbortError(abortSignal, "build Docker template") : err);
 				return;
 			}
 			const server = new Server();
@@ -1536,7 +1599,8 @@ var DockerTemplate = class DockerTemplate {
 	#secrets;
 	#docker;
 	#built = false;
-	#inFlight;
+	#queueTail;
+	#plainBuild;
 	constructor(options = {}, state) {
 		this.#baseImage = state ? state.baseImage : validateString(options.baseImage ?? "node:22-slim", "baseImage");
 		this.#operations = state?.operations ?? [];
@@ -1683,19 +1747,49 @@ var DockerTemplate = class DockerTemplate {
 	* `options.secrets`, the template's `secrets` option, or `process.env`.
 	*/
 	async build(options = {}) {
-		if (!options.force && options.secrets === void 0 && options.docker === void 0 && this.#inFlight) return this.#inFlight;
-		const run = (this.#inFlight?.catch(() => void 0) ?? Promise.resolve()).then(() => this.#build(options));
-		this.#inFlight = run;
-		run.finally(() => {
-			if (this.#inFlight === run) this.#inFlight = void 0;
+		throwIfAborted(options.abortSignal, "build Docker template");
+		const isPlain = !options.force && options.secrets === void 0 && options.docker === void 0;
+		if (isPlain && this.#plainBuild) return this.#waitForBuild(this.#plainBuild, options.abortSignal);
+		const previous = this.#queueTail?.promise.catch(() => void 0) ?? Promise.resolve();
+		const controller = new AbortController();
+		const run = {
+			controller,
+			waiters: 0,
+			promise: previous.then(() => {
+				throwIfAborted(controller.signal, "build Docker template");
+				return this.#build({
+					...options,
+					abortSignal: controller.signal
+				});
+			})
+		};
+		this.#queueTail = run;
+		if (isPlain) this.#plainBuild = run;
+		run.promise.finally(() => {
+			if (this.#queueTail === run) this.#queueTail = void 0;
+			if (this.#plainBuild === run) this.#plainBuild = void 0;
 		}).catch(() => void 0);
-		return run;
+		return this.#waitForBuild(run, options.abortSignal);
+	}
+	#waitForBuild(run, abortSignal) {
+		run.waiters += 1;
+		let settled = false;
+		const release = (aborted) => {
+			if (settled) return;
+			settled = true;
+			run.waiters -= 1;
+			if (aborted && run.waiters === 0) run.controller.abort();
+		};
+		return waitForAbortable(run.promise, abortSignal, "build Docker template", () => release(true)).finally(() => release(false));
 	}
 	async #build(options) {
 		const docker = options.docker ?? this.#getDocker();
 		const tag = this.templateId;
+		const { abortSignal } = options;
+		throwIfAborted(abortSignal, "build Docker template");
 		if (!options.force) try {
 			await docker.getImage(tag).inspect();
+			throwIfAborted(abortSignal, "build Docker template");
 			this.#built = true;
 			return {
 				status: "ready",
@@ -1705,24 +1799,37 @@ var DockerTemplate = class DockerTemplate {
 			if (!isImageNotFoundError(error)) throw error;
 		}
 		const secrets = await this.#resolveSecrets(options.secrets);
+		throwIfAborted(abortSignal, "build Docker template");
 		const context = pack();
 		context.entry({ name: "Dockerfile" }, this.dockerfile);
 		context.finalize();
 		try {
 			const nocache = options.force === true;
 			if (secrets) {
-				const { stream, session } = await this.#buildWithSecrets(docker, context, tag, secrets, nocache);
+				const { stream, session } = await this.#buildWithSecrets(docker, context, tag, secrets, nocache, abortSignal);
 				try {
-					await this.#followBuild(docker, stream);
+					await this.#followBuild(docker, stream, abortSignal);
 				} finally {
 					session.close();
 				}
-			} else await this.#followBuild(docker, await docker.buildImage(context, {
-				t: tag,
-				nocache
-			}));
+			} else {
+				const stream = await waitForAbortable(docker.buildImage(context, {
+					t: tag,
+					nocache
+				}).then((stream) => {
+					if (abortSignal?.aborted) {
+						stream.destroy?.();
+						throw createAbortError(abortSignal, "build Docker template");
+					}
+					return stream;
+				}), abortSignal, "build Docker template", () => {
+					context.destroy?.();
+				});
+				await this.#followBuild(docker, stream, abortSignal);
+			}
 		} catch (error) {
 			this.#built = false;
+			if (abortSignal?.aborted) throw normalizeAbortError(error, "build Docker template");
 			return {
 				status: "failed",
 				templateId: tag,
@@ -1753,12 +1860,35 @@ var DockerTemplate = class DockerTemplate {
 	* directly because `docker.buildImage` replaces any session id with its own
 	* auth-only session when `version` is `'2'`.
 	*/
-	async #buildWithSecrets(docker, context, tag, secrets, nocache) {
-		const session = await openBuildSession(docker, secrets);
+	async #buildWithSecrets(docker, context, tag, secrets, nocache, abortSignal) {
+		throwIfAborted(abortSignal, "build Docker template");
+		const session = await openBuildSession(docker, secrets, abortSignal);
 		let stream;
 		try {
 			stream = await new Promise((resolve, reject) => {
-				docker.modem.dial({
+				let settled = false;
+				let request;
+				const finish = (error, data) => {
+					if (settled) {
+						if (data) data.destroy?.();
+						return;
+					}
+					settled = true;
+					abortSignal?.removeEventListener("abort", abort);
+					error === void 0 ? resolve(data) : reject(error);
+				};
+				const abort = () => {
+					context.destroy?.();
+					request?.destroy?.();
+					session.close();
+					if (abortSignal) finish(createAbortError(abortSignal, "build Docker template"));
+				};
+				abortSignal?.addEventListener("abort", abort, { once: true });
+				if (abortSignal?.aborted) {
+					abort();
+					return;
+				}
+				request = docker.modem.dial({
 					path: "/build?",
 					method: "POST",
 					file: context,
@@ -1773,7 +1903,7 @@ var DockerTemplate = class DockerTemplate {
 						200: true,
 						500: "server error"
 					}
-				}, (err, data) => err ? reject(err) : resolve(data));
+				}, (err, data) => finish(err ?? void 0, data));
 			});
 		} catch (error) {
 			session.close();
@@ -1784,20 +1914,36 @@ var DockerTemplate = class DockerTemplate {
 			session
 		};
 	}
-	#followBuild(docker, stream) {
+	#followBuild(docker, stream, abortSignal) {
 		return new Promise((resolve, reject) => {
+			let settled = false;
+			const finish = (error) => {
+				if (settled) return;
+				settled = true;
+				abortSignal?.removeEventListener("abort", abort);
+				error === void 0 ? resolve() : reject(error);
+			};
+			const abort = () => {
+				stream.destroy?.();
+				if (abortSignal) finish(createAbortError(abortSignal, "build Docker template"));
+			};
+			abortSignal?.addEventListener("abort", abort, { once: true });
+			if (abortSignal?.aborted) {
+				abort();
+				return;
+			}
 			docker.modem.followProgress(stream, (err, output) => {
 				if (err) {
-					reject(err);
+					finish(err);
 					return;
 				}
 				const failure = output?.find((entry) => entry && (entry.error !== void 0 || entry.errorDetail !== void 0));
 				if (failure) {
 					const detail = failure.errorDetail;
-					reject(new Error(String(detail?.message ?? failure.error ?? "docker build failed")));
+					finish(new Error(String(detail?.message ?? failure.error ?? "docker build failed")));
 					return;
 				}
-				resolve();
+				finish();
 			});
 		});
 	}
@@ -1946,16 +2092,31 @@ function createDockerRepoTemplate(options) {
 	if (options.ref !== void 0 && !REF_PATTERN.test(options.ref)) throw new Error(`Invalid ref '${options.ref}': expected a git ref name`);
 	const workingDirectory = trimTrailingSlashes(options.workingDirectory ?? DEFAULT_WORKING_DIRECTORY);
 	if (!workingDirectory.startsWith("/")) throw new Error(`workingDirectory must be an absolute path, got '${options.workingDirectory}'`);
-	return () => resolveRepoTemplate(options, workingDirectory);
+	return (resolveOptions) => resolveRepoTemplate(options, workingDirectory, resolveOptions);
 }
-async function resolveRepoTemplate(options, workingDirectory) {
-	const access = await options.getRepositoryAccess();
+async function resolveRepoTemplate(options, workingDirectory, resolveOptions = {}) {
+	const { abortSignal } = resolveOptions;
+	throwIfAborted(abortSignal, "resolve Docker repository template");
+	let access;
+	try {
+		access = await options.getRepositoryAccess(resolveOptions);
+	} catch (error) {
+		throw normalizeAbortError(error, "resolve Docker repository template");
+	}
+	throwIfAborted(abortSignal, "resolve Docker repository template");
 	const cloneUrl = access?.cloneUrl;
 	if (!cloneUrl) throw new Error("Repo template has no clone URL: repository access returned none.");
 	assertCloneUrl(cloneUrl);
 	const token = access?.authorization?.token;
-	const buildEnv = typeof options.buildEnv === "function" ? await options.buildEnv() : options.buildEnv;
-	const sha = await resolveHead(cloneUrl, options.ref, token);
+	let buildEnv;
+	try {
+		buildEnv = typeof options.buildEnv === "function" ? await options.buildEnv(resolveOptions) : options.buildEnv;
+	} catch (error) {
+		throw normalizeAbortError(error, "resolve Docker repository template");
+	}
+	throwIfAborted(abortSignal, "resolve Docker repository template");
+	const sha = await resolveHead(cloneUrl, options.ref, token, abortSignal);
+	throwIfAborted(abortSignal, "resolve Docker repository template");
 	if (!sha) throw new Error(`Could not resolve ${options.ref ?? "HEAD"} of ${cloneUrl} with git ls-remote; check the ref, the credential and network access`);
 	return buildRepoTemplate({
 		cloneUrl,
@@ -2004,7 +2165,8 @@ function buildRepoTemplate(inputs) {
 * yields undefined; the caller decides how to surface it.
 * @internal exported for tests.
 */
-async function resolveHead(cloneUrl, ref, token) {
+async function resolveHead(cloneUrl, ref, token, abortSignal) {
+	throwIfAborted(abortSignal, "resolve Docker repository template");
 	if (ref && FULL_SHA_PATTERN.test(ref)) return ref.toLowerCase();
 	try {
 		const authEnv = token ? {
@@ -2019,6 +2181,7 @@ async function resolveHead(cloneUrl, ref, token) {
 			ref ?? "HEAD"
 		], {
 			timeout: 1e4,
+			signal: abortSignal,
 			env: {
 				...process.env,
 				...authEnv,
@@ -2028,7 +2191,8 @@ async function resolveHead(cloneUrl, ref, token) {
 		const lines = stdout.split("\n").filter(Boolean).map((line) => line.split("	"));
 		const sha = (lines.find(([, name]) => name?.endsWith("^{}")) ?? lines[0])?.[0]?.trim();
 		return sha && SHA_PATTERN.test(sha) ? sha.toLowerCase() : void 0;
-	} catch {
+	} catch (error) {
+		if (abortSignal?.aborted) throw normalizeAbortError(error, "resolve Docker repository template");
 		return;
 	}
 }