@mastra/docker 0.9.0-alpha.1 → 0.9.0

package/README.md

@@ -91,6 +91,11 @@ const b = new DockerSandbox({ template });
 const result = await template.build();
 if (result.status !== 'ready') throw new Error(result.error);
 
+// Cancel repository resolution or template preparation when needed.
+const controller = new AbortController();
+await a.start({ abortSignal: controller.signal });
+// Explicit builds accept the same option: template.build({ abortSignal: controller.signal }).
+
 // Remove the built image when done (independent of any sandbox's destroy()).
 await template.dispose();
 ```
@@ -105,6 +110,9 @@ template, and their signatures match the E2B and platform template builders.
 The image tag is content-addressed (`mastra-template:<hash>`), so `build()` is
 idempotent and reuses an existing image unless you pass `{ force: true }`,
 which also bypasses the daemon's layer cache so every step really re-runs.
+Concurrent callers share preparation work, but each caller can cancel its own
+wait independently; the underlying build is cancelled only after its last
+active caller aborts.
 
 Never put secrets in `setEnvs` — they are baked into the image. For a step that
 needs a credential, use `runWithSecrets`: the command runs in a throwaway build

package/dist/abort.d.ts

@@ -0,0 +1,7 @@
+import { SandboxAbortError } from '@mastra/core/workspace';
+export declare function createAbortError(signal: AbortSignal, operation: string): SandboxAbortError;
+export declare function throwIfAborted(signal: AbortSignal | undefined, operation: string): void;
+export declare function isAbortError(error: unknown): boolean;
+export declare function normalizeAbortError(error: unknown, operation: string): unknown;
+export declare function waitForAbortable<T>(promise: Promise<T>, signal: AbortSignal | undefined, operation: string, onAbort?: () => void): Promise<T>;
+//# sourceMappingURL=abort.d.ts.map

package/dist/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,iBAAiB,CAE1F;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAEvF;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKpD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAM9E;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,IAAI,GACnB,OAAO,CAAC,CAAC,CAAC,CAqBZ"}

package/dist/index.cjs

@@ -32,6 +32,38 @@ let path_posix = require("path/posix");
 path_posix = __toESM(path_posix, 1);
 let _grpc_grpc_js = require("@grpc/grpc-js");
 let child_process = require("child_process");
+//#region src/abort.ts
+function createAbortError(signal, operation) {
+	return new _mastra_core_workspace.SandboxAbortError(operation, signal.reason);
+}
+function throwIfAborted(signal, operation) {
+	if (signal?.aborted) throw createAbortError(signal, operation);
+}
+function isAbortError(error) {
+	return error instanceof _mastra_core_workspace.SandboxAbortError || error instanceof Error && (error.name === "AbortError" || "code" in error && error.code === "ABORT_ERR");
+}
+function normalizeAbortError(error, operation) {
+	return error instanceof _mastra_core_workspace.SandboxAbortError ? error : isAbortError(error) ? new _mastra_core_workspace.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 _mastra_core_workspace.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
@@ -569,7 +601,9 @@ var DockerSandbox = class DockerSandbox extends _mastra_core_workspace.MastraSan
 		if (!this._container) throw new _mastra_core_workspace.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) {
@@ -590,7 +624,7 @@ var DockerSandbox = class DockerSandbox extends _mastra_core_workspace.MastraSan
 			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}`);
@@ -850,10 +884,20 @@ var DockerSandbox = class DockerSandbox extends _mastra_core_workspace.MastraSan
 	* 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 _mastra_core_workspace.SandboxError(`Docker template build failed: ${result.error ?? "unknown error"}`, "START_FAILED", {
 			templateId: result.templateId,
 			reason: "template_build_failed"
@@ -1226,9 +1270,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 = (0, crypto.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",
@@ -1244,8 +1296,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 _grpc_grpc_js.Server();
@@ -1566,7 +1624,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 ?? [];
@@ -1713,19 +1772,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",
@@ -1735,24 +1824,37 @@ var DockerTemplate = class DockerTemplate {
 			if (!isImageNotFoundError(error)) throw error;
 		}
 		const secrets = await this.#resolveSecrets(options.secrets);
+		throwIfAborted(abortSignal, "build Docker template");
 		const context = (0, tar_stream.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,
@@ -1783,12 +1885,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,
@@ -1803,7 +1928,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();
@@ -1814,20 +1939,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();
 			});
 		});
 	}
@@ -1976,16 +2117,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,
@@ -2034,7 +2190,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 ? {
@@ -2049,6 +2206,7 @@ async function resolveHead(cloneUrl, ref, token) {
 			ref ?? "HEAD"
 		], {
 			timeout: 1e4,
+			signal: abortSignal,
 			env: {
 				...process.env,
 				...authEnv,
@@ -2058,7 +2216,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;
 	}
 }