@cloudflare/sandbox 0.0.0-0608f1e → 0.0.0-12bbd12

package/src/client.ts

@@ -1,41 +1,23 @@
+import type { ExecuteRequest } from "../container_src/types";
 import type { Sandbox } from "./index";
 import type {
+  BaseExecOptions,
+  DeleteFileResponse,
+  ExecuteResponse,
   GetProcessLogsResponse,
   GetProcessResponse,
+  GitCheckoutResponse,
+  ListFilesResponse,
   ListProcessesResponse,
+  MkdirResponse,
+  MoveFileResponse,
+  ReadFileResponse,
+  RenameFileResponse,
   StartProcessRequest,
-  StartProcessResponse
+  StartProcessResponse,
+  WriteFileResponse,
 } from "./types";
 
-interface ExecuteRequest {
-  command: string;
-  sessionId?: string;
-}
-
-export interface ExecuteResponse {
-  success: boolean;
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-  command: string;
-  timestamp: string;
-}
-
-interface SessionResponse {
-  sessionId: string;
-  message: string;
-  timestamp: string;
-}
-
-interface SessionListResponse {
-  sessions: Array<{
-    sessionId: string;
-    hasActiveProcess: boolean;
-    createdAt: string;
-  }>;
-  count: number;
-  timestamp: string;
-}
 
 interface CommandsResponse {
   availableCommands: string[];
@@ -49,16 +31,6 @@ interface GitCheckoutRequest {
   sessionId?: string;
 }
 
-export interface GitCheckoutResponse {
-  success: boolean;
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-  repoUrl: string;
-  branch: string;
-  targetDir: string;
-  timestamp: string;
-}
 
 interface MkdirRequest {
   path: string;
@@ -66,15 +38,6 @@ interface MkdirRequest {
   sessionId?: string;
 }
 
-export interface MkdirResponse {
-  success: boolean;
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-  path: string;
-  recursive: boolean;
-  timestamp: string;
-}
 
 interface WriteFileRequest {
   path: string;
@@ -83,12 +46,6 @@ interface WriteFileRequest {
   sessionId?: string;
 }
 
-export interface WriteFileResponse {
-  success: boolean;
-  exitCode: number;
-  path: string;
-  timestamp: string;
-}
 
 interface ReadFileRequest {
   path: string;
@@ -96,25 +53,12 @@ interface ReadFileRequest {
   sessionId?: string;
 }
 
-export interface ReadFileResponse {
-  success: boolean;
-  exitCode: number;
-  path: string;
-  content: string;
-  timestamp: string;
-}
 
 interface DeleteFileRequest {
   path: string;
   sessionId?: string;
 }
 
-export interface DeleteFileResponse {
-  success: boolean;
-  exitCode: number;
-  path: string;
-  timestamp: string;
-}
 
 interface RenameFileRequest {
   oldPath: string;
@@ -122,13 +66,6 @@ interface RenameFileRequest {
   sessionId?: string;
 }
 
-export interface RenameFileResponse {
-  success: boolean;
-  exitCode: number;
-  oldPath: string;
-  newPath: string;
-  timestamp: string;
-}
 
 interface MoveFileRequest {
   sourcePath: string;
@@ -136,14 +73,17 @@ interface MoveFileRequest {
   sessionId?: string;
 }
 
-export interface MoveFileResponse {
-  success: boolean;
-  exitCode: number;
-  sourcePath: string;
-  destinationPath: string;
-  timestamp: string;
+
+interface ListFilesRequest {
+  path: string;
+  options?: {
+    recursive?: boolean;
+    includeHidden?: boolean;
+  };
+  sessionId?: string;
 }
 
+
 interface PreviewInfo {
   url: string;
   port: number;
@@ -212,7 +152,7 @@ export class HttpClient {
     this.baseUrl = this.options.baseUrl!;
   }
 
-  private async doFetch(
+  protected async doFetch(
     path: string,
     options?: RequestInit
   ): Promise<Response> {
@@ -255,16 +195,19 @@ export class HttpClient {
 
   async execute(
     command: string,
-    sessionId?: string
+    options: Pick<BaseExecOptions, "sessionId" | "cwd" | "env">
   ): Promise<ExecuteResponse> {
     try {
-      const targetSessionId = sessionId || this.sessionId;
+      const targetSessionId = options.sessionId || this.sessionId;
+      const executeRequest = {
+        command,
+        sessionId: targetSessionId,
+        cwd: options.cwd,
+        env: options.env,
+      } satisfies ExecuteRequest;
 
       const response = await this.doFetch(`/api/execute`, {
-        body: JSON.stringify({
-          command,
-          sessionId: targetSessionId,
-        } as ExecuteRequest),
+        body: JSON.stringify(executeRequest),
         headers: {
           "Content-Type": "application/json",
         },
@@ -305,7 +248,6 @@ export class HttpClient {
     }
   }
 
-
   async executeCommandStream(
     command: string,
     sessionId?: string
@@ -320,7 +262,7 @@ export class HttpClient {
         }),
         headers: {
           "Content-Type": "application/json",
-          "Accept": "text/event-stream",
+          Accept: "text/event-stream",
         },
         method: "POST",
       });
@@ -338,9 +280,7 @@ export class HttpClient {
         throw new Error("No response body for streaming request");
       }
 
-      console.log(
-        `[HTTP Client] Started command stream: ${command}`
-      );
+      console.log(`[HTTP Client] Started command stream: ${command}`);
 
       return response.body;
     } catch (error) {
@@ -392,7 +332,6 @@ export class HttpClient {
     }
   }
 
-
   async mkdir(
     path: string,
     recursive: boolean = false,
@@ -434,7 +373,6 @@ export class HttpClient {
     }
   }
 
-
   async writeFile(
     path: string,
     content: string,
@@ -478,7 +416,6 @@ export class HttpClient {
     }
   }
 
-
   async readFile(
     path: string,
     encoding: string = "utf-8",
@@ -520,7 +457,6 @@ export class HttpClient {
     }
   }
 
-
   async deleteFile(
     path: string,
     sessionId?: string
@@ -560,7 +496,6 @@ export class HttpClient {
     }
   }
 
-
   async renameFile(
     oldPath: string,
     newPath: string,
@@ -602,7 +537,6 @@ export class HttpClient {
     }
   }
 
-
   async moveFile(
     sourcePath: string,
     destinationPath: string,
@@ -644,6 +578,49 @@ export class HttpClient {
     }
   }
 
+  async listFiles(
+    path: string,
+    options?: {
+      recursive?: boolean;
+      includeHidden?: boolean;
+    },
+    sessionId?: string
+  ): Promise<ListFilesResponse> {
+    try {
+      const targetSessionId = sessionId || this.sessionId;
+
+      const response = await this.doFetch(`/api/list-files`, {
+        body: JSON.stringify({
+          path,
+          options,
+          sessionId: targetSessionId,
+        } as ListFilesRequest),
+        headers: {
+          "Content-Type": "application/json",
+        },
+        method: "POST",
+      });
+
+      if (!response.ok) {
+        const errorData = (await response.json().catch(() => ({}))) as {
+          error?: string;
+        };
+        throw new Error(
+          errorData.error || `HTTP error! status: ${response.status}`
+        );
+      }
+
+      const data: ListFilesResponse = await response.json();
+      console.log(
+        `[HTTP Client] Listed ${data.files.length} files in: ${path}, Success: ${data.success}`
+      );
+
+      return data;
+    } catch (error) {
+      console.error("[HTTP Client] Error listing files:", error);
+      throw error;
+    }
+  }
 
   async exposePort(port: number, name?: string): Promise<ExposePortResponse> {
     try {
@@ -670,7 +647,9 @@ export class HttpClient {
 
       const data: ExposePortResponse = await response.json();
       console.log(
-        `[HTTP Client] Port exposed: ${port}${name ? ` (${name})` : ""}, Success: ${data.success}`
+        `[HTTP Client] Port exposed: ${port}${
+          name ? ` (${name})` : ""
+        }, Success: ${data.success}`
       );
 
       return data;
@@ -732,9 +711,7 @@ export class HttpClient {
       }
 
       const data: GetExposedPortsResponse = await response.json();
-      console.log(
-        `[HTTP Client] Got ${data.count} exposed ports`
-      );
+      console.log(`[HTTP Client] Got ${data.count} exposed ports`);
 
       return data;
     } catch (error) {
@@ -871,9 +848,7 @@ export class HttpClient {
       }
 
       const data: ListProcessesResponse = await response.json();
-      console.log(
-        `[HTTP Client] Listed ${data.processes.length} processes`
-      );
+      console.log(`[HTTP Client] Listed ${data.processes.length} processes`);
 
       return data;
     } catch (error) {
@@ -902,7 +877,9 @@ export class HttpClient {
 
       const data: GetProcessResponse = await response.json();
       console.log(
-        `[HTTP Client] Got process ${processId}: ${data.process?.status || 'not found'}`
+        `[HTTP Client] Got process ${processId}: ${
+          data.process?.status || "not found"
+        }`
       );
 
       return data;
@@ -912,7 +889,9 @@ export class HttpClient {
     }
   }
 
-  async killProcess(processId: string): Promise<{ success: boolean; message: string }> {
+  async killProcess(
+    processId: string
+  ): Promise<{ success: boolean; message: string }> {
     try {
       const response = await this.doFetch(`/api/process/${processId}`, {
         headers: {
@@ -930,10 +909,11 @@ export class HttpClient {
         );
       }
 
-      const data = await response.json() as { success: boolean; message: string };
-      console.log(
-        `[HTTP Client] Killed process ${processId}`
-      );
+      const data = (await response.json()) as {
+        success: boolean;
+        message: string;
+      };
+      console.log(`[HTTP Client] Killed process ${processId}`);
 
       return data;
     } catch (error) {
@@ -942,7 +922,11 @@ export class HttpClient {
     }
   }
 
-  async killAllProcesses(): Promise<{ success: boolean; killedCount: number; message: string }> {
+  async killAllProcesses(): Promise<{
+    success: boolean;
+    killedCount: number;
+    message: string;
+  }> {
     try {
       const response = await this.doFetch("/api/process/kill-all", {
         headers: {
@@ -960,10 +944,12 @@ export class HttpClient {
         );
       }
 
-      const data = await response.json() as { success: boolean; killedCount: number; message: string };
-      console.log(
-        `[HTTP Client] Killed ${data.killedCount} processes`
-      );
+      const data = (await response.json()) as {
+        success: boolean;
+        killedCount: number;
+        message: string;
+      };
+      console.log(`[HTTP Client] Killed ${data.killedCount} processes`);
 
       return data;
     } catch (error) {
@@ -991,9 +977,7 @@ export class HttpClient {
       }
 
       const data: GetProcessLogsResponse = await response.json();
-      console.log(
-        `[HTTP Client] Got logs for process ${processId}`
-      );
+      console.log(`[HTTP Client] Got logs for process ${processId}`);
 
       return data;
     } catch (error) {
@@ -1002,11 +986,13 @@ export class HttpClient {
     }
   }
 
-  async streamProcessLogs(processId: string): Promise<ReadableStream<Uint8Array>> {
+  async streamProcessLogs(
+    processId: string
+  ): Promise<ReadableStream<Uint8Array>> {
     try {
       const response = await this.doFetch(`/api/process/${processId}/stream`, {
         headers: {
-          "Accept": "text/event-stream",
+          Accept: "text/event-stream",
           "Cache-Control": "no-cache",
         },
         method: "GET",

package/src/errors.ts

@@ -0,0 +1,218 @@
+/**
+ * Standard error response from the sandbox API
+ */
+export interface SandboxErrorResponse {
+  error?: string;
+  status?: string;
+  progress?: number;
+}
+
+/**
+ * Base error class for all Sandbox-related errors
+ */
+export class SandboxError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = this.constructor.name;
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * Error thrown when Jupyter functionality is requested but the service is still initializing.
+ *
+ * Note: With the current implementation, requests wait for Jupyter to be ready.
+ * This error is only thrown when:
+ * 1. The request times out waiting for Jupyter (default: 30 seconds)
+ * 2. Jupyter initialization actually fails
+ *
+ * Most requests will succeed after a delay, not throw this error.
+ */
+export class JupyterNotReadyError extends SandboxError {
+  public readonly code = "JUPYTER_NOT_READY";
+  public readonly retryAfter: number;
+  public readonly progress?: number;
+
+  constructor(
+    message?: string,
+    options?: { retryAfter?: number; progress?: number }
+  ) {
+    super(
+      message || "Jupyter is still initializing. Please retry in a few seconds."
+    );
+    this.retryAfter = options?.retryAfter || 5;
+    this.progress = options?.progress;
+  }
+}
+
+/**
+ * Error thrown when a context is not found
+ */
+export class ContextNotFoundError extends SandboxError {
+  public readonly code = "CONTEXT_NOT_FOUND";
+  public readonly contextId: string;
+
+  constructor(contextId: string) {
+    super(`Context ${contextId} not found`);
+    this.contextId = contextId;
+  }
+}
+
+/**
+ * Error thrown when code execution fails
+ */
+export class CodeExecutionError extends SandboxError {
+  public readonly code = "CODE_EXECUTION_ERROR";
+  public readonly executionError?: {
+    ename?: string;
+    evalue?: string;
+    traceback?: string[];
+  };
+
+  constructor(message: string, executionError?: any) {
+    super(message);
+    this.executionError = executionError;
+  }
+}
+
+/**
+ * Error thrown when the sandbox container is not ready
+ */
+export class ContainerNotReadyError extends SandboxError {
+  public readonly code = "CONTAINER_NOT_READY";
+
+  constructor(message?: string) {
+    super(
+      message ||
+        "Container is not ready. Please wait for initialization to complete."
+    );
+  }
+}
+
+/**
+ * Error thrown when a network request to the sandbox fails
+ */
+export class SandboxNetworkError extends SandboxError {
+  public readonly code = "NETWORK_ERROR";
+  public readonly statusCode?: number;
+  public readonly statusText?: string;
+
+  constructor(message: string, statusCode?: number, statusText?: string) {
+    super(message);
+    this.statusCode = statusCode;
+    this.statusText = statusText;
+  }
+}
+
+/**
+ * Error thrown when service is temporarily unavailable (e.g., circuit breaker open)
+ */
+export class ServiceUnavailableError extends SandboxError {
+  public readonly code = "SERVICE_UNAVAILABLE";
+  public readonly retryAfter?: number;
+
+  constructor(message?: string, retryAfter?: number) {
+    // Simple, user-friendly message without implementation details
+    super(message || "Service temporarily unavailable");
+    this.retryAfter = retryAfter;
+  }
+}
+
+/**
+ * Type guard to check if an error is a JupyterNotReadyError
+ */
+export function isJupyterNotReadyError(
+  error: unknown
+): error is JupyterNotReadyError {
+  return error instanceof JupyterNotReadyError;
+}
+
+/**
+ * Type guard to check if an error is any SandboxError
+ */
+export function isSandboxError(error: unknown): error is SandboxError {
+  return error instanceof SandboxError;
+}
+
+/**
+ * Helper to determine if an error is retryable
+ */
+export function isRetryableError(error: unknown): boolean {
+  if (
+    error instanceof JupyterNotReadyError ||
+    error instanceof ContainerNotReadyError ||
+    error instanceof ServiceUnavailableError
+  ) {
+    return true;
+  }
+
+  if (error instanceof SandboxNetworkError) {
+    // Retry on 502, 503, 504 (gateway/service unavailable errors)
+    return error.statusCode
+      ? [502, 503, 504].includes(error.statusCode)
+      : false;
+  }
+
+  return false;
+}
+
+/**
+ * Parse error response from the sandbox API and return appropriate error instance
+ */
+export async function parseErrorResponse(
+  response: Response
+): Promise<SandboxError> {
+  let data: SandboxErrorResponse;
+
+  try {
+    data = (await response.json()) as SandboxErrorResponse;
+  } catch {
+    // If JSON parsing fails, return a generic network error
+    return new SandboxNetworkError(
+      `Request failed with status ${response.status}`,
+      response.status,
+      response.statusText
+    );
+  }
+
+  // Check for specific error types based on response
+  if (response.status === 503) {
+    // Circuit breaker error
+    if (data.status === "circuit_open") {
+      return new ServiceUnavailableError(
+        "Service temporarily unavailable",
+        parseInt(response.headers.get("Retry-After") || "30")
+      );
+    }
+
+    // Jupyter initialization error
+    if (data.status === "initializing") {
+      return new JupyterNotReadyError(data.error, {
+        retryAfter: parseInt(response.headers.get("Retry-After") || "5"),
+        progress: data.progress,
+      });
+    }
+  }
+
+  // Check for context not found
+  if (
+    response.status === 404 &&
+    data.error?.includes("Context") &&
+    data.error?.includes("not found")
+  ) {
+    const contextId =
+      data.error.match(/Context (\S+) not found/)?.[1] || "unknown";
+    return new ContextNotFoundError(contextId);
+  }
+
+  // Default network error
+  return new SandboxNetworkError(
+    data.error || `Request failed with status ${response.status}`,
+    response.status,
+    response.statusText
+  );
+}