@mastra/railway 0.4.1-alpha.0 → 0.4.1-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @mastra/railway
 
+## 0.4.1-alpha.1
+
+### Patch Changes
+
+- Improved Railway sandbox recovery and checkpoint management: ([#20739](https://github.com/mastra-ai/mastra/pull/20739))
+
+  - A configured `sandboxId` reconnects when the sandbox is running, or creates a replacement when it is missing or stopped.
+  - Use `captureCheckpoint()` to save a recovery point on demand. Saved checkpoints provide the baseline filesystem for new sandboxes; `stop()` captures one before teardown and `destroy()` removes it.
+  - `start()` no longer resolves `template`. The option is still accepted and copied by `clone()`, but has no effect: callers receive neither a custom base image nor an error.
+
+- Updated dependencies [[`b4c89b4`](https://github.com/mastra-ai/mastra/commit/b4c89b4371b0c86da57403ad1a3b3ef0681f3128), [`e44e8f3`](https://github.com/mastra-ai/mastra/commit/e44e8f370b66c339ddcaba946d33da6d3c3f06cd), [`c967a5e`](https://github.com/mastra-ai/mastra/commit/c967a5eec150c5dc5418c4a4388982d1fb7ad27c), [`f53d5bd`](https://github.com/mastra-ai/mastra/commit/f53d5bd4885b29e4ac29a428a6044088ea8d6aa3), [`bda2235`](https://github.com/mastra-ai/mastra/commit/bda22353ee28f2df0eaea555f7cae1549f979c0b), [`a7eb4a1`](https://github.com/mastra-ai/mastra/commit/a7eb4a11450f6170274ed5141bffe821d4fdd5a6), [`2f9ef3f`](https://github.com/mastra-ai/mastra/commit/2f9ef3f4ca06fc2dcdd5088c26b7f4da6a016791), [`e7eefcb`](https://github.com/mastra-ai/mastra/commit/e7eefcb162cda7c493e8c3bf43050ead0efbcb2c), [`4d7aca2`](https://github.com/mastra-ai/mastra/commit/4d7aca2fe75f225c83d1502d63079568e6ec163f), [`c4ec889`](https://github.com/mastra-ai/mastra/commit/c4ec889561c0264c43f66d04d587bee4ce35e792), [`9be8878`](https://github.com/mastra-ai/mastra/commit/9be8878dcf0388e84fc4873e0eec27bd49b881a4)]:
+  - @mastra/core@1.58.0-alpha.2
+
 ## 0.4.1-alpha.0
 
 ### Patch Changes

package/dist/index.cjs

@@ -194,9 +194,10 @@ var RailwaySandbox = class RailwaySandbox extends _mastra_core_workspace.MastraS
 	_createdAt = null;
 	_checkpointRefreshTimer = null;
 	_checkpointRefreshInFlight = null;
+	_sandboxId;
+	_startInFlight = null;
 	_token;
 	_environmentId;
-	_sandboxId;
 	_checkpointName;
 	_idleTimeoutMinutes;
 	_networkIsolation;
@@ -242,67 +243,60 @@ var RailwaySandbox = class RailwaySandbox extends _mastra_core_workspace.MastraS
 	*/
 	async start() {
 		if (this._sandbox) return;
-		await this._startRailwaySandbox({
-			reconnectSandboxId: this._sandboxId,
-			fallbackToCreate: false
+		const clientConfig = this._clientConfig();
+		const createOptions = this._createOptions(clientConfig);
+		if (this._sandboxId) {
+			const sandboxId = this._sandboxId;
+			this._startInFlight ??= (async () => {
+				try {
+					this._sandbox = await this._reconnectSandbox(sandboxId, clientConfig);
+				} catch (error) {
+					if (!(error instanceof railway.SandboxNotFoundError)) throw error;
+					this._sandbox = await this._createNewSandbox(createOptions);
+				}
+			})().finally(() => {
+				this._startInFlight = null;
+			});
+		} else this._startInFlight ??= (async () => {
+			this._sandbox = await this._createNewSandbox(createOptions);
+		})().finally(() => {
+			this._startInFlight = null;
 		});
+		await this._startInFlight;
+		if (!this._sandbox) throw new Error("Failed to start Railway sandbox");
+		const sandbox = this._sandbox;
+		this._sandboxId = sandbox.id;
+		this._createdAt = sandbox.createdAt ? new Date(sandbox.createdAt) : /* @__PURE__ */ new Date();
+		this.logger.debug(`${LOG_PREFIX} Railway sandbox ${sandbox.id} ready for logical ID: ${this.id}`);
+		this._scheduleCheckpointRefresh();
 	}
-	async restart() {
-		const reconnectSandboxId = this._sandbox?.id ?? this._sandboxId;
-		this._cancelCheckpointRefresh();
-		await this._checkpointRefreshInFlight?.catch((error) => {
-			this.logger.warn(`${LOG_PREFIX} Failed to flush in-flight checkpoint before restart:`, error);
-		});
-		this._sandbox = null;
-		this._createdAt = null;
-		this.status = "starting";
+	/**
+	* Create a new Railway sandbox.
+	*/
+	async _createNewSandbox(createOptions) {
+		this.logger.debug(`${LOG_PREFIX} Creating Railway sandbox for: ${this.id}`);
 		try {
-			await this._startRailwaySandbox({
-				reconnectSandboxId,
-				fallbackToCreate: true
-			});
-			this.status = "running";
+			let checkpoinAlreadyExists = false;
+			if (this._checkpointName) checkpoinAlreadyExists = (await railway.Sandbox.checkpoints(this._clientConfig())).some((checkpoint) => checkpoint.key === this._checkpointName);
+			let sandbox;
+			if (checkpoinAlreadyExists) sandbox = await railway.Sandbox.create(this._checkpointName, createOptions);
+			else sandbox = await railway.Sandbox.create(createOptions);
+			return sandbox;
 		} catch (error) {
-			this.status = "error";
 			throw error;
 		}
 	}
-	async withRestartRetry(operation) {
-		await this.ensureRunning();
-		try {
-			return await operation();
-		} catch (error) {
-			if (!this.isSandboxUnavailableError(error)) throw error;
-			await this.restart();
-			return await operation();
-		} finally {
-			this._scheduleCheckpointRefresh();
-		}
-	}
-	async _startRailwaySandbox({ reconnectSandboxId, fallbackToCreate }) {
-		const clientConfig = this._clientConfig();
-		const createOptions = this._createOptions(clientConfig);
-		this._sandbox = reconnectSandboxId ? await this._reconnectSandbox(reconnectSandboxId, fallbackToCreate, clientConfig, createOptions) : await this._createNewSandbox(createOptions);
-		this._createdAt = this._sandbox.createdAt ? new Date(this._sandbox.createdAt) : /* @__PURE__ */ new Date();
-		this.logger.debug(`${LOG_PREFIX} Railway sandbox ${this._sandbox.id} ready for logical ID: ${this.id}`);
-		this._scheduleCheckpointRefresh();
-	}
 	/**
 	* Reconnect to an existing Railway sandbox, creating a fresh one when
-	* `fallbackToCreate` is set and the sandbox is unavailable or not running.
 	*/
-	async _reconnectSandbox(reconnectSandboxId, fallbackToCreate, clientConfig, createOptions) {
+	async _reconnectSandbox(reconnectSandboxId, clientConfig) {
 		this.logger.debug(`${LOG_PREFIX} Reconnecting to Railway sandbox ${reconnectSandboxId}...`);
-		let connectedSandbox;
-		try {
-			connectedSandbox = await railway.Sandbox.connect(reconnectSandboxId, clientConfig);
-		} catch (error) {
-			if (!fallbackToCreate || !this.isSandboxUnavailableError(error)) throw error;
-			return this._createNewSandbox(createOptions);
-		}
-		if (connectedSandbox.status === "RUNNING") return connectedSandbox;
-		if (!fallbackToCreate) throw new Error(`Railway sandbox ${reconnectSandboxId} is not running (status: ${connectedSandbox.status})`);
-		return this._createNewSandbox(createOptions);
+		let connectedSandbox = await railway.Sandbox.connect(reconnectSandboxId, clientConfig);
+		if (connectedSandbox.status !== "RUNNING") throw new railway.SandboxNotFoundError({
+			id: reconnectSandboxId,
+			environmentId: clientConfig.environmentId ?? ""
+		});
+		return connectedSandbox;
 	}
 	_clientConfig() {
 		return {
@@ -318,85 +312,6 @@ var RailwaySandbox = class RailwaySandbox extends _mastra_core_workspace.MastraS
 			...Object.keys(this._env).length > 0 && { env: this._env }
 		};
 	}
-	async _createNewSandbox(createOptions) {
-		const checkpointSandbox = await this._tryCreateFromCheckpoint(createOptions);
-		if (checkpointSandbox) return checkpointSandbox;
-		if (this._templateOption) {
-			const template = this._resolveTemplate();
-			this.logger.debug(`${LOG_PREFIX} Creating Railway sandbox from template for: ${this.id}`);
-			const sandbox = await railway.Sandbox.create(template, createOptions);
-			await this._checkpointSandbox(sandbox);
-			return sandbox;
-		}
-		this.logger.debug(`${LOG_PREFIX} Creating Railway sandbox for: ${this.id}`);
-		const sandbox = await railway.Sandbox.create(createOptions);
-		await this._checkpointSandbox(sandbox);
-		return sandbox;
-	}
-	async _tryCreateFromCheckpoint(createOptions) {
-		if (!this._checkpointName) return;
-		this.logger.debug(`${LOG_PREFIX} Creating Railway sandbox from checkpoint ${this._checkpointName} for: ${this.id}`);
-		try {
-			return await railway.Sandbox.create(this._checkpointName, createOptions);
-		} catch (error) {
-			if (!this.isCheckpointUnavailableError(error)) throw error;
-			return;
-		}
-	}
-	async _checkpointSandbox(sandbox) {
-		if (!this._checkpointName) return;
-		try {
-			this.logger.debug(`${LOG_PREFIX} Capturing Railway sandbox checkpoint ${this._checkpointName} for: ${this.id}`);
-			await sandbox.checkpoint(this._checkpointName);
-		} catch (error) {
-			if (!this.isCheckpointAlreadyExistsError(error)) throw error;
-			await this._deleteCheckpointByName(this._checkpointName);
-			await sandbox.checkpoint(this._checkpointName);
-		}
-	}
-	async _deleteCheckpointByName(name) {
-		try {
-			const checkpoint = (await railway.Sandbox.checkpoints(this._clientConfig())).find((checkpoint) => checkpoint.key === name);
-			if (!checkpoint) return;
-			await railway.Sandbox.deleteCheckpoint(checkpoint.id, this._clientConfig());
-		} catch (error) {
-			if (!this.isCheckpointUnavailableError(error)) throw error;
-		}
-	}
-	_scheduleCheckpointRefresh() {
-		if (!this._checkpointName || !this._sandbox) return;
-		const idleTimeoutMinutes = this._idleTimeoutMinutes ?? this._sandbox.idleTimeoutMinutes;
-		if (!idleTimeoutMinutes) return;
-		if (this._checkpointRefreshTimer) clearTimeout(this._checkpointRefreshTimer);
-		const delayMs = Math.max(1e3, idleTimeoutMinutes * 6e4 - CHECKPOINT_REFRESH_MARGIN_MS);
-		this._checkpointRefreshTimer = setTimeout(() => {
-			this._checkpointRefreshTimer = null;
-			const sandbox = this._sandbox;
-			if (!sandbox) return;
-			const refresh = this._checkpointSandbox(sandbox).finally(() => {
-				if (this._checkpointRefreshInFlight === refresh) this._checkpointRefreshInFlight = null;
-			});
-			this._checkpointRefreshInFlight = refresh;
-			this._checkpointRefreshInFlight.catch((error) => {
-				this.logger.warn(`${LOG_PREFIX} Failed to refresh Railway sandbox checkpoint ${this._checkpointName}:`, error);
-			});
-		}, delayMs);
-		this._checkpointRefreshTimer.unref?.();
-	}
-	_cancelCheckpointRefresh() {
-		if (this._checkpointRefreshTimer) {
-			clearTimeout(this._checkpointRefreshTimer);
-			this._checkpointRefreshTimer = null;
-		}
-	}
-	async _flushCheckpointRefresh() {
-		this._cancelCheckpointRefresh();
-		if (this._checkpointRefreshInFlight) {
-			await this._checkpointRefreshInFlight;
-			return;
-		}
-		if (this._sandbox) await this._checkpointSandbox(this._sandbox);
-	}
 	/**
 	* Capture the sandbox's checkpoint on demand, outside the idle-timer schedule.
 	*
@@ -447,74 +362,76 @@ var RailwaySandbox = class RailwaySandbox extends _mastra_core_workspace.MastraS
 			checkpointName
 		};
 	}
-	isCheckpointUnavailableError(error) {
-		if (!(error instanceof Error)) return false;
-		const message = error.message.toLowerCase();
-		return message.includes("checkpoint") && [
-			"not found",
-			"does not exist",
-			"missing",
-			"unknown",
-			"no checkpoint"
-		].some((phrase) => message.includes(phrase));
-	}
-	isCheckpointAlreadyExistsError(error) {
-		if (!(error instanceof Error)) return false;
-		const message = error.message.toLowerCase();
-		return message.includes("checkpoint") && ([
-			"already exists",
-			"must be unused",
-			"unique"
-		].some((phrase) => message.includes(phrase)) || message.includes("name") && message.includes("used"));
-	}
-	isSandboxUnavailableError(error, seen = /* @__PURE__ */ new Set()) {
-		if (error && typeof error === "object") {
-			if (seen.has(error)) return false;
-			seen.add(error);
-		}
-		if (error instanceof railway.SandboxNotFoundError || error instanceof railway.SandboxFailedError || error instanceof railway.SandboxTimeoutError && error.resource === "sandbox") return true;
-		if (error && typeof error === "object") {
-			const errorLike = error;
-			const name = typeof errorLike.name === "string" ? errorLike.name : "";
-			const message = typeof errorLike.message === "string" ? errorLike.message.toLowerCase() : "";
-			if (name === "SandboxNotFoundError" || name === "SandboxFailedError" || name === "SandboxTimeoutError" && errorLike.resource === "sandbox") return true;
-			if (message.includes("sandbox") && [
-				"not found",
-				"destroyed",
-				"failed",
-				"not running",
-				"unavailable"
-			].some((phrase) => message.includes(phrase))) return true;
-			if (errorLike.cause !== void 0) return this.isSandboxUnavailableError(errorLike.cause, seen);
+	async _checkpointSandbox(sandbox) {
+		if (!this._checkpointName) return;
+		this.logger.debug(`${LOG_PREFIX} Capturing Railway sandbox checkpoint ${this._checkpointName} for: ${this.id}`);
+		if ((await railway.Sandbox.checkpoints(this._clientConfig())).some((checkpoint) => checkpoint.key === this._checkpointName)) await railway.Sandbox.deleteCheckpoint(this._checkpointName, this._clientConfig());
+		await sandbox.checkpoint(this._checkpointName);
+	}
+	_scheduleCheckpointRefresh() {
+		if (!this._checkpointName || !this._sandbox) return;
+		const idleTimeoutMinutes = this._idleTimeoutMinutes ?? this._sandbox.idleTimeoutMinutes;
+		if (!idleTimeoutMinutes) return;
+		this._cancelCheckpointRefresh();
+		const delayMs = Math.max(1e3, idleTimeoutMinutes * 6e4 - CHECKPOINT_REFRESH_MARGIN_MS);
+		this._checkpointRefreshTimer = setTimeout(() => {
+			this._checkpointRefreshTimer = null;
+			const sandbox = this._sandbox;
+			if (!sandbox || this._checkpointRefreshInFlight) return;
+			const refresh = this._checkpointSandbox(sandbox).finally(() => {
+				if (this._checkpointRefreshInFlight === refresh) this._checkpointRefreshInFlight = null;
+			});
+			this._checkpointRefreshInFlight = refresh;
+			refresh.catch((error) => {
+				this.logger.warn(`${LOG_PREFIX} Failed to refresh Railway sandbox checkpoint ${this._checkpointName}:`, error);
+			});
+		}, delayMs);
+		this._checkpointRefreshTimer.unref?.();
+	}
+	_cancelCheckpointRefresh() {
+		if (this._checkpointRefreshTimer) {
+			clearTimeout(this._checkpointRefreshTimer);
+			this._checkpointRefreshTimer = null;
 		}
-		return false;
 	}
 	/**
 	* Stop the Railway sandbox.
 	*
 	* Railway sandboxes have no separate "stopped" state — they're either
-	* running or destroyed — so stopping destroys the sandbox.
+	* running or destroyed — so stopping destroys the sandbox but we keep a checkpoint of the filesystem.
 	*/
 	async stop() {
+		if (this._checkpointName) await this._flushCheckpointRefresh().catch((error) => {
+			this.logger.warn(`${LOG_PREFIX} Failed to checkpoint Railway sandbox ${this._sandbox?.id}:`, error);
+		});
 		await this._teardown();
 	}
 	/**
-	* Destroy the Railway sandbox and release its resources.
+	* Destroy the Railway sandbox and release its resources including the checkpoint.
 	*/
 	async destroy() {
+		this._cancelCheckpointRefresh();
+		if (this._checkpointName) {
+			await this._checkpointRefreshInFlight;
+			await railway.Sandbox.deleteCheckpoint(this._checkpointName, this._clientConfig()).catch((error) => {
+				this.logger.warn(`${LOG_PREFIX} Failed to delete Railway checkpoint ${this._checkpointName}:`, error);
+			});
+		}
 		await this._teardown();
 	}
-	async _teardown() {
-		if (!this._sandbox) {
-			this._cancelCheckpointRefresh();
+	async _flushCheckpointRefresh() {
+		this._cancelCheckpointRefresh();
+		if (this._checkpointRefreshInFlight) {
+			await this._checkpointRefreshInFlight;
 			return;
 		}
+		if (this._sandbox) await this._checkpointSandbox(this._sandbox);
+	}
+	async _teardown() {
+		this._cancelCheckpointRefresh();
+		if (!this._sandbox) return;
+		await this._checkpointRefreshInFlight;
 		const sandbox = this._sandbox;
-		try {
-			await this._flushCheckpointRefresh();
-		} catch (error) {
-			this.logger.warn(`${LOG_PREFIX} Failed to flush checkpoint before teardown:`, error);
-		}
 		this._sandbox = null;
 		try {
 			await sandbox.destroy();
@@ -523,15 +440,6 @@ var RailwaySandbox = class RailwaySandbox extends _mastra_core_workspace.MastraS
 		}
 	}
 	/**
-	* Resolve the configured template into a `SandboxTemplate` that Railway
-	* builds during `Sandbox.create()`. Accepts either a pre-built
-	* `SandboxTemplate` or a builder callback over `Sandbox.template()`.
-	*/
-	_resolveTemplate() {
-		const option = this._templateOption;
-		return typeof option === "function" ? option(railway.Sandbox.template()) : option;
-	}
-	/**
 	* Fork this running sandbox into a new, independent `RailwaySandbox`.
 	*
 	* Clones the filesystem (a fresh boot, not live processes) into the same
@@ -542,7 +450,7 @@ var RailwaySandbox = class RailwaySandbox extends _mastra_core_workspace.MastraS
 	* @throws {SandboxNotReadyError} If this sandbox has not been started.
 	*/
 	async fork(options = {}) {
-		const forked = await this.railway.fork({
+		await this.railway.fork({
 			...options.idleTimeoutMinutes !== void 0 && { idleTimeoutMinutes: options.idleTimeoutMinutes },
 			...options.networkIsolation !== void 0 && { networkIsolation: options.networkIsolation },
 			...options.env !== void 0 && { env: options.env }
@@ -551,7 +459,6 @@ var RailwaySandbox = class RailwaySandbox extends _mastra_core_workspace.MastraS
 			...options.id !== void 0 && { id: options.id },
 			...this._token !== void 0 && { token: this._token },
 			...this._environmentId !== void 0 && { environmentId: this._environmentId },
-			sandboxId: forked.id,
 			idleTimeoutMinutes: options.idleTimeoutMinutes ?? this._idleTimeoutMinutes,
 			networkIsolation: options.networkIsolation ?? this._networkIsolation,
 			env: options.env ?? this._env,
@@ -576,7 +483,6 @@ var RailwaySandbox = class RailwaySandbox extends _mastra_core_workspace.MastraS
 			...options.id !== void 0 && { id: options.id },
 			...this._token !== void 0 && { token: this._token },
 			...this._environmentId !== void 0 && { environmentId: this._environmentId },
-			...options.sandboxId !== void 0 && { sandboxId: options.sandboxId },
 			...(options.checkpointName ?? this._checkpointName) !== void 0 && { checkpointName: options.checkpointName ?? this._checkpointName },
 			idleTimeoutMinutes: options.idleTimeoutMinutes ?? this._idleTimeoutMinutes,
 			...this._networkIsolation !== void 0 && { networkIsolation: this._networkIsolation },
@@ -633,28 +539,31 @@ var RailwaySandbox = class RailwaySandbox extends _mastra_core_workspace.MastraS
 	* Execute a command in the sandbox and return the result.
 	*/
 	async executeCommand(command, args = [], options = {}) {
-		return this.withRestartRetry(async () => {
-			const fullCommand = args.length > 0 ? `${command} ${args.map(shellQuote).join(" ")}` : command;
-			const timeout = options.timeout ?? this._timeout;
-			const env = options.env ? Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== void 0)) : void 0;
-			const startedAt = Date.now();
-			const result = await this.railway.exec(fullCommand, {
-				...timeout !== void 0 && { timeoutSec: Math.ceil(timeout / 1e3) },
-				...options.cwd !== void 0 && { cwd: options.cwd },
-				...env !== void 0 && { env }
-			});
-			const exitCode = result.exitCode ?? -1;
-			return {
-				success: exitCode === 0,
-				exitCode,
-				stdout: result.stdout,
-				stderr: result.stderr,
-				executionTimeMs: Date.now() - startedAt,
-				command,
-				args,
-				timedOut: result.timedOut
-			};
+		if (this._sandbox?.status !== "RUNNING") {
+			if (!this._checkpointName) throw new _mastra_core_workspace.SandboxNotReadyError(this.id);
+			this._sandbox = null;
+			await this.start();
+		}
+		const fullCommand = args.length > 0 ? `${command} ${args.map(shellQuote).join(" ")}` : command;
+		const timeout = options.timeout ?? this._timeout;
+		const env = options.env ? Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== void 0)) : void 0;
+		const startedAt = Date.now();
+		const result = await this.railway.exec(fullCommand, {
+			...timeout !== void 0 && { timeoutSec: Math.ceil(timeout / 1e3) },
+			...options.cwd !== void 0 && { cwd: options.cwd },
+			...env !== void 0 && { env }
 		});
+		const exitCode = result.exitCode ?? -1;
+		return {
+			success: exitCode === 0,
+			exitCode,
+			stdout: result.stdout,
+			stderr: result.stderr,
+			executionTimeMs: Date.now() - startedAt,
+			command,
+			args,
+			timedOut: result.timedOut
+		};
 	}
 };
 //#endregion