@cloudflare/sandbox 0.0.0-dc66e8e → 0.0.0-e943505

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,20 +1,75 @@
-// Export types from client
-export type {
-  DeleteFileResponse, ExecuteResponse,
-  GitCheckoutResponse,
-  MkdirResponse, MoveFileResponse,
-  ReadFileResponse, RenameFileResponse, WriteFileResponse
-} 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";
 
-// Re-export request handler utilities
+/**
+ * @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 API response types
 export {
-  proxyToSandbox, type RouteInfo, type SandboxEnv
-} from './request-handler';
+  CodeExecutionError,
+  ContainerNotReadyError,
+  ContextNotFoundError,
+  InterpreterNotReadyError,
+  isInterpreterNotReadyError,
+  isRetryableError,
+  isSandboxError,
+  parseErrorResponse,
+  SandboxError,
+  type SandboxErrorResponse,
+  SandboxNetworkError,
+  ServiceUnavailableError,
+} from "./errors";
 
+// 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 event types for streaming
-export type { ExecEvent, LogEvent } from "./types";
+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";

package/src/interpreter-client.ts

@@ -0,0 +1,352 @@
+import { HttpClient } from "./client.js";
+import { isRetryableError, parseErrorResponse } from "./errors.js";
+import type {
+  CodeContext,
+  CreateContextOptions,
+  ExecutionError,
+  OutputMessage,
+  Result,
+} from "./interpreter-types.js";
+
+// API Response types
+interface ContextResponse {
+  id: string;
+  language: string;
+  cwd: string;
+  createdAt: string; // ISO date string from JSON
+  lastUsed: string; // ISO date string from JSON
+}
+
+interface ContextListResponse {
+  contexts: ContextResponse[];
+}
+
+// Streaming execution data from the server
+interface StreamingExecutionData {
+  type: "result" | "stdout" | "stderr" | "error" | "execution_complete";
+  text?: string;
+  html?: string;
+  png?: string; // base64
+  jpeg?: string; // base64
+  svg?: string;
+  latex?: string;
+  markdown?: string;
+  javascript?: string;
+  json?: unknown;
+  chart?: {
+    type:
+      | "line"
+      | "bar"
+      | "scatter"
+      | "pie"
+      | "histogram"
+      | "heatmap"
+      | "unknown";
+    data: unknown;
+    options?: unknown;
+  };
+  data?: unknown;
+  metadata?: Record<string, unknown>;
+  execution_count?: number;
+  ename?: string;
+  evalue?: string;
+  traceback?: string[];
+  lineNumber?: number;
+  timestamp?: number;
+}
+
+export interface ExecutionCallbacks {
+  onStdout?: (output: OutputMessage) => void | Promise<void>;
+  onStderr?: (output: OutputMessage) => void | Promise<void>;
+  onResult?: (result: Result) => void | Promise<void>;
+  onError?: (error: ExecutionError) => void | Promise<void>;
+}
+
+export class InterpreterClient extends HttpClient {
+  private readonly maxRetries = 3;
+  private readonly retryDelayMs = 1000;
+
+  async createCodeContext(
+    options: CreateContextOptions = {}
+  ): Promise<CodeContext> {
+    return this.executeWithRetry(async () => {
+      const response = await this.doFetch("/api/contexts", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          language: options.language || "python",
+          cwd: options.cwd || "/workspace",
+          env_vars: options.envVars,
+        }),
+      });
+
+      if (!response.ok) {
+        throw await parseErrorResponse(response);
+      }
+
+      const data = (await response.json()) as ContextResponse;
+      return {
+        id: data.id,
+        language: data.language,
+        cwd: data.cwd,
+        createdAt: new Date(data.createdAt),
+        lastUsed: new Date(data.lastUsed),
+      };
+    });
+  }
+
+  async runCodeStream(
+    contextId: string | undefined,
+    code: string,
+    language: string | undefined,
+    callbacks: ExecutionCallbacks
+  ): Promise<void> {
+    return this.executeWithRetry(async () => {
+      const response = await this.doFetch("/api/execute/code", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "text/event-stream",
+        },
+        body: JSON.stringify({
+          context_id: contextId,
+          code,
+          language,
+        }),
+      });
+
+      if (!response.ok) {
+        throw await parseErrorResponse(response);
+      }
+
+      if (!response.body) {
+        throw new Error("No response body for streaming execution");
+      }
+
+      // Process streaming response
+      for await (const chunk of this.readLines(response.body)) {
+        await this.parseExecutionResult(chunk, callbacks);
+      }
+    });
+  }
+
+  private async *readLines(
+    stream: ReadableStream<Uint8Array>
+  ): AsyncGenerator<string> {
+    const reader = stream.getReader();
+    let buffer = "";
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (value) {
+          buffer += new TextDecoder().decode(value);
+        }
+        if (done) break;
+
+        let newlineIdx = buffer.indexOf("\n");
+        while (newlineIdx !== -1) {
+          yield buffer.slice(0, newlineIdx);
+          buffer = buffer.slice(newlineIdx + 1);
+          newlineIdx = buffer.indexOf("\n");
+        }
+      }
+
+      // Yield any remaining data
+      if (buffer.length > 0) {
+        yield buffer;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  private async parseExecutionResult(
+    line: string,
+    callbacks: ExecutionCallbacks
+  ) {
+    if (!line.trim()) return;
+
+    try {
+      const data = JSON.parse(line) as StreamingExecutionData;
+
+      switch (data.type) {
+        case "stdout":
+          if (callbacks.onStdout && data.text) {
+            await callbacks.onStdout({
+              text: data.text,
+              timestamp: data.timestamp || Date.now(),
+            });
+          }
+          break;
+
+        case "stderr":
+          if (callbacks.onStderr && data.text) {
+            await callbacks.onStderr({
+              text: data.text,
+              timestamp: data.timestamp || Date.now(),
+            });
+          }
+          break;
+
+        case "result":
+          if (callbacks.onResult) {
+            // Convert raw result to Result interface
+            const result: Result = {
+              text: data.text,
+              html: data.html,
+              png: data.png,
+              jpeg: data.jpeg,
+              svg: data.svg,
+              latex: data.latex,
+              markdown: data.markdown,
+              javascript: data.javascript,
+              json: data.json,
+              chart: data.chart,
+              data: data.data,
+              formats: () => {
+                const formats: string[] = [];
+                if (data.text) formats.push("text");
+                if (data.html) formats.push("html");
+                if (data.png) formats.push("png");
+                if (data.jpeg) formats.push("jpeg");
+                if (data.svg) formats.push("svg");
+                if (data.latex) formats.push("latex");
+                if (data.markdown) formats.push("markdown");
+                if (data.javascript) formats.push("javascript");
+                if (data.json) formats.push("json");
+                if (data.chart) formats.push("chart");
+                return formats;
+              },
+            };
+            await callbacks.onResult(result);
+          }
+          break;
+
+        case "error":
+          if (callbacks.onError) {
+            await callbacks.onError({
+              name: data.ename || "Error",
+              value: data.evalue || data.text || "Unknown error",
+              traceback: data.traceback || [],
+              lineNumber: data.lineNumber,
+            });
+          }
+          break;
+
+        case "execution_complete":
+          // Execution completed successfully
+          break;
+      }
+    } catch (error) {
+      console.error(
+        "[InterpreterClient] Error parsing execution result:",
+        error
+      );
+    }
+  }
+
+  async listCodeContexts(): Promise<CodeContext[]> {
+    return this.executeWithRetry(async () => {
+      const response = await this.doFetch("/api/contexts", {
+        method: "GET",
+        headers: { "Content-Type": "application/json" },
+      });
+
+      if (!response.ok) {
+        throw await parseErrorResponse(response);
+      }
+
+      const data = (await response.json()) as ContextListResponse;
+      return data.contexts.map((ctx) => ({
+        id: ctx.id,
+        language: ctx.language,
+        cwd: ctx.cwd,
+        createdAt: new Date(ctx.createdAt),
+        lastUsed: new Date(ctx.lastUsed),
+      }));
+    });
+  }
+
+  async deleteCodeContext(contextId: string): Promise<void> {
+    return this.executeWithRetry(async () => {
+      const response = await this.doFetch(`/api/contexts/${contextId}`, {
+        method: "DELETE",
+        headers: { "Content-Type": "application/json" },
+      });
+
+      if (!response.ok) {
+        throw await parseErrorResponse(response);
+      }
+    });
+  }
+
+  // Override parent doFetch to be public for this class
+  public async doFetch(path: string, options?: RequestInit): Promise<Response> {
+    return super.doFetch(path, options);
+  }
+
+  /**
+   * Execute an operation with automatic retry for transient errors
+   */
+  private async executeWithRetry<T>(operation: () => Promise<T>): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        return await operation();
+      } catch (error) {
+        lastError = error as Error;
+
+        // Check if it's a retryable error (circuit breaker or interpreter not ready)
+        if (this.isRetryableError(error)) {
+          // Don't retry on the last attempt
+          if (attempt < this.maxRetries - 1) {
+            // Exponential backoff with jitter
+            const delay =
+              this.retryDelayMs * 2 ** attempt + Math.random() * 1000;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            continue;
+          }
+        }
+
+        // Non-retryable error or last attempt - throw immediately
+        throw error;
+      }
+    }
+
+    // All retries exhausted - throw a clean error without implementation details
+    if (lastError?.message.includes("Code execution")) {
+      // If the error already has a clean message about code execution, use it
+      throw lastError;
+    }
+
+    // Otherwise, throw a generic but user-friendly error
+    throw new Error("Unable to execute code at this time");
+  }
+
+  /**
+   * Check if an error is retryable
+   */
+  private isRetryableError(error: unknown): boolean {
+    // Use the SDK's built-in retryable check
+    if (isRetryableError(error)) {
+      return true;
+    }
+
+    // Also check for circuit breaker specific errors
+    if (error instanceof Error) {
+      // Circuit breaker errors (from the container's response)
+      if (error.message.includes("Circuit breaker is open")) {
+        return true;
+      }
+
+      // Check if error has a status property
+      if ("status" in error && error.status === "circuit_open") {
+        return true;
+      }
+    }
+
+    return false;
+  }
+}