@cloudflare/sandbox 0.0.0-ee8c772 → 0.0.0-ef9e320

package/src/errors.ts

@@ -0,0 +1,219 @@
+/**
+ * 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 interpreter functionality is requested but the service is still initializing.
+ *
+ * Note: With the current implementation, requests wait for interpreter to be ready.
+ * This error is only thrown when:
+ * 1. The request times out waiting for interpreter (default: 30 seconds)
+ * 2. interpreter initialization actually fails
+ *
+ * Most requests will succeed after a delay, not throw this error.
+ */
+export class InterpreterNotReadyError extends SandboxError {
+  public readonly code = "INTERPRETER_NOT_READY";
+  public readonly retryAfter: number;
+  public readonly progress?: number;
+
+  constructor(
+    message?: string,
+    options?: { retryAfter?: number; progress?: number }
+  ) {
+    super(
+      message ||
+        "Interpreter 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 InterpreterNotReadyError
+ */
+export function isInterpreterNotReadyError(
+  error: unknown
+): error is InterpreterNotReadyError {
+  return error instanceof InterpreterNotReadyError;
+}
+
+/**
+ * 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 InterpreterNotReadyError ||
+    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")
+      );
+    }
+
+    // Interpreter initialization error
+    if (data.status === "initializing") {
+      return new InterpreterNotReadyError(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
+  );
+}

package/src/index.ts

@@ -1,129 +1,75 @@
-import { Container, getContainer } from "@cloudflare/containers";
-import { HttpClient } from "./client";
+// biome-ignore-start assist/source/organizeImports: Need separate exports for deprecation warnings to work properly
+/**
+ * @deprecated Use `InterpreterNotReadyError` instead. Will be removed in a future version.
+ */
+export { InterpreterNotReadyError as JupyterNotReadyError } from "./errors";
 
-export function getSandbox(ns: DurableObjectNamespace<Sandbox>, id: string) {
-  return getContainer(ns, id);
-}
+/**
+ * @deprecated Use `isInterpreterNotReadyError` instead. Will be removed in a future version.
+ */
+export { isInterpreterNotReadyError as isJupyterNotReadyError } from "./errors";
+// biome-ignore-end assist/source/organizeImports: Need separate exports for deprecation warnings to work properly
 
-export class Sandbox<Env = unknown> extends Container<Env> {
-  defaultPort = 3000; // The default port for the container to listen on
-  sleepAfter = "3m"; // Sleep the sandbox if no requests are made in this timeframe
+// Export API response types
+export {
+  CodeExecutionError,
+  ContainerNotReadyError,
+  ContextNotFoundError,
+  InterpreterNotReadyError,
+  isInterpreterNotReadyError,
+  isRetryableError,
+  isSandboxError,
+  parseErrorResponse,
+  SandboxError,
+  type SandboxErrorResponse,
+  SandboxNetworkError,
+  ServiceUnavailableError,
+} from "./errors";
 
-  client: HttpClient = new HttpClient({
-    onCommandComplete: (success, exitCode, stdout, stderr, command, args) => {
-      console.log(
-        `[Container] Command completed: ${command}, Success: ${success}, Exit code: ${exitCode}`
-      );
-    },
-    onCommandStart: (command, args) => {
-      console.log(`[Container] Command started: ${command} ${args.join(" ")}`);
-    },
-    onError: (error, command, args) => {
-      console.error(`[Container] Command error: ${error}`);
-    },
-    onOutput: (stream, data, command) => {
-      console.log(`[Container] [${stream}] ${data}`);
-    },
-    port: this.defaultPort,
-  });
-
-  envVars = {
-    MESSAGE: "I was passed in via the Sandbox class!",
-  };
-
-  override onStart() {
-    console.log("Sandbox successfully started");
-  }
-
-  override onStop() {
-    console.log("Sandbox successfully shut down");
-    if (this.client) {
-      this.client.clearSession();
-    }
-  }
-
-  override onError(error: unknown) {
-    console.log("Sandbox error:", error);
-  }
-
-  async exec(command: string, args: string[], options?: { stream?: boolean }) {
-    if (options?.stream) {
-      return this.client.executeStream(command, args);
-    }
-    return this.client.execute(command, args);
-  }
-
-  async gitCheckout(
-    repoUrl: string,
-    options: { branch?: string; targetDir?: string; stream?: boolean }
-  ) {
-    if (options?.stream) {
-      return this.client.gitCheckoutStream(
-        repoUrl,
-        options.branch,
-        options.targetDir
-      );
-    }
-    return this.client.gitCheckout(repoUrl, options.branch, options.targetDir);
-  }
-
-  async mkdir(
-    path: string,
-    options: { recursive?: boolean; stream?: boolean }
-  ) {
-    if (options?.stream) {
-      return this.client.mkdirStream(path, options.recursive);
-    }
-    return this.client.mkdir(path, options.recursive);
-  }
-
-  async writeFile(
-    path: string,
-    content: string,
-    options: { encoding?: string; stream?: boolean }
-  ) {
-    if (options?.stream) {
-      return this.client.writeFileStream(path, content, options.encoding);
-    }
-    return this.client.writeFile(path, content, options.encoding);
-  }
-
-  async deleteFile(path: string, options: { stream?: boolean }) {
-    if (options?.stream) {
-      return this.client.deleteFileStream(path);
-    }
-    return this.client.deleteFile(path);
-  }
-
-  async renameFile(
-    oldPath: string,
-    newPath: string,
-    options: { stream?: boolean }
-  ) {
-    if (options?.stream) {
-      return this.client.renameFileStream(oldPath, newPath);
-    }
-    return this.client.renameFile(oldPath, newPath);
-  }
-
-  async moveFile(
-    sourcePath: string,
-    destinationPath: string,
-    options: { stream?: boolean }
-  ) {
-    if (options?.stream) {
-      return this.client.moveFileStream(sourcePath, destinationPath);
-    }
-    return this.client.moveFile(sourcePath, destinationPath);
-  }
-
-  async readFile(
-    path: string,
-    options: { encoding?: string; stream?: boolean }
-  ) {
-    if (options?.stream) {
-      return this.client.readFileStream(path, options.encoding);
-    }
-    return this.client.readFile(path, options.encoding);
-  }
-}
+// Export code interpreter types
+export type {
+  ChartData,
+  CodeContext,
+  CreateContextOptions,
+  Execution,
+  ExecutionError,
+  OutputMessage,
+  Result,
+  RunCodeOptions,
+} from "./interpreter-types";
+// Export the implementations
+export { ResultImpl } from "./interpreter-types";
+// Re-export request handler utilities
+export {
+  proxyToSandbox,
+  type RouteInfo,
+  type SandboxEnv,
+} from "./request-handler";
+export { getSandbox, Sandbox } from "./sandbox";
+// Export SSE parser for converting ReadableStream to AsyncIterable
+export {
+  asyncIterableToSSEStream,
+  parseSSEStream,
+  responseToAsyncIterable,
+} from "./sse-parser";
+export type {
+  DeleteFileResponse,
+  ExecEvent,
+  ExecOptions,
+  ExecResult,
+  ExecuteResponse,
+  ExecutionSession,
+  GitCheckoutResponse,
+  ISandbox,
+  ListFilesResponse,
+  LogEvent,
+  MkdirResponse,
+  MoveFileResponse,
+  Process,
+  ProcessOptions,
+  ProcessStatus,
+  ReadFileResponse,
+  RenameFileResponse,
+  StreamOptions,
+  WriteFileResponse,
+} from "./types";