@cloudflare/sandbox 0.6.1 → 0.6.4

package/dist/index.js

@@ -1,120 +1,7 @@
-import { a as createLogger, c as Execution, d as getEnvString, i as shellEscape, l as ResultImpl, n as isProcess, o as createNoOpLogger, r as isProcessStatus, s as TraceContext, t as isExecResult, u as GitLogger } from "./dist-gVyG2H2h.js";
+import { a as shellEscape, c as TraceContext, d as GitLogger, f as getEnvString, i as isTerminalStatus, l as Execution, n as isProcess, o as createLogger, r as isProcessStatus, s as createNoOpLogger, t as isExecResult, u as ResultImpl } from "./dist-2SF6oOaz.js";
+import { t as ErrorCode } from "./errors-BHN41iBd.js";
 import { Container, getContainer, switchPort } from "@cloudflare/containers";
 
-//#region ../shared/dist/errors/codes.js
-/**
-* Centralized error code registry
-* Each code maps to a specific error type with consistent semantics
-*/
-const ErrorCode = {
-	FILE_NOT_FOUND: "FILE_NOT_FOUND",
-	PERMISSION_DENIED: "PERMISSION_DENIED",
-	FILE_EXISTS: "FILE_EXISTS",
-	IS_DIRECTORY: "IS_DIRECTORY",
-	NOT_DIRECTORY: "NOT_DIRECTORY",
-	NO_SPACE: "NO_SPACE",
-	TOO_MANY_FILES: "TOO_MANY_FILES",
-	RESOURCE_BUSY: "RESOURCE_BUSY",
-	READ_ONLY: "READ_ONLY",
-	NAME_TOO_LONG: "NAME_TOO_LONG",
-	TOO_MANY_LINKS: "TOO_MANY_LINKS",
-	FILESYSTEM_ERROR: "FILESYSTEM_ERROR",
-	COMMAND_NOT_FOUND: "COMMAND_NOT_FOUND",
-	COMMAND_PERMISSION_DENIED: "COMMAND_PERMISSION_DENIED",
-	INVALID_COMMAND: "INVALID_COMMAND",
-	COMMAND_EXECUTION_ERROR: "COMMAND_EXECUTION_ERROR",
-	STREAM_START_ERROR: "STREAM_START_ERROR",
-	PROCESS_NOT_FOUND: "PROCESS_NOT_FOUND",
-	PROCESS_PERMISSION_DENIED: "PROCESS_PERMISSION_DENIED",
-	PROCESS_ERROR: "PROCESS_ERROR",
-	PORT_ALREADY_EXPOSED: "PORT_ALREADY_EXPOSED",
-	PORT_IN_USE: "PORT_IN_USE",
-	PORT_NOT_EXPOSED: "PORT_NOT_EXPOSED",
-	INVALID_PORT_NUMBER: "INVALID_PORT_NUMBER",
-	INVALID_PORT: "INVALID_PORT",
-	SERVICE_NOT_RESPONDING: "SERVICE_NOT_RESPONDING",
-	PORT_OPERATION_ERROR: "PORT_OPERATION_ERROR",
-	CUSTOM_DOMAIN_REQUIRED: "CUSTOM_DOMAIN_REQUIRED",
-	GIT_REPOSITORY_NOT_FOUND: "GIT_REPOSITORY_NOT_FOUND",
-	GIT_BRANCH_NOT_FOUND: "GIT_BRANCH_NOT_FOUND",
-	GIT_AUTH_FAILED: "GIT_AUTH_FAILED",
-	GIT_NETWORK_ERROR: "GIT_NETWORK_ERROR",
-	INVALID_GIT_URL: "INVALID_GIT_URL",
-	GIT_CLONE_FAILED: "GIT_CLONE_FAILED",
-	GIT_CHECKOUT_FAILED: "GIT_CHECKOUT_FAILED",
-	GIT_OPERATION_FAILED: "GIT_OPERATION_FAILED",
-	BUCKET_MOUNT_ERROR: "BUCKET_MOUNT_ERROR",
-	S3FS_MOUNT_ERROR: "S3FS_MOUNT_ERROR",
-	MISSING_CREDENTIALS: "MISSING_CREDENTIALS",
-	INVALID_MOUNT_CONFIG: "INVALID_MOUNT_CONFIG",
-	INTERPRETER_NOT_READY: "INTERPRETER_NOT_READY",
-	CONTEXT_NOT_FOUND: "CONTEXT_NOT_FOUND",
-	CODE_EXECUTION_ERROR: "CODE_EXECUTION_ERROR",
-	PYTHON_NOT_AVAILABLE: "PYTHON_NOT_AVAILABLE",
-	VALIDATION_FAILED: "VALIDATION_FAILED",
-	INVALID_JSON_RESPONSE: "INVALID_JSON_RESPONSE",
-	UNKNOWN_ERROR: "UNKNOWN_ERROR",
-	INTERNAL_ERROR: "INTERNAL_ERROR"
-};
-
-//#endregion
-//#region ../shared/dist/errors/status-map.js
-/**
-* Maps error codes to HTTP status codes
-* Centralized mapping ensures consistency across SDK
-*/
-const ERROR_STATUS_MAP = {
-	[ErrorCode.FILE_NOT_FOUND]: 404,
-	[ErrorCode.COMMAND_NOT_FOUND]: 404,
-	[ErrorCode.PROCESS_NOT_FOUND]: 404,
-	[ErrorCode.PORT_NOT_EXPOSED]: 404,
-	[ErrorCode.GIT_REPOSITORY_NOT_FOUND]: 404,
-	[ErrorCode.GIT_BRANCH_NOT_FOUND]: 404,
-	[ErrorCode.CONTEXT_NOT_FOUND]: 404,
-	[ErrorCode.IS_DIRECTORY]: 400,
-	[ErrorCode.NOT_DIRECTORY]: 400,
-	[ErrorCode.INVALID_COMMAND]: 400,
-	[ErrorCode.INVALID_PORT_NUMBER]: 400,
-	[ErrorCode.INVALID_PORT]: 400,
-	[ErrorCode.INVALID_GIT_URL]: 400,
-	[ErrorCode.CUSTOM_DOMAIN_REQUIRED]: 400,
-	[ErrorCode.INVALID_JSON_RESPONSE]: 400,
-	[ErrorCode.NAME_TOO_LONG]: 400,
-	[ErrorCode.VALIDATION_FAILED]: 400,
-	[ErrorCode.MISSING_CREDENTIALS]: 400,
-	[ErrorCode.INVALID_MOUNT_CONFIG]: 400,
-	[ErrorCode.GIT_AUTH_FAILED]: 401,
-	[ErrorCode.PERMISSION_DENIED]: 403,
-	[ErrorCode.COMMAND_PERMISSION_DENIED]: 403,
-	[ErrorCode.PROCESS_PERMISSION_DENIED]: 403,
-	[ErrorCode.READ_ONLY]: 403,
-	[ErrorCode.FILE_EXISTS]: 409,
-	[ErrorCode.PORT_ALREADY_EXPOSED]: 409,
-	[ErrorCode.PORT_IN_USE]: 409,
-	[ErrorCode.RESOURCE_BUSY]: 409,
-	[ErrorCode.SERVICE_NOT_RESPONDING]: 502,
-	[ErrorCode.GIT_NETWORK_ERROR]: 502,
-	[ErrorCode.PYTHON_NOT_AVAILABLE]: 501,
-	[ErrorCode.INTERPRETER_NOT_READY]: 503,
-	[ErrorCode.NO_SPACE]: 500,
-	[ErrorCode.TOO_MANY_FILES]: 500,
-	[ErrorCode.TOO_MANY_LINKS]: 500,
-	[ErrorCode.FILESYSTEM_ERROR]: 500,
-	[ErrorCode.COMMAND_EXECUTION_ERROR]: 500,
-	[ErrorCode.STREAM_START_ERROR]: 500,
-	[ErrorCode.PROCESS_ERROR]: 500,
-	[ErrorCode.PORT_OPERATION_ERROR]: 500,
-	[ErrorCode.GIT_CLONE_FAILED]: 500,
-	[ErrorCode.GIT_CHECKOUT_FAILED]: 500,
-	[ErrorCode.GIT_OPERATION_FAILED]: 500,
-	[ErrorCode.CODE_EXECUTION_ERROR]: 500,
-	[ErrorCode.BUCKET_MOUNT_ERROR]: 500,
-	[ErrorCode.S3FS_MOUNT_ERROR]: 500,
-	[ErrorCode.UNKNOWN_ERROR]: 500,
-	[ErrorCode.INTERNAL_ERROR]: 500
-};
-
-//#endregion
 //#region src/errors/classes.ts
 /**
 * Base SDK error that wraps ErrorResponse
@@ -283,6 +170,18 @@ var ProcessError = class extends SandboxError {
 	}
 };
 /**
+* Error thrown when a session already exists
+*/
+var SessionAlreadyExistsError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "SessionAlreadyExistsError";
+	}
+	get sessionId() {
+		return this.context.sessionId;
+	}
+};
+/**
 * Error thrown when a port is already exposed
 */
 var PortAlreadyExposedError = class extends SandboxError {
@@ -570,6 +469,48 @@ var ValidationFailedError = class extends SandboxError {
 		return this.context.validationErrors;
 	}
 };
+/**
+* Error thrown when a process does not become ready within the timeout period
+*/
+var ProcessReadyTimeoutError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "ProcessReadyTimeoutError";
+	}
+	get processId() {
+		return this.context.processId;
+	}
+	get command() {
+		return this.context.command;
+	}
+	get condition() {
+		return this.context.condition;
+	}
+	get timeout() {
+		return this.context.timeout;
+	}
+};
+/**
+* Error thrown when a process exits before becoming ready
+*/
+var ProcessExitedBeforeReadyError = class extends SandboxError {
+	constructor(errorResponse) {
+		super(errorResponse);
+		this.name = "ProcessExitedBeforeReadyError";
+	}
+	get processId() {
+		return this.context.processId;
+	}
+	get command() {
+		return this.context.command;
+	}
+	get condition() {
+		return this.context.condition;
+	}
+	get exitCode() {
+		return this.context.exitCode;
+	}
+};
 
 //#endregion
 //#region src/errors/adapter.ts
@@ -599,6 +540,7 @@ function createErrorFromResponse(errorResponse) {
 		case ErrorCode.PROCESS_NOT_FOUND: return new ProcessNotFoundError(errorResponse);
 		case ErrorCode.PROCESS_PERMISSION_DENIED:
 		case ErrorCode.PROCESS_ERROR: return new ProcessError(errorResponse);
+		case ErrorCode.SESSION_ALREADY_EXISTS: return new SessionAlreadyExistsError(errorResponse);
 		case ErrorCode.PORT_ALREADY_EXPOSED: return new PortAlreadyExposedError(errorResponse);
 		case ErrorCode.PORT_NOT_EXPOSED: return new PortNotExposedError(errorResponse);
 		case ErrorCode.INVALID_PORT_NUMBER:
@@ -747,7 +689,7 @@ var BaseHttpClient = class {
 	* Utility method to log successful operations
 	*/
 	logSuccess(operation, details) {
-		this.logger.info(`${operation} completed successfully`, details ? { details } : void 0);
+		this.logger.info(operation, details ? { details } : void 0);
 	}
 	/**
 	* Utility method to log errors intelligently
@@ -1371,6 +1313,20 @@ var PortClient = class extends BaseHttpClient {
 			throw error;
 		}
 	}
+	/**
+	* Check if a port is ready to accept connections
+	* @param request - Port check configuration
+	*/
+	async checkPortReady(request) {
+		try {
+			return await this.post("/api/port-check", request);
+		} catch (error) {
+			return {
+				ready: false,
+				error: error instanceof Error ? error.message : "Port check failed"
+			};
+		}
+	}
 };
 
 //#endregion
@@ -2063,7 +2019,7 @@ function resolveS3fsOptions(provider, userOptions) {
 * This file is auto-updated by .github/changeset-version.ts during releases
 * DO NOT EDIT MANUALLY - Changes will be overwritten on the next version bump
 */
-const SDK_VERSION = "0.6.1";
+const SDK_VERSION = "0.6.4";
 
 //#endregion
 //#region src/sandbox.ts
@@ -2511,24 +2467,23 @@ var Sandbox = class extends Container {
 	* we reuse it instead of trying to create a new one.
 	*/
 	async ensureDefaultSession() {
-		if (!this.defaultSession) {
-			const sessionId = `sandbox-${this.sandboxName || "default"}`;
-			try {
-				await this.client.utils.createSession({
-					id: sessionId,
-					env: this.envVars || {},
-					cwd: "/workspace"
-				});
+		const sessionId = `sandbox-${this.sandboxName || "default"}`;
+		if (this.defaultSession === sessionId) return this.defaultSession;
+		try {
+			await this.client.utils.createSession({
+				id: sessionId,
+				env: this.envVars || {},
+				cwd: "/workspace"
+			});
+			this.defaultSession = sessionId;
+			await this.ctx.storage.put("defaultSession", sessionId);
+			this.logger.debug("Default session initialized", { sessionId });
+		} catch (error) {
+			if (error instanceof SessionAlreadyExistsError) {
+				this.logger.debug("Session exists in container but not in DO state, syncing", { sessionId });
 				this.defaultSession = sessionId;
 				await this.ctx.storage.put("defaultSession", sessionId);
-				this.logger.debug("Default session initialized", { sessionId });
-			} catch (error) {
-				if (error instanceof Error && error.message.includes("already exists")) {
-					this.logger.debug("Reusing existing session after reload", { sessionId });
-					this.defaultSession = sessionId;
-					await this.ctx.storage.put("defaultSession", sessionId);
-				} else throw error;
-			}
+			} else throw error;
 		}
 		return this.defaultSession;
 	}
@@ -2645,9 +2600,209 @@ var Sandbox = class extends Container {
 					stdout: logs.stdout,
 					stderr: logs.stderr
 				};
+			},
+			waitForLog: async (pattern, timeout) => {
+				return this.waitForLogPattern(data.id, data.command, pattern, timeout);
+			},
+			waitForPort: async (port, options) => {
+				await this.waitForPortReady(data.id, data.command, port, options);
 			}
 		};
 	}
+	/**
+	* Wait for a log pattern to appear in process output
+	*/
+	async waitForLogPattern(processId, command, pattern, timeout) {
+		const startTime = Date.now();
+		const conditionStr = this.conditionToString(pattern);
+		let collectedStdout = "";
+		let collectedStderr = "";
+		try {
+			const existingLogs = await this.getProcessLogs(processId);
+			collectedStdout = existingLogs.stdout;
+			if (collectedStdout && !collectedStdout.endsWith("\n")) collectedStdout += "\n";
+			collectedStderr = existingLogs.stderr;
+			if (collectedStderr && !collectedStderr.endsWith("\n")) collectedStderr += "\n";
+			const stdoutResult = this.matchPattern(existingLogs.stdout, pattern);
+			if (stdoutResult) return stdoutResult;
+			const stderrResult = this.matchPattern(existingLogs.stderr, pattern);
+			if (stderrResult) return stderrResult;
+		} catch (error) {
+			this.logger.debug("Could not get existing logs, will stream", {
+				processId,
+				error: error instanceof Error ? error.message : String(error)
+			});
+		}
+		const stream = await this.streamProcessLogs(processId);
+		let timeoutId;
+		let timeoutPromise;
+		if (timeout !== void 0) {
+			const remainingTime = timeout - (Date.now() - startTime);
+			if (remainingTime <= 0) throw this.createReadyTimeoutError(processId, command, conditionStr, timeout);
+			timeoutPromise = new Promise((_, reject) => {
+				timeoutId = setTimeout(() => {
+					reject(this.createReadyTimeoutError(processId, command, conditionStr, timeout));
+				}, remainingTime);
+			});
+		}
+		try {
+			const streamProcessor = async () => {
+				const DEBOUNCE_MS = 50;
+				let lastCheckTime = 0;
+				let pendingCheck = false;
+				const checkPattern = () => {
+					const stdoutResult = this.matchPattern(collectedStdout, pattern);
+					if (stdoutResult) return stdoutResult;
+					const stderrResult = this.matchPattern(collectedStderr, pattern);
+					if (stderrResult) return stderrResult;
+					return null;
+				};
+				for await (const event of parseSSEStream(stream)) {
+					if (event.type === "stdout" || event.type === "stderr") {
+						const data = event.data || "";
+						if (event.type === "stdout") collectedStdout += data;
+						else collectedStderr += data;
+						pendingCheck = true;
+						const now = Date.now();
+						if (now - lastCheckTime >= DEBOUNCE_MS) {
+							lastCheckTime = now;
+							pendingCheck = false;
+							const result = checkPattern();
+							if (result) return result;
+						}
+					}
+					if (event.type === "exit") {
+						if (pendingCheck) {
+							const result = checkPattern();
+							if (result) return result;
+						}
+						throw this.createExitedBeforeReadyError(processId, command, conditionStr, event.exitCode ?? 1);
+					}
+				}
+				if (pendingCheck) {
+					const result = checkPattern();
+					if (result) return result;
+				}
+				throw this.createExitedBeforeReadyError(processId, command, conditionStr, 0);
+			};
+			if (timeoutPromise) return await Promise.race([streamProcessor(), timeoutPromise]);
+			return await streamProcessor();
+		} finally {
+			if (timeoutId) clearTimeout(timeoutId);
+		}
+	}
+	/**
+	* Wait for a port to become available (for process readiness checking)
+	*/
+	async waitForPortReady(processId, command, port, options) {
+		const { mode = "http", path = "/", status = {
+			min: 200,
+			max: 399
+		}, timeout, interval = 500 } = options ?? {};
+		const startTime = Date.now();
+		const conditionStr = mode === "http" ? `port ${port} (HTTP ${path})` : `port ${port} (TCP)`;
+		const targetInterval = interval;
+		let checkCount = 0;
+		const checkRequest = {
+			port,
+			mode,
+			path,
+			statusMin: typeof status === "number" ? status : status.min,
+			statusMax: typeof status === "number" ? status : status.max
+		};
+		while (true) {
+			if (timeout !== void 0) {
+				if (timeout - (Date.now() - startTime) <= 0) throw this.createReadyTimeoutError(processId, command, conditionStr, timeout);
+			}
+			const iterationStart = Date.now();
+			if (checkCount % 3 === 0) {
+				const processInfo = await this.getProcess(processId);
+				if (!processInfo || isTerminalStatus(processInfo.status)) throw this.createExitedBeforeReadyError(processId, command, conditionStr, processInfo?.exitCode ?? 1);
+			}
+			try {
+				if ((await this.client.ports.checkPortReady(checkRequest)).ready) return;
+			} catch {}
+			checkCount++;
+			const iterationDuration = Date.now() - iterationStart;
+			const sleepTime = Math.max(0, targetInterval - iterationDuration);
+			if (sleepTime > 0) {
+				if (timeout === void 0 || Date.now() - startTime + sleepTime < timeout) await new Promise((resolve) => setTimeout(resolve, sleepTime));
+			}
+		}
+	}
+	/**
+	* Match a pattern against text
+	*/
+	matchPattern(text, pattern) {
+		if (typeof pattern === "string") {
+			if (text.includes(pattern)) {
+				const lines = text.split("\n");
+				for (const line of lines) if (line.includes(pattern)) return { line };
+				return { line: pattern };
+			}
+		} else {
+			const safePattern = new RegExp(pattern.source, pattern.flags.replace("g", ""));
+			const match = text.match(safePattern);
+			if (match) {
+				const lines = text.split("\n");
+				for (const line of lines) {
+					const lineMatch = line.match(safePattern);
+					if (lineMatch) return {
+						line,
+						match: lineMatch
+					};
+				}
+				return {
+					line: match[0],
+					match
+				};
+			}
+		}
+		return null;
+	}
+	/**
+	* Convert a log pattern to a human-readable string
+	*/
+	conditionToString(pattern) {
+		if (typeof pattern === "string") return `"${pattern}"`;
+		return pattern.toString();
+	}
+	/**
+	* Create a ProcessReadyTimeoutError
+	*/
+	createReadyTimeoutError(processId, command, condition, timeout) {
+		return new ProcessReadyTimeoutError({
+			code: ErrorCode.PROCESS_READY_TIMEOUT,
+			message: `Process did not become ready within ${timeout}ms. Waiting for: ${condition}`,
+			context: {
+				processId,
+				command,
+				condition,
+				timeout
+			},
+			httpStatus: 408,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			suggestion: `Check if your process outputs ${condition}. You can increase the timeout parameter.`
+		});
+	}
+	/**
+	* Create a ProcessExitedBeforeReadyError
+	*/
+	createExitedBeforeReadyError(processId, command, condition, exitCode) {
+		return new ProcessExitedBeforeReadyError({
+			code: ErrorCode.PROCESS_EXITED_BEFORE_READY,
+			message: `Process exited with code ${exitCode} before becoming ready. Waiting for: ${condition}`,
+			context: {
+				processId,
+				command,
+				condition,
+				exitCode
+			},
+			httpStatus: 500,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			suggestion: "Check process logs with getLogs() for error messages"
+		});
+	}
 	async startProcess(command, options, sessionId) {
 		try {
 			const session = sessionId ?? await this.ensureDefaultSession();
@@ -2670,12 +2825,37 @@ var Sandbox = class extends Container {
 				exitCode: void 0
 			}, session);
 			if (options?.onStart) options.onStart(processObj);
+			if (options?.onOutput || options?.onExit) this.startProcessCallbackStream(response.processId, options).catch(() => {});
 			return processObj;
 		} catch (error) {
 			if (options?.onError && error instanceof Error) options.onError(error);
 			throw error;
 		}
 	}
+	/**
+	* Start background streaming for process callbacks
+	* Opens SSE stream to container and routes events to callbacks
+	*/
+	async startProcessCallbackStream(processId, options) {
+		try {
+			const stream = await this.client.processes.streamProcessLogs(processId);
+			for await (const event of parseSSEStream(stream)) switch (event.type) {
+				case "stdout":
+					if (event.data && options.onOutput) options.onOutput("stdout", event.data);
+					break;
+				case "stderr":
+					if (event.data && options.onOutput) options.onOutput("stderr", event.data);
+					break;
+				case "exit":
+				case "complete":
+					if (options.onExit) options.onExit(event.exitCode ?? null);
+					return;
+			}
+		} catch (error) {
+			if (options.onError && error instanceof Error) options.onError(error);
+			this.logger.error("Background process streaming failed", error instanceof Error ? error : new Error(String(error)), { processId });
+		}
+	}
 	async listProcesses(sessionId) {
 		const session = sessionId ?? await this.ensureDefaultSession();
 		return (await this.client.processes.listProcesses()).processes.map((processData) => this.createProcessFromDTO({
@@ -2748,10 +2928,10 @@ var Sandbox = class extends Container {
 		return this.client.processes.streamProcessLogs(processId);
 	}
 	async gitCheckout(repoUrl, options) {
-		const session = options.sessionId ?? await this.ensureDefaultSession();
+		const session = options?.sessionId ?? await this.ensureDefaultSession();
 		return this.client.git.checkout(repoUrl, session, {
-			branch: options.branch,
-			targetDir: options.targetDir
+			branch: options?.branch,
+			targetDir: options?.targetDir
 		});
 	}
 	async mkdir(path, options = {}) {
@@ -3141,5 +3321,5 @@ async function collectFile(stream) {
 }
 
 //#endregion
-export { BucketMountError, CodeInterpreter, CommandClient, FileClient, GitClient, InvalidMountConfigError, MissingCredentialsError, PortClient, ProcessClient, S3FSMountError, Sandbox, SandboxClient, UtilityClient, asyncIterableToSSEStream, collectFile, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyToSandbox, responseToAsyncIterable, streamFile };
+export { BucketMountError, CodeInterpreter, CommandClient, FileClient, GitClient, InvalidMountConfigError, MissingCredentialsError, PortClient, ProcessClient, ProcessExitedBeforeReadyError, ProcessReadyTimeoutError, S3FSMountError, Sandbox, SandboxClient, UtilityClient, asyncIterableToSSEStream, collectFile, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyToSandbox, responseToAsyncIterable, streamFile };
 //# sourceMappingURL=index.js.map