@mastra/docker 0.11.1-alpha.1 → 0.12.0-alpha.2

package/README.md

@@ -141,6 +141,43 @@ const template = new DockerTemplate({ secrets: { GITHUB_TOKEN: token } })
 `dispose()` removes the image; Docker refuses while a container still references
 it, so destroy the template's sandboxes first.
 
+#### Build progress
+
+Pass `onProgress` to `build()` (or `onTemplateBuildProgress` to `DockerSandbox`)
+to follow a long preparation while it runs:
+
+```typescript
+const result = await template.build({
+  onProgress: event => {
+    if (event.type === 'step-start') console.log(`> ${event.step.name}${event.step.cached ? ' (cached)' : ''}`);
+    if (event.type === 'output') process.stdout.write(redact(event.text));
+  },
+  maxOutputBytes: 32 * 1024, // default 64 KiB
+});
+if (result.status === 'failed') {
+  console.error(result.error, result.failedStep?.name, result.output, result.outputTruncated);
+}
+```
+
+Events are `reused` (the image already exists, nothing is built),
+`build-start` (with `builder: 'legacy' | 'buildkit'`), `step-start`,
+`step-complete` (with `cached` when the builder reports a cache hit), `output`,
+and `build-complete`. Plain builds use the legacy builder, which reports
+`Step N/M` steps; builds with secrets use BuildKit, which reports build
+vertices. The callback contract:
+
+- Delivery is synchronous, in arrival order, with no backpressure — keep the
+  callback fast and hand heavy work off elsewhere.
+- Errors thrown by the callback are ignored and never fail the build.
+- Concurrent callers sharing a build each receive its events from the moment
+  they join (no replay). A caller that aborts stops receiving events; the build
+  continues for the remaining callers.
+- Only the most recent `maxOutputBytes` of output are retained, and only to
+  populate `output` on failed results; `outputTruncated` reports whether older
+  output was dropped.
+- `output` text is raw command output. Commands run with `runWithSecrets` can
+  echo secret values into it, so redact before logging or persisting.
+
 #### Repository templates
 
 `createDockerRepoTemplate` prepares a repository checkout plus setup commands,

package/dist/index.cjs

@@ -607,6 +607,7 @@ var DockerSandbox = class DockerSandbox extends _mastra_core_workspace.MastraSan
 	/** Image the container boots from; rewritten by a template resolution on `start()`. */
 	_image;
 	_templateSpec;
+	_onTemplateBuildProgress;
 	_workingDirectoryWasSet;
 	_command;
 	_env;
@@ -650,6 +651,7 @@ var DockerSandbox = class DockerSandbox extends _mastra_core_workspace.MastraSan
 		this._containerName = sanitizeContainerName(options.name ?? this.id);
 		if (options.image !== void 0 && options.template !== void 0) throw new TypeError("DockerSandbox: `image` and `template` are mutually exclusive");
 		this._templateSpec = options.template;
+		this._onTemplateBuildProgress = options.onTemplateBuildProgress;
 		this._image = options.image ?? "node:22-slim";
 		this._workingDirectoryWasSet = options.workingDirectory !== void 0 || options.workingDir !== void 0;
 		this._command = options.command ?? ["sleep", "infinity"];
@@ -1009,7 +1011,8 @@ var DockerSandbox = class DockerSandbox extends _mastra_core_workspace.MastraSan
 		throwIfAborted(abortSignal, "start Docker sandbox");
 		const result = await template.build({
 			docker: this._docker,
-			abortSignal
+			abortSignal,
+			...this._onTemplateBuildProgress && { onProgress: this._onTemplateBuildProgress }
 		});
 		if (result.status !== "ready") throw new _mastra_core_workspace.SandboxError(`Docker template build failed: ${result.error ?? "unknown error"}`, "START_FAILED", {
 			templateId: result.templateId,
@@ -1362,6 +1365,287 @@ const dockerSandboxProvider = {
 	createSandbox: (config) => new DockerSandbox(config)
 };
 //#endregion
+//#region src/template/build-progress.ts
+/**
+* Build progress for `DockerTemplate.build()`.
+*
+* The daemon reports build progress as newline-delimited JSON. The legacy
+* builder sends plain text (`{stream: "Step 2/5 : RUN ..."}`); BuildKit sends
+* `{id: 'moby.buildkit.trace', aux: <base64 StatusResponse protobuf>}`. This
+* module normalizes both into {@link DockerTemplateBuildEvent}s and keeps a
+* bounded tail of raw output for failure diagnostics.
+*/
+const DEFAULT_MAX_OUTPUT_BYTES = 64 * 1024;
+/** Keeps at most `maxBytes` (UTF-8) of the most recent text. */
+var BoundedTail = class {
+	#maxBytes;
+	#chunks = [];
+	#bytes = 0;
+	#truncated = false;
+	constructor(maxBytes) {
+		this.#maxBytes = maxBytes;
+	}
+	get truncated() {
+		return this.#truncated;
+	}
+	push(text) {
+		if (text.length === 0) return;
+		let chunk = Buffer.from(text, "utf8");
+		if (chunk.length > this.#maxBytes) {
+			chunk = chunk.subarray(chunk.length - this.#maxBytes);
+			this.#chunks = [];
+			this.#bytes = 0;
+			this.#truncated = true;
+		}
+		this.#chunks.push(chunk);
+		this.#bytes += chunk.length;
+		while (this.#bytes > this.#maxBytes) {
+			const head = this.#chunks[0];
+			const excess = this.#bytes - this.#maxBytes;
+			this.#truncated = true;
+			if (head.length <= excess) {
+				this.#chunks.shift();
+				this.#bytes -= head.length;
+			} else {
+				this.#chunks[0] = head.subarray(excess);
+				this.#bytes -= excess;
+			}
+		}
+	}
+	toString() {
+		let text = Buffer.concat(this.#chunks).toString("utf8");
+		if (this.#truncated) text = text.replace(/^\uFFFD+/, "");
+		return text;
+	}
+};
+function readFields(buffer) {
+	const fields = [];
+	let offset = 0;
+	const readVarint = () => {
+		let result = 0;
+		let shift = 0;
+		for (;;) {
+			if (offset >= buffer.length) throw new Error("truncated varint");
+			const byte = buffer[offset++];
+			result += (byte & 127) * 2 ** shift;
+			if ((byte & 128) === 0) return result;
+			shift += 7;
+		}
+	};
+	while (offset < buffer.length) {
+		const key = readVarint();
+		const field = Math.floor(key / 8);
+		const wireType = key % 8;
+		switch (wireType) {
+			case 0:
+				fields.push({
+					field,
+					value: readVarint()
+				});
+				break;
+			case 1:
+				offset += 8;
+				break;
+			case 5:
+				offset += 4;
+				break;
+			case 2: {
+				const length = readVarint();
+				if (offset + length > buffer.length) throw new Error("truncated field");
+				fields.push({
+					field,
+					value: buffer.subarray(offset, offset + length)
+				});
+				offset += length;
+				break;
+			}
+			default: throw new Error(`unsupported protobuf wire type ${wireType}`);
+		}
+	}
+	return fields;
+}
+/** @internal exported for tests. Throws on malformed input. */
+function decodeBuildkitStatus(aux) {
+	const vertexes = [];
+	const logs = [];
+	for (const { field, value } of readFields(Buffer.from(aux, "base64"))) {
+		if (!Buffer.isBuffer(value)) continue;
+		if (field === 1) {
+			const vertex = {
+				digest: "",
+				cached: false,
+				started: false,
+				completed: false
+			};
+			for (const f of readFields(value)) if (f.field === 1 && Buffer.isBuffer(f.value)) vertex.digest = f.value.toString("utf8");
+			else if (f.field === 3 && Buffer.isBuffer(f.value)) vertex.name = f.value.toString("utf8");
+			else if (f.field === 4) vertex.cached = f.value !== 0;
+			else if (f.field === 5) vertex.started = true;
+			else if (f.field === 6) vertex.completed = true;
+			else if (f.field === 7 && Buffer.isBuffer(f.value) && f.value.length > 0) vertex.error = f.value.toString("utf8");
+			if (vertex.digest) vertexes.push(vertex);
+		} else if (field === 3) {
+			let vertex = "";
+			let data = Buffer.alloc(0);
+			for (const f of readFields(value)) if (f.field === 1 && Buffer.isBuffer(f.value)) vertex = f.value.toString("utf8");
+			else if (f.field === 4 && Buffer.isBuffer(f.value)) data = f.value;
+			logs.push({
+				vertex,
+				data
+			});
+		}
+	}
+	return {
+		vertexes,
+		logs
+	};
+}
+const LEGACY_STEP = /^Step (\d+)\/(\d+) : (.*)$/;
+function createBuildEventNormalizer(emit, tail) {
+	let failure;
+	let failedStep;
+	let legacyStep;
+	let legacyCached;
+	let pending = "";
+	const vertexes = /* @__PURE__ */ new Map();
+	const decoders = /* @__PURE__ */ new Map();
+	const output = (text, stepId) => {
+		if (!text) return;
+		tail.push(text);
+		emit({
+			type: "output",
+			...stepId !== void 0 && { stepId },
+			text
+		});
+	};
+	const completeLegacyStep = (error) => {
+		if (!legacyStep) return;
+		const step = {
+			...legacyStep,
+			...legacyCached !== void 0 && { cached: legacyCached }
+		};
+		if (error !== void 0) failedStep = step;
+		emit({
+			type: "step-complete",
+			step,
+			...error !== void 0 && { error }
+		});
+		legacyStep = void 0;
+		legacyCached = void 0;
+	};
+	const handleLegacyLine = (line) => {
+		const match = LEGACY_STEP.exec(line.replace(/\r?\n$/, ""));
+		if (match) {
+			completeLegacyStep();
+			legacyStep = {
+				id: match[1],
+				name: match[3],
+				index: Number(match[1]),
+				total: Number(match[2])
+			};
+			emit({
+				type: "step-start",
+				step: { ...legacyStep }
+			});
+			return;
+		}
+		if (legacyStep) {
+			const trimmed = line.trim();
+			if (trimmed === "---> Using cache") legacyCached = true;
+			else if (trimmed.startsWith("---> Running in ") && legacyCached === void 0) legacyCached = false;
+		}
+		output(line, legacyStep?.id);
+	};
+	const handleLegacyStream = (text) => {
+		pending += text;
+		let newline = pending.indexOf("\n");
+		while (newline !== -1) {
+			handleLegacyLine(pending.slice(0, newline + 1));
+			pending = pending.slice(newline + 1);
+			newline = pending.indexOf("\n");
+		}
+	};
+	const flushLegacy = () => {
+		if (pending) {
+			handleLegacyLine(pending);
+			pending = "";
+		}
+	};
+	const handleBuildkit = (aux) => {
+		const { vertexes: updates, logs } = decodeBuildkitStatus(aux);
+		for (const update of updates) {
+			let state = vertexes.get(update.digest);
+			if (!state) {
+				state = {
+					step: {
+						id: update.digest,
+						name: update.name ?? ""
+					},
+					started: false,
+					completed: false
+				};
+				vertexes.set(update.digest, state);
+			}
+			if (update.name && !state.step.name) state.step.name = update.name;
+			if (update.cached) state.step.cached = true;
+			if (state.step.name.startsWith("[internal]")) continue;
+			if (!state.started && (update.started || update.completed || update.cached || update.error)) {
+				state.started = true;
+				emit({
+					type: "step-start",
+					step: { ...state.step }
+				});
+			}
+			if (!state.completed && (update.completed || update.error)) {
+				state.completed = true;
+				if (state.step.cached === void 0) state.step.cached = false;
+				const step = { ...state.step };
+				if (update.error) failedStep = step;
+				emit({
+					type: "step-complete",
+					step,
+					...update.error && { error: update.error }
+				});
+			}
+		}
+		for (const log of logs) {
+			if (vertexes.get(log.vertex)?.step.name.startsWith("[internal]")) continue;
+			let decoder = decoders.get(log.vertex);
+			if (!decoder) {
+				decoder = new string_decoder.StringDecoder("utf8");
+				decoders.set(log.vertex, decoder);
+			}
+			output(decoder.write(log.data), log.vertex || void 0);
+		}
+	};
+	const handleError = (raw) => {
+		const detail = raw.errorDetail;
+		const message = String(detail?.message ?? raw.error ?? "docker build failed");
+		flushLegacy();
+		completeLegacyStep(message);
+		if (!failure) failure = {
+			message,
+			...failedStep && { step: failedStep }
+		};
+	};
+	return {
+		handle(raw) {
+			if (!raw || typeof raw !== "object") return;
+			const event = raw;
+			try {
+				if (event.error !== void 0 || event.errorDetail !== void 0) handleError(event);
+				else if (event.id === "moby.buildkit.trace" && typeof event.aux === "string") handleBuildkit(event.aux);
+				else if (typeof event.stream === "string") handleLegacyStream(event.stream);
+			} catch {}
+		},
+		finish() {
+			flushLegacy();
+			completeLegacyStep();
+		},
+		failure: () => failure
+	};
+}
+//#endregion
 //#region src/template/build-session.ts
 /**
 * BuildKit session that serves build secrets to the daemon.
@@ -1898,20 +2182,29 @@ var DockerTemplate = class DockerTemplate {
 	* `options.secrets`, the template's `secrets` option, or `process.env`.
 	*/
 	async build(options = {}) {
+		const { maxOutputBytes = DEFAULT_MAX_OUTPUT_BYTES } = options;
+		if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes <= 0) throw new RangeError("maxOutputBytes must be a positive integer");
 		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);
+		if (isPlain && this.#plainBuild) return this.#waitForBuild(this.#plainBuild, options.abortSignal, options.onProgress);
 		const previous = this.#queueTail?.promise.catch(() => void 0) ?? Promise.resolve();
 		const controller = new AbortController();
+		const listeners = /* @__PURE__ */ new Set();
+		const emit = (event) => {
+			for (const listener of [...listeners]) try {
+				listener(event);
+			} catch {}
+		};
 		const run = {
 			controller,
 			waiters: 0,
+			listeners,
 			promise: previous.then(() => {
 				throwIfAborted(controller.signal, "build Docker template");
 				return this.#build({
 					...options,
 					abortSignal: controller.signal
-				});
+				}, emit, maxOutputBytes);
 			})
 		};
 		this.#queueTail = run;
@@ -1920,20 +2213,23 @@ var DockerTemplate = class DockerTemplate {
 			if (this.#queueTail === run) this.#queueTail = void 0;
 			if (this.#plainBuild === run) this.#plainBuild = void 0;
 		}).catch(() => void 0);
-		return this.#waitForBuild(run, options.abortSignal);
+		return this.#waitForBuild(run, options.abortSignal, options.onProgress);
 	}
-	#waitForBuild(run, abortSignal) {
+	#waitForBuild(run, abortSignal, onProgress) {
 		run.waiters += 1;
+		const listener = onProgress && ((event) => onProgress(event));
+		if (listener) run.listeners.add(listener);
 		let settled = false;
 		const release = (aborted) => {
 			if (settled) return;
 			settled = true;
+			if (listener) run.listeners.delete(listener);
 			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) {
+	async #build(options, emit, maxOutputBytes) {
 		const docker = options.docker ?? this.#getDocker();
 		const tag = this.templateId;
 		const { abortSignal } = options;
@@ -1942,6 +2238,10 @@ var DockerTemplate = class DockerTemplate {
 			await docker.getImage(tag).inspect();
 			throwIfAborted(abortSignal, "build Docker template");
 			this.#built = true;
+			emit({
+				type: "reused",
+				templateId: tag
+			});
 			return {
 				status: "ready",
 				templateId: tag
@@ -1954,12 +2254,19 @@ var DockerTemplate = class DockerTemplate {
 		const context = (0, tar_stream.pack)();
 		context.entry({ name: "Dockerfile" }, this.dockerfile);
 		context.finalize();
+		const tail = new BoundedTail(maxOutputBytes);
+		const normalizer = createBuildEventNormalizer(emit, tail);
+		emit({
+			type: "build-start",
+			templateId: tag,
+			builder: secrets ? "buildkit" : "legacy"
+		});
 		try {
 			const nocache = options.force === true;
 			if (secrets) {
 				const { stream, session } = await this.#buildWithSecrets(docker, context, tag, secrets, nocache, abortSignal);
 				try {
-					await this.#followBuild(docker, stream, abortSignal);
+					await this.#followBuild(docker, stream, normalizer, abortSignal);
 				} finally {
 					session.close();
 				}
@@ -1977,18 +2284,31 @@ var DockerTemplate = class DockerTemplate {
 				}), abortSignal, "build Docker template", () => {
 					context.destroy?.();
 				});
-				await this.#followBuild(docker, stream, abortSignal);
+				await this.#followBuild(docker, stream, normalizer, abortSignal);
 			}
 		} catch (error) {
 			this.#built = false;
 			if (abortSignal?.aborted) throw normalizeAbortError(error, "build Docker template");
+			emit({
+				type: "build-complete",
+				status: "failed"
+			});
+			const failedStep = normalizer.failure()?.step;
 			return {
 				status: "failed",
 				templateId: tag,
-				error: error instanceof Error ? error.message : String(error)
+				error: error instanceof Error ? error.message : String(error),
+				...failedStep && { failedStep },
+				output: tail.toString(),
+				outputTruncated: tail.truncated
 			};
 		}
+		normalizer.finish();
 		this.#built = true;
+		emit({
+			type: "build-complete",
+			status: "ready"
+		});
 		return {
 			status: "ready",
 			templateId: tag
@@ -2066,7 +2386,7 @@ var DockerTemplate = class DockerTemplate {
 			session
 		};
 	}
-	#followBuild(docker, stream, abortSignal) {
+	#followBuild(docker, stream, normalizer, abortSignal) {
 		return new Promise((resolve, reject) => {
 			let settled = false;
 			const finish = (error) => {
@@ -2089,6 +2409,11 @@ var DockerTemplate = class DockerTemplate {
 					finish(err);
 					return;
 				}
+				const reported = normalizer.failure();
+				if (reported) {
+					finish(new Error(reported.message));
+					return;
+				}
 				const failure = output?.find((entry) => entry && (entry.error !== void 0 || entry.errorDetail !== void 0));
 				if (failure) {
 					const detail = failure.errorDetail;
@@ -2096,6 +2421,8 @@ var DockerTemplate = class DockerTemplate {
 					return;
 				}
 				finish();
+			}, (event) => {
+				if (!settled) normalizer.handle(event);
 			});
 		});
 	}