@cloudflare/sandbox 0.8.1 → 0.8.3

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { $ as DirectoryBackup, A as DesktopStopResponse, At as StreamOptions, B as ExecuteResponse, Bt as PtyOptions, C as ClickOptions, Ct as ProcessOptions, D as DesktopStartOptions, Dt as RestoreBackupResult, E as DesktopClient, Et as RemoteMountBucketOptions, F as ScreenshotRegion, Ft as isProcess, G as HttpClientOptions, Gt as RunCodeOptions, H as BaseApiResponse, Ht as CreateContextOptions, I as ScreenshotResponse, It as isProcessStatus, J as SessionRequest, K as RequestConfig, L as ScrollDirection, Lt as ExecuteRequest, M as ScreenSizeResponse, Mt as WaitForPortOptions, N as ScreenshotBytesResponse, Nt as WatchOptions, O as DesktopStartResponse, Ot as SandboxOptions, P as ScreenshotOptions, Pt as isExecResult, Q as BucketProvider, R as TypeOptions, Rt as ExposePortRequest, S as WriteFileRequest, St as ProcessLogsResult, T as Desktop, Tt as ProcessStatus, U as ContainerStub, Ut as Execution, V as BackupClient, Vt as CodeContext, W as ErrorResponse, Wt as ExecutionResult, X as BaseExecOptions, Y as BackupOptions, Z as BucketCredentials, _ as GitClient, _t as Process, a as CreateSessionRequest, at as FileMetadata, b as MkdirRequest, bt as ProcessKillResult, c as DeleteSessionResponse, ct as GitCheckoutResult, d as ProcessClient, dt as LocalMountBucketOptions, et as ExecEvent, f as PortClient, ft as LogEvent, g as GitCheckoutRequest, gt as PortListResult, h as InterpreterClient, ht as PortExposeResult, i as CommandsResponse, it as FileChunk, j as KeyInput, jt as WaitForLogResult, k as DesktopStatusResponse, kt as SessionOptions, l as PingResponse, lt as ISandbox, m as ExecutionCallbacks, mt as PortCloseResult, n as getSandbox, nt as ExecResult, o as CreateSessionResponse, ot as FileStreamEvent, p as UnexposePortRequest, pt as MountBucketOptions, q as ResponseHandler, r as SandboxClient, rt as ExecutionSession, s as DeleteSessionRequest, st as FileWatchSSEEvent, t as Sandbox, tt as ExecOptions, u as UtilityClient, ut as ListFilesOptions, v as FileClient, vt as ProcessCleanupResult, w as CursorPositionResponse, wt as ProcessStartResult, x as ReadFileRequest, xt as ProcessListResult, y as FileOperationRequest, yt as ProcessInfoResult, z as CommandClient, zt as StartProcessRequest } from "./sandbox-DDDSuWA6.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-BoLbdjOe.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";
 
@@ -249,5 +249,5 @@ declare class InvalidMountConfigError extends BucketMountError {
   constructor(message: string);
 }
 //#endregion
-export { BackupClient, BackupCreateError, BackupExpiredError, BackupNotFoundError, type BackupOptions, BackupRestoreError, type BaseApiResponse, type BaseExecOptions, type BucketCredentials, BucketMountError, type BucketProvider, type ClickOptions, type CodeContext, CodeInterpreter, CommandClient, type ExecuteResponse as CommandExecuteResponse, type CommandsResponse, ContainerProxy, type ContainerStub, type CreateContextOptions, type CreateSessionRequest, type CreateSessionResponse, type CursorPositionResponse, type DeleteSessionRequest, type DeleteSessionResponse, type Desktop, DesktopClient, DesktopInvalidCoordinatesError, DesktopInvalidOptionsError, DesktopNotStartedError, DesktopProcessCrashedError, DesktopStartFailedError, type DesktopStartOptions, type DesktopStartResponse, type DesktopStatusResponse, type DesktopStopResponse, DesktopUnavailableError, type DirectoryBackup, type ErrorResponse, type ExecEvent, type ExecOptions, type ExecResult, type ExecuteRequest, type ExecutionCallbacks, type ExecutionResult, type ExecutionSession, type ExposePortRequest, type FileChunk, FileClient, type FileMetadata, type FileOperationRequest, type FileStreamEvent, type FileWatchSSEEvent, type GitCheckoutRequest, type GitCheckoutResult, GitClient, type ISandbox, type InterpreterClient, InvalidBackupConfigError, InvalidMountConfigError, type KeyInput, type ListFilesOptions, type LocalMountBucketOptions, type LogEvent, MissingCredentialsError, type MkdirRequest, type MountBucketOptions, type PingResponse, PortClient, type PortCloseResult, type PortExposeResult, type PortListResult, type Process, type ProcessCleanupResult, ProcessClient, ProcessExitedBeforeReadyError, type ProcessInfoResult, type ProcessKillResult, type ProcessListResult, type ProcessLogsResult, type ProcessOptions, ProcessReadyTimeoutError, type ProcessStartResult, type ProcessStatus, type PtyOptions, type ReadFileRequest, type RemoteMountBucketOptions, type RequestConfig, type ResponseHandler, type RestoreBackupResult, type RouteInfo, type RunCodeOptions, S3FSMountError, Sandbox, SandboxClient, type HttpClientOptions as SandboxClientOptions, type SandboxEnv, type SandboxOptions, type ScreenSizeResponse, type ScreenshotBytesResponse, type ScreenshotOptions, type ScreenshotRegion, type ScreenshotResponse, type ScrollDirection, type SessionOptions, type SessionRequest, type StartProcessRequest, type StreamOptions, type TypeOptions, type UnexposePortRequest, UtilityClient, type WaitForLogResult, type WaitForPortOptions, type WatchOptions, type WriteFileRequest, asyncIterableToSSEStream, collectFile, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyTerminal, proxyToSandbox, responseToAsyncIterable, streamFile };
+export { BackupClient, BackupCreateError, BackupExpiredError, BackupNotFoundError, type BackupOptions, BackupRestoreError, type BaseApiResponse, type BaseExecOptions, type BucketCredentials, BucketMountError, type BucketProvider, type CheckChangesOptions, type CheckChangesResult, type ClickOptions, type CodeContext, CodeInterpreter, CommandClient, type ExecuteResponse as CommandExecuteResponse, type CommandsResponse, ContainerProxy, type ContainerStub, type CreateContextOptions, type CreateSessionRequest, type CreateSessionResponse, type CursorPositionResponse, type DeleteSessionRequest, type DeleteSessionResponse, type Desktop, DesktopClient, DesktopInvalidCoordinatesError, DesktopInvalidOptionsError, DesktopNotStartedError, DesktopProcessCrashedError, DesktopStartFailedError, type DesktopStartOptions, type DesktopStartResponse, type DesktopStatusResponse, type DesktopStopResponse, DesktopUnavailableError, type DirectoryBackup, type ErrorResponse, type ExecEvent, type ExecOptions, type ExecResult, type ExecuteRequest, type ExecutionCallbacks, type ExecutionResult, type ExecutionSession, type ExposePortRequest, type FileChunk, FileClient, type FileMetadata, type FileOperationRequest, type FileStreamEvent, type FileWatchSSEEvent, type GitCheckoutRequest, type GitCheckoutResult, GitClient, type ISandbox, type InterpreterClient, InvalidBackupConfigError, InvalidMountConfigError, type KeyInput, type ListFilesOptions, type LocalMountBucketOptions, type LogEvent, MissingCredentialsError, type MkdirRequest, type MountBucketOptions, type PingResponse, PortClient, type PortCloseResult, type PortExposeResult, type PortListResult, type Process, type ProcessCleanupResult, ProcessClient, ProcessExitedBeforeReadyError, type ProcessInfoResult, type ProcessKillResult, type ProcessListResult, type ProcessLogsResult, type ProcessOptions, ProcessReadyTimeoutError, type ProcessStartResult, type ProcessStatus, type PtyOptions, type ReadFileRequest, type RemoteMountBucketOptions, type RequestConfig, type ResponseHandler, type RestoreBackupResult, type RouteInfo, type RunCodeOptions, S3FSMountError, Sandbox, SandboxClient, type HttpClientOptions as SandboxClientOptions, type SandboxEnv, type SandboxOptions, type ScreenSizeResponse, type ScreenshotBytesResponse, type ScreenshotOptions, type ScreenshotRegion, type ScreenshotResponse, type ScrollDirection, type SessionOptions, type SessionRequest, type StartProcessRequest, type StreamOptions, type TypeOptions, type UnexposePortRequest, UtilityClient, type WaitForLogResult, type WaitForPortOptions, type WatchOptions, type WriteFileRequest, asyncIterableToSSEStream, collectFile, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyTerminal, proxyToSandbox, responseToAsyncIterable, streamFile };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -844,6 +844,7 @@ var HttpTransport = class extends BaseTransport {
 const DEFAULT_REQUEST_TIMEOUT_MS = 12e4;
 const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 3e5;
 const DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
+const DEFAULT_IDLE_DISCONNECT_MS = 1e3;
 const MIN_TIME_FOR_CONNECT_RETRY_MS = 15e3;
 /**
 * WebSocket transport implementation
@@ -856,6 +857,7 @@ var WebSocketTransport = class extends BaseTransport {
 	state = "disconnected";
 	pendingRequests = /* @__PURE__ */ new Map();
 	connectPromise = null;
+	idleDisconnectTimer = null;
 	boundHandleMessage;
 	boundHandleClose;
 	constructor(config) {
@@ -880,6 +882,7 @@ var WebSocketTransport = class extends BaseTransport {
 	* callers share the same connection attempt.
 	*/
 	async connect() {
+		this.clearIdleDisconnectTimer();
 		if (this.isConnected()) return;
 		if (this.connectPromise) return this.connectPromise;
 		this.connectPromise = this.doConnect();
@@ -1055,6 +1058,7 @@ var WebSocketTransport = class extends BaseTransport {
 	*/
 	async request(method, path$1, body, headers) {
 		await this.connect();
+		this.clearIdleDisconnectTimer();
 		const id = generateRequestId();
 		const request = {
 			type: "request",
@@ -1068,12 +1072,14 @@ var WebSocketTransport = class extends BaseTransport {
 			const timeoutMs = this.config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
 			const timeoutId = setTimeout(() => {
 				this.pendingRequests.delete(id);
+				this.scheduleIdleDisconnect();
 				reject(/* @__PURE__ */ new Error(`Request timeout after ${timeoutMs}ms: ${method} ${path$1}`));
 			}, timeoutMs);
 			this.pendingRequests.set(id, {
 				resolve: (response) => {
 					clearTimeout(timeoutId);
 					this.pendingRequests.delete(id);
+					this.scheduleIdleDisconnect();
 					resolve({
 						status: response.status,
 						body: response.body
@@ -1082,6 +1088,7 @@ var WebSocketTransport = class extends BaseTransport {
 				reject: (error) => {
 					clearTimeout(timeoutId);
 					this.pendingRequests.delete(id);
+					this.scheduleIdleDisconnect();
 					reject(error);
 				},
 				isStreaming: false,
@@ -1092,6 +1099,7 @@ var WebSocketTransport = class extends BaseTransport {
 			} catch (error) {
 				clearTimeout(timeoutId);
 				this.pendingRequests.delete(id);
+				this.scheduleIdleDisconnect();
 				reject(error instanceof Error ? error : new Error(String(error)));
 			}
 		});
@@ -1112,6 +1120,7 @@ var WebSocketTransport = class extends BaseTransport {
 	*/
 	async requestStream(method, path$1, body, headers) {
 		await this.connect();
+		this.clearIdleDisconnectTimer();
 		const id = generateRequestId();
 		const request = {
 			type: "request",
@@ -1128,6 +1137,7 @@ var WebSocketTransport = class extends BaseTransport {
 			const createIdleTimeout = () => {
 				return setTimeout(() => {
 					this.pendingRequests.delete(id);
+					this.scheduleIdleDisconnect();
 					const error = /* @__PURE__ */ new Error(`Stream idle timeout after ${idleTimeoutMs}ms: ${method} ${path$1}`);
 					if (firstMessageReceived) try {
 						streamController?.error(error);
@@ -1155,6 +1165,7 @@ var WebSocketTransport = class extends BaseTransport {
 						});
 					}
 					this.pendingRequests.delete(id);
+					this.scheduleIdleDisconnect();
 				}
 			});
 			this.pendingRequests.set(id, {
@@ -1162,6 +1173,7 @@ var WebSocketTransport = class extends BaseTransport {
 					const pending = this.pendingRequests.get(id);
 					if (pending?.timeoutId) clearTimeout(pending.timeoutId);
 					this.pendingRequests.delete(id);
+					this.scheduleIdleDisconnect();
 					if (!firstMessageReceived) {
 						firstMessageReceived = true;
 						if (response.status >= 400) rejectStream(/* @__PURE__ */ new Error(`Stream error: ${response.status} - ${JSON.stringify(response.body)}`));
@@ -1178,6 +1190,7 @@ var WebSocketTransport = class extends BaseTransport {
 					const pending = this.pendingRequests.get(id);
 					if (pending?.timeoutId) clearTimeout(pending.timeoutId);
 					this.pendingRequests.delete(id);
+					this.scheduleIdleDisconnect();
 					if (firstMessageReceived) try {
 						streamController?.error(error);
 					} catch {}
@@ -1202,6 +1215,7 @@ var WebSocketTransport = class extends BaseTransport {
 									});
 									if (pending.timeoutId) clearTimeout(pending.timeoutId);
 									this.pendingRequests.delete(id);
+									this.scheduleIdleDisconnect();
 								}
 								pending.bufferedChunks = void 0;
 							}
@@ -1215,6 +1229,7 @@ var WebSocketTransport = class extends BaseTransport {
 			} catch (error) {
 				clearTimeout(timeoutId);
 				this.pendingRequests.delete(id);
+				this.scheduleIdleDisconnect();
 				rejectStream(error instanceof Error ? error : new Error(String(error)));
 			}
 		});
@@ -1301,6 +1316,7 @@ var WebSocketTransport = class extends BaseTransport {
 			});
 			if (pending.timeoutId) clearTimeout(pending.timeoutId);
 			this.pendingRequests.delete(chunk.id);
+			this.scheduleIdleDisconnect();
 		}
 	}
 	/**
@@ -1312,6 +1328,7 @@ var WebSocketTransport = class extends BaseTransport {
 		const idleTimeoutMs = this.config.streamIdleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
 		pending.timeoutId = setTimeout(() => {
 			this.pendingRequests.delete(id);
+			this.scheduleIdleDisconnect();
 			if (pending.streamController) try {
 				pending.streamController.error(/* @__PURE__ */ new Error(`Stream idle timeout after ${idleTimeoutMs}ms`));
 			} catch {}
@@ -1354,6 +1371,7 @@ var WebSocketTransport = class extends BaseTransport {
 	* Cleanup resources
 	*/
 	cleanup() {
+		this.clearIdleDisconnectTimer();
 		if (this.ws) {
 			this.ws.removeEventListener("close", this.boundHandleClose);
 			this.ws.removeEventListener("message", this.boundHandleMessage);
@@ -1365,6 +1383,23 @@ var WebSocketTransport = class extends BaseTransport {
 		for (const pending of this.pendingRequests.values()) if (pending.timeoutId) clearTimeout(pending.timeoutId);
 		this.pendingRequests.clear();
 	}
+	scheduleIdleDisconnect() {
+		if (!this.isConnected() || this.pendingRequests.size > 0) return;
+		this.clearIdleDisconnectTimer();
+		this.idleDisconnectTimer = setTimeout(() => {
+			this.idleDisconnectTimer = null;
+			if (this.pendingRequests.size === 0 && this.isConnected()) {
+				this.logger.debug("Disconnecting idle WebSocket transport");
+				this.cleanup();
+			}
+		}, DEFAULT_IDLE_DISCONNECT_MS);
+	}
+	clearIdleDisconnectTimer() {
+		if (this.idleDisconnectTimer) {
+			clearTimeout(this.idleDisconnectTimer);
+			this.idleDisconnectTimer = null;
+		}
+	}
 };
 
 //#endregion
@@ -2581,9 +2616,15 @@ var UtilityClient = class extends BaseHttpClient {
 * Uses inotify under the hood for native filesystem event notifications
 *
 * @internal This client is used internally by the SDK.
-* Users should use `sandbox.watch()` instead.
+* Users should use `sandbox.watch()` or `sandbox.checkChanges()` instead.
 */
 var WatchClient = class extends BaseHttpClient {
+	/**
+	* Check whether a path changed since a previously returned version.
+	*/
+	async checkChanges(request) {
+		return this.post("/api/watch/check", request);
+	}
 	/**
 	* Start watching a directory for changes.
 	* The returned promise resolves only after the watcher is established
@@ -3591,7 +3632,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.1";
+const SDK_VERSION = "0.8.3";
 
 //#endregion
 //#region src/sandbox.ts
@@ -5174,6 +5215,27 @@ var Sandbox = class Sandbox extends Container {
 		});
 	}
 	/**
+	* Check whether a path changed while this caller was disconnected.
+	*
+	* Pass the `version` returned from a prior call in `options.since` to learn
+	* whether the path is unchanged, changed, or needs a full resync because the
+	* retained change state was reset.
+	*
+	* @param path - Path to check (absolute or relative to /workspace)
+	* @param options - Change-check options
+	*/
+	async checkChanges(path$1, options = {}) {
+		const sessionId = options.sessionId ?? await this.ensureDefaultSession();
+		return this.client.watch.checkChanges({
+			path: path$1,
+			recursive: options.recursive,
+			include: options.include,
+			exclude: options.exclude,
+			since: options.since,
+			sessionId
+		});
+	}
+	/**
 	* Expose a port and get a preview URL for accessing services running in the sandbox
 	*
 	* @param port - Port number to expose (1024-65535)
@@ -5425,6 +5487,10 @@ var Sandbox = class Sandbox extends Container {
 				...options,
 				sessionId
 			}),
+			checkChanges: (path$1, options) => this.checkChanges(path$1, {
+				...options,
+				sessionId
+			}),
 			mkdir: (path$1, options) => this.mkdir(path$1, {
 				...options,
 				sessionId