@cloudflare/sandbox 0.8.4 → 0.8.6

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as CheckChangesOptions, A as DesktopStopResponse, At as SandboxOptions, B as ExecuteResponse, Bt as ExposePortRequest, C as ClickOptions, Ct as ProcessListResult, D as DesktopStartOptions, Dt as ProcessStatus, E as DesktopClient, Et as ProcessStartResult, F as ScreenshotRegion, Ft as WatchOptions, G as HttpClientOptions, Gt as Execution, H as BaseApiResponse, Ht as PtyOptions, I as ScreenshotResponse, It as isExecResult, J as SessionRequest, K as RequestConfig, Kt as ExecutionResult, L as ScrollDirection, Lt as isProcess, M as ScreenSizeResponse, Mt as StreamOptions, N as ScreenshotBytesResponse, Nt as WaitForLogResult, O as DesktopStartResponse, Ot as RemoteMountBucketOptions, P as ScreenshotOptions, Pt as WaitForPortOptions, Q as BucketProvider, R as TypeOptions, Rt as isProcessStatus, S as WriteFileRequest, St as ProcessKillResult, T as Desktop, Tt as ProcessOptions, U as ContainerStub, Ut as CodeContext, V as BackupClient, Vt as StartProcessRequest, W as ErrorResponse, Wt as CreateContextOptions, X as BaseExecOptions, Y as BackupOptions, Z as BucketCredentials, _ as GitClient, _t as PortExposeResult, a as CreateSessionRequest, at as ExecutionSession, b as MkdirRequest, bt as ProcessCleanupResult, c as DeleteSessionResponse, ct as FileStreamEvent, d as ProcessClient, dt as ISandbox, et as CheckChangesResult, f as PortClient, ft as ListFilesOptions, g as GitCheckoutRequest, gt as PortCloseResult, h as InterpreterClient, ht as MountBucketOptions, i as CommandsResponse, it as ExecResult, j as KeyInput, jt as SessionOptions, k as DesktopStatusResponse, kt as RestoreBackupResult, l as PingResponse, lt as FileWatchSSEEvent, m as ExecutionCallbacks, mt as LogEvent, n as getSandbox, nt as ExecEvent, o as CreateSessionResponse, ot as FileChunk, p as UnexposePortRequest, pt as LocalMountBucketOptions, q as ResponseHandler, qt as RunCodeOptions, r as SandboxClient, rt as ExecOptions, s as DeleteSessionRequest, st as FileMetadata, t as Sandbox, tt as DirectoryBackup, u as UtilityClient, ut as GitCheckoutResult, v as FileClient, vt as PortListResult, w as CursorPositionResponse, wt as ProcessLogsResult, x as ReadFileRequest, xt as ProcessInfoResult, y as FileOperationRequest, yt as Process, z as CommandClient, zt as ExecuteRequest } from "./sandbox-BoLbdjOe.js";
+import { $ as CheckChangesOptions, A as DesktopStopResponse, At as SandboxOptions, B as ExecuteResponse, Bt as ExposePortRequest, C as ClickOptions, Ct as ProcessListResult, D as DesktopStartOptions, Dt as ProcessStatus, E as DesktopClient, Et as ProcessStartResult, F as ScreenshotRegion, Ft as WatchOptions, G as HttpClientOptions, Gt as Execution, H as BaseApiResponse, Ht as PtyOptions, I as ScreenshotResponse, It as isExecResult, J as SessionRequest, K as RequestConfig, Kt as ExecutionResult, L as ScrollDirection, Lt as isProcess, M as ScreenSizeResponse, Mt as StreamOptions, N as ScreenshotBytesResponse, Nt as WaitForLogResult, O as DesktopStartResponse, Ot as RemoteMountBucketOptions, P as ScreenshotOptions, Pt as WaitForPortOptions, Q as BucketProvider, R as TypeOptions, Rt as isProcessStatus, S as WriteFileRequest, St as ProcessKillResult, T as Desktop, Tt as ProcessOptions, U as ContainerStub, Ut as CodeContext, V as BackupClient, Vt as StartProcessRequest, W as ErrorResponse, Wt as CreateContextOptions, X as BaseExecOptions, Y as BackupOptions, Z as BucketCredentials, _ as GitClient, _t as PortExposeResult, a as CreateSessionRequest, at as ExecutionSession, b as MkdirRequest, bt as ProcessCleanupResult, c as DeleteSessionResponse, ct as FileStreamEvent, d as ProcessClient, dt as ISandbox, et as CheckChangesResult, f as PortClient, ft as ListFilesOptions, g as GitCheckoutRequest, gt as PortCloseResult, h as InterpreterClient, ht as MountBucketOptions, i as CommandsResponse, it as ExecResult, j as KeyInput, jt as SessionOptions, k as DesktopStatusResponse, kt as RestoreBackupResult, l as PingResponse, lt as FileWatchSSEEvent, m as ExecutionCallbacks, mt as LogEvent, n as getSandbox, nt as ExecEvent, o as CreateSessionResponse, ot as FileChunk, p as UnexposePortRequest, pt as LocalMountBucketOptions, q as ResponseHandler, qt as RunCodeOptions, r as SandboxClient, rt as ExecOptions, s as DeleteSessionRequest, st as FileMetadata, t as Sandbox, tt as DirectoryBackup, u as UtilityClient, ut as GitCheckoutResult, v as FileClient, vt as PortListResult, w as CursorPositionResponse, wt as ProcessLogsResult, x as ReadFileRequest, xt as ProcessInfoResult, y as FileOperationRequest, yt as Process, z as CommandClient, zt as ExecuteRequest } from "./sandbox-DW5aQ1lD.js";
 import { a as DesktopCoordinateErrorContext, d as ErrorResponse$1, f as OperationType, i as BackupRestoreContext, l as ProcessExitedBeforeReadyContext, n as BackupExpiredContext, o as DesktopErrorContext, p as ErrorCode, r as BackupNotFoundContext, s as InvalidBackupConfigContext, t as BackupCreateContext, u as ProcessReadyTimeoutContext } from "./contexts-CeQR115r.js";
 import { ContainerProxy } from "@cloudflare/containers";
 

package/dist/index.js

@@ -773,6 +773,44 @@ var BaseTransport = class {
 		}
 	}
 	/**
+	* Build a URL targeting the container's HTTP server.
+	*/
+	buildContainerUrl(path$1) {
+		if (this.config.stub) return `http://localhost:${this.config.port || 3e3}${path$1}`;
+		return `${this.config.baseUrl ?? `http://localhost:${this.config.port || 3e3}`}${path$1}`;
+	}
+	/**
+	* Single HTTP request to the container — no WebSocket, no 503 retry.
+	*/
+	httpFetch(path$1, options) {
+		const url = this.buildContainerUrl(path$1);
+		if (this.config.stub) return this.config.stub.containerFetch(url, options || {}, this.config.port);
+		return globalThis.fetch(url, options);
+	}
+	/**
+	* Streaming HTTP request to the container — no WebSocket, no 503 retry.
+	*/
+	async httpFetchStream(path$1, body, method = "POST", headers) {
+		const url = this.buildContainerUrl(path$1);
+		const init = {
+			method,
+			headers: body && method === "POST" ? {
+				...headers,
+				"Content-Type": "application/json"
+			} : headers,
+			body: body && method === "POST" ? JSON.stringify(body) : void 0
+		};
+		let response;
+		if (this.config.stub) response = await this.config.stub.containerFetch(url, init, this.config.port);
+		else response = await globalThis.fetch(url, init);
+		if (!response.ok) {
+			const errorBody = await response.text();
+			throw new Error(`HTTP error! status: ${response.status} - ${errorBody}`);
+		}
+		if (!response.body) throw new Error("No response body for streaming");
+		return response.body;
+	}
+	/**
 	* Sleep utility for retry delays
 	*/
 	sleep(ms) {
@@ -787,13 +825,12 @@ var BaseTransport = class {
 *
 * Uses standard fetch API for communication with the container.
 * HTTP is stateless, so connect/disconnect are no-ops.
+*
+* All HTTP request logic lives in {@link BaseTransport.httpFetch} and
+* {@link BaseTransport.httpFetchStream}; this subclass simply wires
+* the abstract `doFetch` / `fetchStream` hooks to those shared helpers.
 */
 var HttpTransport = class extends BaseTransport {
-	baseUrl;
-	constructor(config) {
-		super(config);
-		this.baseUrl = config.baseUrl ?? "http://localhost:3000";
-	}
 	getMode() {
 		return "http";
 	}
@@ -803,36 +840,10 @@ var HttpTransport = class extends BaseTransport {
 		return true;
 	}
 	async doFetch(path$1, options) {
-		const url = this.buildUrl(path$1);
-		if (this.config.stub) return this.config.stub.containerFetch(url, options || {}, this.config.port);
-		return globalThis.fetch(url, options);
+		return this.httpFetch(path$1, options);
 	}
 	async fetchStream(path$1, body, method = "POST", headers) {
-		const url = this.buildUrl(path$1);
-		const options = this.buildStreamOptions(body, method, headers);
-		let response;
-		if (this.config.stub) response = await this.config.stub.containerFetch(url, options, this.config.port);
-		else response = await globalThis.fetch(url, options);
-		if (!response.ok) {
-			const errorBody = await response.text();
-			throw new Error(`HTTP error! status: ${response.status} - ${errorBody}`);
-		}
-		if (!response.body) throw new Error("No response body for streaming");
-		return response.body;
-	}
-	buildUrl(path$1) {
-		if (this.config.stub) return `http://localhost:${this.config.port}${path$1}`;
-		return `${this.baseUrl}${path$1}`;
-	}
-	buildStreamOptions(body, method, headers) {
-		return {
-			method,
-			headers: body && method === "POST" ? {
-				...headers,
-				"Content-Type": "application/json"
-			} : headers,
-			body: body && method === "POST" ? JSON.stringify(body) : void 0
-		};
+		return this.httpFetchStream(path$1, body, method, headers);
 	}
 };
 
@@ -899,10 +910,30 @@ var WebSocketTransport = class extends BaseTransport {
 		this.cleanup();
 	}
 	/**
-	* Transport-specific fetch implementation
+	* Whether a WebSocket connection is currently being established.
+	*
+	* When true, awaiting `connectPromise` from a nested call would deadlock:
+	* the outer `connectViaFetch → stub.fetch → containerFetch →
+	* startAndWaitForPorts → blockConcurrencyWhile(onStart)` chain may call
+	* back into the SDK (e.g. `exec()`), which would await the same
+	* `connectPromise` that cannot resolve until `onStart` returns.
+	*
+	* Callers use this to fall back to a direct HTTP request, which is safe
+	* because `startAndWaitForPorts()` calls `setHealthy()` before invoking
+	* `onStart()`, so `containerFetch()` routes directly to the container.
+	*/
+	isWebSocketConnecting() {
+		return this.state === "connecting";
+	}
+	/**
+	* Transport-specific fetch implementation.
 	* Converts WebSocket response to standard Response object.
+	*
+	* Falls back to HTTP while a WebSocket connection is being established
+	* to avoid the re-entrant deadlock described in `isWebSocketConnecting()`.
 	*/
 	async doFetch(path$1, options) {
+		if (this.isWebSocketConnecting()) return this.httpFetch(path$1, options);
 		await this.connect();
 		const method = options?.method || "GET";
 		const body = this.parseBody(options?.body);
@@ -914,7 +945,9 @@ var WebSocketTransport = class extends BaseTransport {
 		});
 	}
 	/**
-	* Streaming fetch implementation
+	* Streaming fetch implementation.
+	*
+	* Delegates to `requestStream()`, which applies the re-entrancy guard.
 	*/
 	async fetchStream(path$1, body, method = "POST", headers) {
 		return this.requestStream(method, path$1, body, headers);
@@ -1054,7 +1087,12 @@ var WebSocketTransport = class extends BaseTransport {
 		});
 	}
 	/**
-	* Send a request and wait for response
+	* Send a request and wait for response.
+	*
+	* Only reachable from `doFetch()`, which already applies the re-entrancy
+	* guard via `isWebSocketConnecting()`. The `connect()` call here handles
+	* the case where the WebSocket was closed between `doFetch` and `request`
+	* (idle disconnect).
 	*/
 	async request(method, path$1, body, headers) {
 		await this.connect();
@@ -1105,7 +1143,7 @@ var WebSocketTransport = class extends BaseTransport {
 		});
 	}
 	/**
-	* Send a streaming request and return a ReadableStream
+	* Send a streaming request and return a ReadableStream.
 	*
 	* The stream will receive data chunks as they arrive over the WebSocket.
 	* Format matches SSE for compatibility with existing streaming code.
@@ -1117,8 +1155,12 @@ var WebSocketTransport = class extends BaseTransport {
 	* Uses an inactivity timeout instead of a total-duration timeout so that
 	* long-running streams (e.g. execStream from an agent) stay alive as long
 	* as data is flowing. The timer resets on every chunk or response message.
+	*
+	* Falls back to HTTP while a WebSocket connection is being established
+	* to avoid the re-entrant deadlock described in `isWebSocketConnecting()`.
 	*/
 	async requestStream(method, path$1, body, headers) {
+		if (this.isWebSocketConnecting()) return this.httpFetchStream(path$1, body, method, headers);
 		await this.connect();
 		this.clearIdleDisconnectTimer();
 		const id = generateRequestId();
@@ -2813,6 +2855,19 @@ var SandboxClient = class {
 	}
 };
 
+//#endregion
+//#region ../shared/src/backup.ts
+/**
+* Absolute directory prefixes supported by backup and restore operations.
+*/
+const BACKUP_ALLOWED_PREFIXES = [
+	"/workspace",
+	"/home",
+	"/tmp",
+	"/var/tmp",
+	"/app"
+];
+
 //#endregion
 //#region src/security.ts
 /**
@@ -3632,7 +3687,7 @@ function buildS3fsSource(bucket, prefix) {
 * 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.8.4";
+const SDK_VERSION = "0.8.6";
 
 //#endregion
 //#region src/sandbox.ts
@@ -5554,7 +5609,7 @@ var Sandbox = class Sandbox extends Container {
 	static UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 	/**
 	* Validate that a directory path is safe for backup operations.
-	* Rejects empty, relative, traversal, and null-byte paths.
+	* Rejects empty, relative, traversal, null-byte, and unsupported-root paths.
 	*/
 	static validateBackupDir(dir, label) {
 		if (!dir || !dir.startsWith("/")) throw new InvalidBackupConfigError({
@@ -5578,6 +5633,13 @@ var Sandbox = class Sandbox extends Container {
 			context: { reason: `${label} must not contain ".." path segments` },
 			timestamp: (/* @__PURE__ */ new Date()).toISOString()
 		});
+		if (!BACKUP_ALLOWED_PREFIXES.some((prefix) => dir === prefix || dir.startsWith(`${prefix}/`))) throw new InvalidBackupConfigError({
+			message: `${label} must be inside one of the supported backup roots (${BACKUP_ALLOWED_PREFIXES.join(", ")})`,
+			code: ErrorCode.INVALID_BACKUP_CONFIG,
+			httpStatus: 400,
+			context: { reason: `${label} must be inside one of the supported backup roots` },
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		});
 	}
 	/**
 	* Returns the R2 bucket or throws if backup is not configured.
@@ -5948,19 +6010,19 @@ var Sandbox = class Sandbox extends Container {
 		const restoreStartTime = Date.now();
 		const bucket = this.requireBackupBucket();
 		this.requirePresignedUrlSupport();
-		const { id: backupId, dir } = backup;
+		const { id, dir } = backup;
 		let outcome = "error";
 		let caughtError;
 		let backupSession;
 		try {
-			if (!backupId || typeof backupId !== "string") throw new InvalidBackupConfigError({
+			if (!id || typeof id !== "string") throw new InvalidBackupConfigError({
 				message: "Invalid backup: missing or invalid id",
 				code: ErrorCode.INVALID_BACKUP_CONFIG,
 				httpStatus: 400,
 				context: { reason: "missing or invalid id" },
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
-			if (!Sandbox.UUID_REGEX.test(backupId)) throw new InvalidBackupConfigError({
+			if (!Sandbox.UUID_REGEX.test(id)) throw new InvalidBackupConfigError({
 				message: "Invalid backup: id must be a valid UUID (e.g. from createBackup)",
 				code: ErrorCode.INVALID_BACKUP_CONFIG,
 				httpStatus: 400,
@@ -5968,13 +6030,13 @@ var Sandbox = class Sandbox extends Container {
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 			Sandbox.validateBackupDir(dir, "Invalid backup: dir");
-			const metaKey = `backups/${backupId}/meta.json`;
+			const metaKey = `backups/${id}/meta.json`;
 			const metaObject = await bucket.get(metaKey);
 			if (!metaObject) throw new BackupNotFoundError({
-				message: `Backup not found: ${backupId}. Verify the backup ID is correct and the backup has not been deleted.`,
+				message: `Backup not found: ${id}. Verify the backup ID is correct and the backup has not been deleted.`,
 				code: ErrorCode.BACKUP_NOT_FOUND,
 				httpStatus: 404,
-				context: { backupId },
+				context: { backupId: id },
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 			const metadata = await metaObject.json();
@@ -5986,44 +6048,44 @@ var Sandbox = class Sandbox extends Container {
 				httpStatus: 500,
 				context: {
 					dir,
-					backupId
+					backupId: id
 				},
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 			const expiresAt = createdAt + metadata.ttl * 1e3;
 			if (Date.now() + TTL_BUFFER_MS > expiresAt) throw new BackupExpiredError({
-				message: `Backup ${backupId} has expired (created: ${metadata.createdAt}, TTL: ${metadata.ttl}s). Create a new backup.`,
+				message: `Backup ${id} has expired (created: ${metadata.createdAt}, TTL: ${metadata.ttl}s). Create a new backup.`,
 				code: ErrorCode.BACKUP_EXPIRED,
 				httpStatus: 400,
 				context: {
-					backupId,
+					backupId: id,
 					expiredAt: new Date(expiresAt).toISOString()
 				},
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
-			const r2Key = `backups/${backupId}/data.sqsh`;
+			const r2Key = `backups/${id}/data.sqsh`;
 			const archiveHead = await bucket.head(r2Key);
 			if (!archiveHead) throw new BackupNotFoundError({
-				message: `Backup archive not found in R2: ${backupId}. The archive may have been deleted by R2 lifecycle rules.`,
+				message: `Backup archive not found in R2: ${id}. The archive may have been deleted by R2 lifecycle rules.`,
 				code: ErrorCode.BACKUP_NOT_FOUND,
 				httpStatus: 404,
-				context: { backupId },
+				context: { backupId: id },
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
 			backupSession = await this.ensureBackupSession();
-			const archivePath = `/var/backups/${backupId}.sqsh`;
-			const mountGlob = `/var/backups/mounts/${backupId}`;
+			const archivePath = `/var/backups/${id}.sqsh`;
+			const mountGlob = `/var/backups/mounts/${id}`;
 			await this.execWithSession(`/usr/bin/fusermount3 -uz ${shellEscape(dir)} 2>/dev/null || true`, backupSession, { origin: "internal" }).catch(() => {});
 			await this.execWithSession(`for d in ${shellEscape(mountGlob)}_*/lower ${shellEscape(mountGlob)}/lower; do [ -d "$d" ] && /usr/bin/fusermount3 -uz "$d" 2>/dev/null; done; true`, backupSession, { origin: "internal" }).catch(() => {});
 			const sizeCheck = await this.execWithSession(`stat -c %s ${shellEscape(archivePath)} 2>/dev/null || echo 0`, backupSession, { origin: "internal" }).catch(() => ({ stdout: "0" }));
-			if (Number.parseInt((sizeCheck.stdout ?? "0").trim(), 10) !== archiveHead.size) await this.downloadBackupPresigned(archivePath, r2Key, archiveHead.size, backupId, dir, backupSession);
+			if (Number.parseInt((sizeCheck.stdout ?? "0").trim(), 10) !== archiveHead.size) await this.downloadBackupPresigned(archivePath, r2Key, archiveHead.size, id, dir, backupSession);
 			if (!(await this.client.backup.restoreArchive(dir, archivePath, backupSession)).success) throw new BackupRestoreError({
 				message: "Container failed to restore backup archive",
 				code: ErrorCode.BACKUP_RESTORE_FAILED,
 				httpStatus: 500,
 				context: {
 					dir,
-					backupId
+					backupId: id
 				},
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
 			});
@@ -6031,12 +6093,12 @@ var Sandbox = class Sandbox extends Container {
 			return {
 				success: true,
 				dir,
-				id: backupId
+				id
 			};
 		} catch (error) {
 			caughtError = error instanceof Error ? error : new Error(String(error));
-			if (backupId && backupSession) {
-				const archivePath = `/var/backups/${backupId}.sqsh`;
+			if (id && backupSession) {
+				const archivePath = `/var/backups/${id}.sqsh`;
 				await this.execWithSession(`rm -f ${shellEscape(archivePath)}`, backupSession, { origin: "internal" }).catch(() => {});
 			}
 			throw error;
@@ -6046,7 +6108,7 @@ var Sandbox = class Sandbox extends Container {
 				event: "backup.restore",
 				outcome,
 				durationMs: Date.now() - restoreStartTime,
-				backupId,
+				backupId: id,
 				dir,
 				error: caughtError
 			});