@cloudflare/sandbox 0.0.0-d55b0f4 → 0.0.0-d670ba2

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/file-stream.ts

@@ -0,0 +1,162 @@
+/**
+ * File streaming utilities for reading binary and text files
+ * Provides simple AsyncIterable API over SSE stream with automatic base64 decoding
+ */
+
+import { parseSSEStream } from './sse-parser';
+import type { FileChunk, FileMetadata, FileStreamEvent } from './types';
+
+/**
+ * Convert ReadableStream of SSE file events to AsyncIterable of file chunks
+ * Automatically decodes base64 for binary files and provides metadata
+ *
+ * @param stream - The SSE ReadableStream from readFileStream()
+ * @param signal - Optional AbortSignal for cancellation
+ * @returns AsyncIterable that yields file chunks (string for text, Uint8Array for binary)
+ *
+ * @example
+ * ```typescript
+ * const stream = await sandbox.readFileStream('/path/to/file.png');
+ *
+ * for await (const chunk of streamFile(stream)) {
+ *   if (chunk instanceof Uint8Array) {
+ *     // Binary chunk - already decoded from base64
+ *     console.log('Binary chunk:', chunk.byteLength, 'bytes');
+ *   } else {
+ *     // Text chunk
+ *     console.log('Text chunk:', chunk);
+ *   }
+ * }
+ *
+ * // Access metadata
+ * const iter = streamFile(stream);
+ * for await (const chunk of iter) {
+ *   console.log('MIME type:', iter.metadata?.mimeType);
+ *   // process chunk...
+ * }
+ * ```
+ */
+export async function* streamFile(
+  stream: ReadableStream<Uint8Array>,
+  signal?: AbortSignal
+): AsyncGenerator<FileChunk, void, undefined> {
+  let metadata: FileMetadata | undefined;
+
+  try {
+    for await (const event of parseSSEStream<FileStreamEvent>(stream, signal)) {
+      switch (event.type) {
+        case 'metadata':
+          // Store metadata for access via iterator
+          metadata = {
+            mimeType: event.mimeType,
+            size: event.size,
+            isBinary: event.isBinary,
+            encoding: event.encoding,
+          };
+          // Store on generator function for external access
+          (streamFile as any).metadata = metadata;
+          break;
+
+        case 'chunk':
+          // Auto-decode base64 for binary files
+          if (metadata?.isBinary && metadata?.encoding === 'base64') {
+            // Decode base64 to Uint8Array
+            const binaryString = atob(event.data);
+            const bytes = new Uint8Array(binaryString.length);
+            for (let i = 0; i < binaryString.length; i++) {
+              bytes[i] = binaryString.charCodeAt(i);
+            }
+            yield bytes;
+          } else {
+            // Text file - yield as-is
+            yield event.data;
+          }
+          break;
+
+        case 'complete':
+          // Stream completed successfully
+          console.log(`[streamFile] File streaming complete: ${event.bytesRead} bytes read`);
+          return;
+
+        case 'error':
+          // Stream error
+          throw new Error(`File streaming error: ${event.error}`);
+      }
+    }
+  } catch (error) {
+    console.error('[streamFile] Error streaming file:', error);
+    throw error;
+  }
+}
+
+/**
+ * Helper to collect entire file from stream into memory
+ * Useful for smaller files where you want the complete content at once
+ *
+ * @param stream - The SSE ReadableStream from readFileStream()
+ * @param signal - Optional AbortSignal for cancellation
+ * @returns Object with content (string or Uint8Array) and metadata
+ *
+ * @example
+ * ```typescript
+ * const stream = await sandbox.readFileStream('/path/to/image.png');
+ * const { content, metadata } = await collectFile(stream);
+ *
+ * if (content instanceof Uint8Array) {
+ *   console.log('Binary file:', metadata.mimeType, content.byteLength, 'bytes');
+ * } else {
+ *   console.log('Text file:', metadata.mimeType, content.length, 'chars');
+ * }
+ * ```
+ */
+export async function collectFile(
+  stream: ReadableStream<Uint8Array>,
+  signal?: AbortSignal
+): Promise<{ content: string | Uint8Array; metadata: FileMetadata }> {
+  let metadata: FileMetadata | undefined;
+  const chunks: FileChunk[] = [];
+
+  for await (const chunk of streamFile(stream, signal)) {
+    chunks.push(chunk);
+    // Capture metadata from first iteration
+    if (!metadata && (streamFile as any).metadata) {
+      metadata = (streamFile as any).metadata;
+    }
+  }
+
+  if (!metadata) {
+    throw new Error('No metadata received from file stream');
+  }
+
+  // Combine chunks based on type
+  if (chunks.length === 0) {
+    // Empty file
+    return {
+      content: metadata.isBinary ? new Uint8Array(0) : '',
+      metadata,
+    };
+  }
+
+  // Check if binary or text based on first chunk
+  if (chunks[0] instanceof Uint8Array) {
+    // Binary file - concatenate Uint8Arrays
+    const totalLength = chunks.reduce((sum, chunk) => {
+      return sum + (chunk as Uint8Array).byteLength;
+    }, 0);
+
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk as Uint8Array, offset);
+      offset += (chunk as Uint8Array).byteLength;
+    }
+
+    return { content: result, metadata };
+  } else {
+    // Text file - concatenate strings
+    return {
+      content: chunks.join(''),
+      metadata,
+    };
+  }
+}

package/src/index.ts

@@ -1,20 +1,81 @@
-// 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 file streaming utilities
+export { streamFile, collectFile } from "./file-stream";
+export type {
+  DeleteFileResponse,
+  ExecEvent,
+  ExecOptions,
+  ExecResult,
+  ExecuteResponse,
+  ExecutionSession,
+  FileChunk,
+  FileMetadata,
+  FileStream,
+  FileStreamEvent,
+  GitCheckoutResponse,
+  ISandbox,
+  ListFilesResponse,
+  LogEvent,
+  MkdirResponse,
+  MoveFileResponse,
+  Process,
+  ProcessOptions,
+  ProcessStatus,
+  ReadFileResponse,
+  RenameFileResponse,
+  StreamOptions,
+  WriteFileResponse,
+} from "./types";