inngest 4.19.0 → 4.20.0

package/components/sandbox/client.js

@@ -1,5 +1,5 @@
 import { SandboxError, SandboxValidationError } from "./types.js";
-import { canonicalUuidSchema, decodeBase64, decodeOutputChunk, decodeUtf8, normalizeFileDownloadOptions, normalizeFileUploadOptions, normalizeSandboxCommandOptions, normalizeSandboxCreateOptions, normalizeSandboxListOptions, normalizeSandboxProcessListOptions, normalizeSandboxProcessOutputOptions, normalizeSandboxProcessSignalOptions, normalizeSandboxProcessStartOptions, normalizeSandboxProcessWaitOptions, normalizeSandboxWaitUntilRunningOptions, parseWithSchema, restOutputChunkSchema, sandboxProcessRefFromResource, sandboxProcessRefSchema, sandboxRefFromResource, sandboxRefSchema } from "./validation.js";
+import { canonicalUuidSchema, decodeBase64, decodeOutputChunk, decodeUtf8, normalizeFileDownloadOptions, normalizeFileUploadOptions, normalizeSandboxCommandOptions, normalizeSandboxCreateOptions, normalizeSandboxListOptions, normalizeSandboxProcessListOptions, normalizeSandboxProcessOutputOptions, normalizeSandboxProcessSignalOptions, normalizeSandboxProcessStartOptions, normalizeSandboxProcessWaitOptions, normalizeSandboxSnapshotCreateOptions, normalizeSandboxSnapshotListOptions, normalizeSandboxWaitUntilRunningOptions, parseWithSchema, restOutputChunkSchema, sandboxProcessRefFromResource, sandboxProcessRefSchema, sandboxRefFromResource, sandboxRefSchema, sandboxSnapshotRefFromResource, sandboxSnapshotRefSchema } from "./validation.js";
 import { z } from "zod/v3";
 
 //#region src/components/sandbox/client.ts
@@ -57,6 +57,8 @@ const waitProcessSchema = z.object({
 const safeRepeatActions = new Set([
 	"create",
 	"destroy",
+	"pause",
+	"resume",
 	"file.upload",
 	"list",
 	"get",
@@ -67,7 +69,11 @@ const safeRepeatActions = new Set([
 	"process.output",
 	"process.stream",
 	"logs.stream",
-	"file.download"
+	"file.download",
+	"snapshot.list",
+	"snapshot.get",
+	"snapshot.waitUntilReady",
+	"snapshot.delete"
 ]);
 const sandboxTransportFailureMessage = (action) => {
 	switch (action) {
@@ -77,6 +83,8 @@ const sandboxTransportFailureMessage = (action) => {
 		case "exec": return "The sandbox command may have run. Inspect its external effects before running it again";
 		case "process.start": return "A sandbox process may be running. List processes and reconcile before starting another";
 		case "process.signal": return "The sandbox process signal may have been delivered. Get or wait for the process before sending another";
+		case "snapshot.create": return "Snapshot creation may have started and a retry may create a second snapshot. Check snapshots.list() before creating another";
+		case "snapshot.delete": return "Snapshot deletion may have started. Repeating Delete is safe";
 		default: return "Compute is temporarily unavailable. Retry this operation";
 	}
 };
@@ -93,11 +101,13 @@ var SandboxRestTransport = class {
 			body: options.body === void 0 ? void 0 : JSON.stringify(options.body),
 			headers: options.body === void 0 ? void 0 : { "Content-Type": "application/json" },
 			sandboxId: options.sandboxId,
-			processId: options.processId
+			processId: options.processId,
+			snapshotId: options.snapshotId,
+			signal: options.signal
 		});
-		if (!options.statuses.includes(response.status)) await this.throwResponseError(action, response, options.sandboxId, options.processId);
+		if (!options.statuses.includes(response.status)) await this.throwResponseError(action, response, options.sandboxId, options.processId, options.snapshotId);
 		if (response.status === 204) return { status: response.status };
-		const raw = await this.readResponseJSON(action, response, options.sandboxId, options.processId);
+		const raw = await this.readResponseJSON(action, response, options.sandboxId, options.processId, options.snapshotId);
 		return {
 			status: response.status,
 			envelope: parseWithSchema(responseEnvelopeSchema, raw, "sandbox API response")
@@ -105,11 +115,11 @@ var SandboxRestTransport = class {
 	}
 	async raw(action, method, path, options) {
 		const response = await this.send(action, method, path, options);
-		if (!response.ok) await this.throwResponseError(action, response, options.sandboxId, options.processId);
+		if (!response.ok) await this.throwResponseError(action, response, options.sandboxId, options.processId, options.snapshotId);
 		return response;
 	}
-	async readResponseEnvelope(action, response, sandboxId, processId) {
-		return parseWithSchema(responseEnvelopeSchema, await this.readResponseJSON(action, response, sandboxId, processId), "sandbox API response");
+	async readResponseEnvelope(action, response, sandboxId, processId, snapshotId) {
+		return parseWithSchema(responseEnvelopeSchema, await this.readResponseJSON(action, response, sandboxId, processId, snapshotId), "sandbox API response");
 	}
 	async stream(action, path, sandboxId, processId) {
 		const abortController = new AbortController();
@@ -187,17 +197,17 @@ var SandboxRestTransport = class {
 		try {
 			return await this.config.fetch()(new URL(path, this.config.baseUrl()), requestInit);
 		} catch (error) {
-			throw this.transportFailure(action, error, options.sandboxId, options.processId);
+			throw this.transportFailure(action, error, options.sandboxId, options.processId, options.snapshotId);
 		}
 	}
-	async readResponseJSON(action, response, sandboxId, processId) {
+	async readResponseJSON(action, response, sandboxId, processId, snapshotId) {
 		try {
 			return await response.json();
 		} catch (error) {
-			throw this.transportFailure(action, error, sandboxId, processId);
+			throw this.transportFailure(action, error, sandboxId, processId, snapshotId);
 		}
 	}
-	transportFailure(action, cause, sandboxId, processId) {
+	transportFailure(action, cause, sandboxId, processId, snapshotId) {
 		const safeToRepeat = safeRepeatActions.has(action);
 		return new SandboxError({
 			action,
@@ -205,22 +215,23 @@ var SandboxRestTransport = class {
 			message: sandboxTransportFailureMessage(action),
 			sandboxId,
 			processId,
+			snapshotId,
 			ambiguous: !safeToRepeat,
 			retryable: safeToRepeat,
 			details: [],
 			cause
 		});
 	}
-	async throwResponseError(action, response, sandboxId, processId) {
+	async throwResponseError(action, response, sandboxId, processId, snapshotId) {
 		const raw = await response.json().catch(() => void 0);
 		const parsed = errorEnvelopeSchema.safeParse(raw);
 		const item = parsed.success ? parsed.data.errors[0] : {
 			code: "internal_error",
 			message: `Sandbox API returned HTTP ${response.status}`
 		};
-		throw this.errorFromItem(action, response.status, item, sandboxId, processId, response.headers.get("x-request-id") ?? void 0, parsed.success ? parsed.data.errors : []);
+		throw this.errorFromItem(action, response.status, item, sandboxId, processId, snapshotId, response.headers.get("x-request-id") ?? void 0, parsed.success ? parsed.data.errors : []);
 	}
-	errorFromItem(action, status, item, sandboxId, processId, requestId, details = []) {
+	errorFromItem(action, status, item, sandboxId, processId, snapshotId, requestId, details = []) {
 		const ambiguous = item.code === "operation_ambiguous" || item.code === "sandbox_exec_output_too_large" || item.code === "sandbox_exec_timed_out";
 		const availability = item.code === "compute_unavailable" || item.code === "rate_limited" || status === 429 || status === 503;
 		return new SandboxError({
@@ -230,6 +241,7 @@ var SandboxRestTransport = class {
 			status,
 			sandboxId,
 			processId,
+			snapshotId,
 			ambiguous,
 			retryable: !ambiguous && availability,
 			requestId,
@@ -241,6 +253,18 @@ const processPath = (sandboxId, processId) => `/v2/sandboxes/${encodeURIComponen
 const sandboxStartingStatuses = new Set(["PENDING", "STARTING"]);
 const sandboxRunningPollIntervalMs = 1e3;
 const delay = async (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+const lifecycleTimeout = (options) => normalizeSandboxWaitUntilRunningOptions({ timeout: options?.timeout ?? 5 * 6e4 }).timeoutMs;
+const abortableDelay = (milliseconds, signal) => new Promise((resolve, reject) => {
+	if (signal?.aborted) {
+		reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+		return;
+	}
+	const timer = setTimeout(resolve, milliseconds);
+	signal?.addEventListener("abort", () => {
+		clearTimeout(timer);
+		reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+	}, { once: true });
+});
 const sandboxStartFailedError = (action, sandbox) => new SandboxError({
 	action,
 	code: "sandbox_start_failed",
@@ -319,6 +343,48 @@ const runSandboxCommandForOperation = (sandbox, command, options) => {
 	if (!run) throw new SandboxValidationError("Sandbox commands can only run on an SDK sandbox resource");
 	return run(command, options);
 };
+const pollSandboxStatus = async (initial, target, action, transport, options) => {
+	const timeoutMs = lifecycleTimeout(options);
+	const deadline = Date.now() + timeoutMs;
+	let current = initial;
+	while (current.status !== target) {
+		if (["FAILED", "TERMINATED"].includes(current.status)) throw new SandboxError({
+			action,
+			code: "invalid_request",
+			message: `Sandbox entered ${current.status} before reaching ${target}`,
+			sandboxId: current.id
+		});
+		const remaining = deadline - Date.now();
+		if (remaining <= 0) throw new SandboxError({
+			action,
+			code: "sandbox_start_timed_out",
+			message: `Sandbox did not reach ${target} within ${timeoutMs} milliseconds`,
+			sandboxId: current.id
+		});
+		await abortableDelay(Math.min(1e3, remaining), options?.signal);
+		const { envelope } = await transport.json(action, "GET", `/v2/sandboxes/${encodeURIComponent(current.id)}`, {
+			statuses: [200],
+			sandboxId: current.id,
+			signal: options?.signal
+		});
+		current = sandboxRefFromResource(envelope?.data);
+		if (current.id !== initial.id || current.name !== initial.name) throw new SandboxValidationError("Sandbox lifecycle operation returned an unrelated sandbox");
+	}
+	return createDirectSandboxFacade(current, transport);
+};
+const createDirectSnapshotFacade = (rawRef, transport) => {
+	const ref = sandboxSnapshotRefFromResource(rawRef);
+	return Object.freeze({
+		...ref,
+		resources: Object.freeze({ ...ref.resources }),
+		clone: async (options, waitOptions) => createSandbox(transport, {
+			name: options.name,
+			snapshotId: ref.id,
+			runningTimeout: options.runningTimeout ?? waitOptions?.timeout
+		}),
+		delete: async () => deleteSandboxSnapshot(transport, ref.id)
+	});
+};
 const createDirectSandboxFacade = (rawRef, transport) => {
 	const ref = parseWithSchema(sandboxRefSchema, rawRef, "sandbox reference");
 	const basePath = `/v2/sandboxes/${encodeURIComponent(ref.id)}`;
@@ -424,6 +490,34 @@ const createDirectSandboxFacade = (rawRef, transport) => {
 			}
 		}),
 		waitUntilRunning: async (options) => waitUntilSandboxRunning(ref, normalizeSandboxWaitUntilRunningOptions(options).timeoutMs, transport, "waitUntilRunning"),
+		pause: async (options) => {
+			const { envelope } = await transport.json("pause", "POST", `${basePath}/pause`, {
+				statuses: [
+					200,
+					201,
+					202
+				],
+				sandboxId: ref.id,
+				signal: options?.signal
+			});
+			return pollSandboxStatus(envelope?.data === void 0 ? ref : sandboxRefFromResource(envelope.data), "PAUSED", "pause", transport, options);
+		},
+		resume: async (options) => {
+			const { envelope } = await transport.json("resume", "POST", `${basePath}/resume`, {
+				statuses: [
+					200,
+					201,
+					202
+				],
+				sandboxId: ref.id,
+				signal: options?.signal
+			});
+			return pollSandboxStatus(envelope?.data === void 0 ? ref : sandboxRefFromResource(envelope.data), "RUNNING", "resume", transport, options);
+		},
+		snapshot: async (options = {}, waitOptions) => {
+			normalizeSandboxSnapshotCreateOptions(options);
+			return createDirectSnapshotFacade(await waitUntilSandboxSnapshotReady(transport, await createSandboxSnapshot(transport, ref.id, waitOptions?.signal), lifecycleTimeout(waitOptions), waitOptions?.signal), transport);
+		},
 		destroy: async () => {
 			const { status, envelope } = await transport.json("destroy", "DELETE", basePath, {
 				statuses: [202, 204],
@@ -480,23 +574,123 @@ const transportForClient = (client) => {
 */
 const sandboxForOperation = (client, ref) => createDirectSandboxFacade(ref, transportForClient(client));
 const sandboxProcessForOperation = (client, ref) => createDirectProcessFacade(ref, transportForClient(client));
+const getSnapshotForOperation = async (transport, snapshotId, action) => {
+	try {
+		const { envelope } = await transport.json(action, "GET", `/v2/snapshots/${encodeURIComponent(snapshotId)}`, {
+			statuses: [200],
+			snapshotId
+		});
+		return sandboxSnapshotRefFromResource(envelope?.data);
+	} catch (error) {
+		if (error instanceof SandboxError && error.code === "sandbox_snapshot_not_found") return null;
+		throw error;
+	}
+};
+const createSandboxSnapshot = async (transport, sandboxId, signal) => {
+	const { status, envelope } = await transport.json("snapshot.create", "POST", `/v2/sandboxes/${encodeURIComponent(sandboxId)}/snapshots`, {
+		body: {},
+		statuses: [201, 202],
+		sandboxId,
+		signal
+	});
+	const snapshot = sandboxSnapshotRefFromResource(envelope?.data);
+	if (status === 201 && snapshot.status !== "READY" || status === 202 && snapshot.status !== "CREATING") throw new SandboxValidationError(`Sandbox snapshot Create returned HTTP ${status} with status ${snapshot.status}`);
+	return snapshot;
+};
+const listSandboxSnapshots = async (transport, options) => {
+	const normalized = normalizeSandboxSnapshotListOptions(options);
+	const query = new URLSearchParams({ limit: `${normalized.limit}` });
+	if (normalized.cursor !== void 0) query.set("cursor", normalized.cursor);
+	const { envelope } = await transport.json("snapshot.list", "GET", `/v2/snapshots?${query}`, { statuses: [200] });
+	const resources = parseWithSchema(z.array(z.unknown()), envelope?.data, "sandbox snapshot list");
+	const page = parseWithSchema(sandboxPageSchema, envelope?.page, "sandbox snapshot list page");
+	const metadata = parseWithSchema(metadataSchema, envelope?.metadata, "sandbox snapshot list metadata");
+	return {
+		items: resources.map(sandboxSnapshotRefFromResource),
+		page: {
+			hasMore: page.hasMore,
+			limit: page.limit,
+			...page.cursor != null && { cursor: page.cursor }
+		},
+		fetchedAt: metadata.fetchedAt
+	};
+};
+const createSandboxSnapshotForOperation = async (client, sandboxId) => createSandboxSnapshot(transportForClient(client), sandboxId);
+const listSandboxSnapshotsForOperation = async (client, options) => listSandboxSnapshots(transportForClient(client), options);
+const getSandboxSnapshotForOperation = async (client, snapshotId) => getSnapshotForOperation(transportForClient(client), snapshotId, "snapshot.get");
+const snapshotNotReadyError = (snapshot) => new SandboxError({
+	action: "snapshot.waitUntilReady",
+	code: "sandbox_snapshot_not_ready",
+	message: `Snapshot entered ${snapshot.status} before reaching READY`,
+	snapshotId: snapshot.id,
+	retryable: false,
+	details: [{ status: snapshot.status }]
+});
+const snapshotWaitTimedOutError = (snapshot, timeoutMs) => new SandboxError({
+	action: "snapshot.waitUntilReady",
+	code: "sandbox_snapshot_wait_timed_out",
+	message: `Snapshot did not reach READY within ${timeoutMs} milliseconds`,
+	snapshotId: snapshot.id,
+	retryable: false,
+	details: [{
+		status: snapshot.status,
+		timeoutMs
+	}]
+});
+const waitUntilSandboxSnapshotReady = async (transport, initialSnapshot, timeoutMs, signal) => {
+	let snapshot = parseWithSchema(sandboxSnapshotRefSchema, initialSnapshot, "sandbox snapshot reference");
+	if (snapshot.status === "READY") return snapshot;
+	if (snapshot.status !== "CREATING") throw snapshotNotReadyError(snapshot);
+	const deadline = Date.now() + timeoutMs;
+	for (;;) {
+		if (deadline - Date.now() <= 0) throw snapshotWaitTimedOutError(snapshot, timeoutMs);
+		try {
+			const current = await getSnapshotForOperation(transport, snapshot.id, "snapshot.waitUntilReady");
+			if (!current) throw new SandboxError({
+				action: "snapshot.waitUntilReady",
+				code: "sandbox_snapshot_not_found",
+				message: "Snapshot not found",
+				snapshotId: snapshot.id,
+				retryable: false
+			});
+			snapshot = current;
+		} catch (error) {
+			if (!(error instanceof SandboxError && error.retryable)) throw error;
+		}
+		if (snapshot.status === "READY") return snapshot;
+		if (snapshot.status !== "CREATING") throw snapshotNotReadyError(snapshot);
+		const remainingMs = deadline - Date.now();
+		if (remainingMs <= 0) throw snapshotWaitTimedOutError(snapshot, timeoutMs);
+		await abortableDelay(Math.min(sandboxRunningPollIntervalMs, remainingMs), signal);
+	}
+};
+const waitUntilSandboxSnapshotReadyForOperation = async (client, initialSnapshot, timeoutMs) => waitUntilSandboxSnapshotReady(transportForClient(client), initialSnapshot, timeoutMs);
+const deleteSandboxSnapshot = async (transport, snapshotId) => {
+	await transport.json("snapshot.delete", "DELETE", `/v2/snapshots/${encodeURIComponent(snapshotId)}`, {
+		statuses: [204],
+		snapshotId
+	});
+};
+const deleteSandboxSnapshotForOperation = async (client, snapshotId) => deleteSandboxSnapshot(transportForClient(client), snapshotId);
+const createSandbox = async (transport, options) => {
+	const { runningTimeoutMs, ...body } = normalizeSandboxCreateOptions(options);
+	const { status, envelope } = await transport.json("create", "POST", "/v2/sandboxes", {
+		body,
+		statuses: [
+			200,
+			201,
+			202
+		]
+	});
+	const sandbox = sandboxRefFromResource(envelope?.data);
+	if (status === 201 && sandbox.status !== "RUNNING" || status === 202 && sandbox.status !== "STARTING") throw new SandboxValidationError(`Sandbox Create returned HTTP ${status} with status ${sandbox.status}`);
+	return runningTimeoutMs === false ? createDirectSandboxFacade(sandbox, transport) : waitUntilSandboxRunning(sandbox, runningTimeoutMs, transport, "create");
+};
+const createSandboxForOperation = async (client, options) => createSandbox(transportForClient(client), options);
 const createSandboxClient = (config) => {
 	const transport = new SandboxRestTransport(config);
 	const client = {
-		create: async (options) => {
-			const { runningTimeoutMs, ...body } = normalizeSandboxCreateOptions(options);
-			const { status, envelope } = await transport.json("create", "POST", "/v2/sandboxes", {
-				body,
-				statuses: [
-					200,
-					201,
-					202
-				]
-			});
-			const sandbox = sandboxRefFromResource(envelope?.data);
-			if (status === 201 && sandbox.status !== "RUNNING" || status === 202 && sandbox.status !== "STARTING") throw new SandboxValidationError(`Sandbox Create returned HTTP ${status} with status ${sandbox.status}`);
-			return runningTimeoutMs === false ? createDirectSandboxFacade(sandbox, transport) : waitUntilSandboxRunning(sandbox, runningTimeoutMs, transport, "create");
-		},
+		create: async (options) => createSandbox(transport, options),
 		list: async (options) => {
 			const normalized = normalizeSandboxListOptions(options);
 			const query = new URLSearchParams({ limit: `${normalized.limit}` });
@@ -527,12 +721,26 @@ const createSandboxClient = (config) => {
 				if (error instanceof SandboxError && error.code === "sandbox_not_found") return null;
 				throw error;
 			}
-		}
+		},
+		snapshots: Object.freeze({
+			list: async (options) => {
+				const result = await listSandboxSnapshots(transport, options);
+				return {
+					items: result.items.map((snapshot) => createDirectSnapshotFacade(snapshot, transport)),
+					page: { ...result.page },
+					fetchedAt: result.fetchedAt
+				};
+			},
+			get: async (snapshotId) => {
+				const snapshot = await getSnapshotForOperation(transport, parseWithSchema(canonicalUuidSchema, snapshotId, "sandbox snapshot ID"), "snapshot.get");
+				return snapshot ? createDirectSnapshotFacade(snapshot, transport) : null;
+			}
+		})
 	};
 	sandboxClientTransports.set(client, transport);
 	return client;
 };
 
 //#endregion
-export { createSandboxClient, runSandboxCommandForOperation, sandboxForOperation, sandboxProcessForOperation };
+export { createSandboxClient, createSandboxForOperation, createSandboxSnapshotForOperation, deleteSandboxSnapshotForOperation, getSandboxSnapshotForOperation, listSandboxSnapshotsForOperation, runSandboxCommandForOperation, sandboxForOperation, sandboxProcessForOperation, waitUntilSandboxSnapshotReadyForOperation };
 //# sourceMappingURL=client.js.map