@cloudflare/sandbox 0.0.0-603d05f → 0.0.0-66cc85b

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,31 @@
-// Export API response types
+// 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";
+
+/**
+ * @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 errors
+// Export API response types
 export {
   CodeExecutionError,
   ContainerNotReadyError,
   ContextNotFoundError,
-  isJupyterNotReadyError,
+  InterpreterNotReadyError,
+  isInterpreterNotReadyError,
   isRetryableError,
   isSandboxError,
-  JupyterNotReadyError,
   parseErrorResponse,
   SandboxError,
   type SandboxErrorResponse,
   SandboxNetworkError,
   ServiceUnavailableError,
 } from "./errors";
+
 // Export code interpreter types
 export type {
   ChartData,
@@ -41,6 +52,8 @@ export {
   parseSSEStream,
   responseToAsyncIterable,
 } from "./sse-parser";
+// Export file streaming utilities
+export { streamFile, collectFile } from "./file-stream";
 export type {
   DeleteFileResponse,
   ExecEvent,
@@ -48,6 +61,10 @@ export type {
   ExecResult,
   ExecuteResponse,
   ExecutionSession,
+  FileChunk,
+  FileMetadata,
+  FileStream,
+  FileStreamEvent,
   GitCheckoutResponse,
   ISandbox,
   ListFilesResponse,
@@ -60,5 +77,5 @@ export type {
   ReadFileResponse,
   RenameFileResponse,
   StreamOptions,
-  WriteFileResponse
+  WriteFileResponse,
 } from "./types";

package/src/{jupyter-client.ts → interpreter-client.ts}

@@ -62,7 +62,7 @@ export interface ExecutionCallbacks {
   onError?: (error: ExecutionError) => void | Promise<void>;
 }
 
-export class JupyterClient extends HttpClient {
+export class InterpreterClient extends HttpClient {
   private readonly maxRetries = 3;
   private readonly retryDelayMs = 1000;
 
@@ -239,7 +239,10 @@ export class JupyterClient extends HttpClient {
           break;
       }
     } catch (error) {
-      console.error("[JupyterClient] Error parsing execution result:", error);
+      console.error(
+        "[InterpreterClient] Error parsing execution result:",
+        error
+      );
     }
   }
 
@@ -295,7 +298,7 @@ export class JupyterClient extends HttpClient {
       } catch (error) {
         lastError = error as Error;
 
-        // Check if it's a retryable error (circuit breaker or Jupyter not ready)
+        // 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) {

package/src/interpreter-types.ts

@@ -4,19 +4,19 @@ export interface CreateContextOptions {
    * Programming language for the context
    * @default 'python'
    */
-  language?: 'python' | 'javascript' | 'typescript';
-  
+  language?: "python" | "javascript" | "typescript";
+
   /**
    * Working directory for the context
    * @default '/workspace'
    */
   cwd?: string;
-  
+
   /**
    * Environment variables for the context
    */
   envVars?: Record<string, string>;
-  
+
   /**
    * Request timeout in milliseconds
    * @default 30000
@@ -29,22 +29,22 @@ export interface CodeContext {
    * Unique identifier for the context
    */
   readonly id: string;
-  
+
   /**
    * Programming language of the context
    */
   readonly language: string;
-  
+
   /**
    * Current working directory
    */
   readonly cwd: string;
-  
+
   /**
    * When the context was created
    */
   readonly createdAt: Date;
-  
+
   /**
    * When the context was last used
    */
@@ -57,44 +57,44 @@ export interface RunCodeOptions {
    * Context to run the code in. If not provided, uses default context for the language
    */
   context?: CodeContext;
-  
+
   /**
    * Language to use if context is not provided
    * @default 'python'
    */
-  language?: 'python' | 'javascript' | 'typescript';
-  
+  language?: "python" | "javascript" | "typescript";
+
   /**
    * Environment variables for this execution
    */
   envVars?: Record<string, string>;
-  
+
   /**
    * Execution timeout in milliseconds
    * @default 60000
    */
   timeout?: number;
-  
+
   /**
    * AbortSignal for cancelling execution
    */
   signal?: AbortSignal;
-  
+
   /**
    * Callback for stdout output
    */
   onStdout?: (output: OutputMessage) => void | Promise<void>;
-  
+
   /**
    * Callback for stderr output
    */
   onStderr?: (output: OutputMessage) => void | Promise<void>;
-  
+
   /**
    * Callback for execution results (charts, tables, etc)
    */
   onResult?: (result: Result) => void | Promise<void>;
-  
+
   /**
    * Callback for execution errors
    */
@@ -107,7 +107,7 @@ export interface OutputMessage {
    * The output text
    */
   text: string;
-  
+
   /**
    * Timestamp of the output
    */
@@ -120,57 +120,57 @@ export interface Result {
    * Plain text representation
    */
   text?: string;
-  
+
   /**
    * HTML representation (tables, formatted output)
    */
   html?: string;
-  
+
   /**
    * PNG image data (base64 encoded)
    */
   png?: string;
-  
+
   /**
    * JPEG image data (base64 encoded)
    */
   jpeg?: string;
-  
+
   /**
    * SVG image data
    */
   svg?: string;
-  
+
   /**
    * LaTeX representation
    */
   latex?: string;
-  
+
   /**
    * Markdown representation
    */
   markdown?: string;
-  
+
   /**
    * JavaScript code to execute
    */
   javascript?: string;
-  
+
   /**
    * JSON data
    */
   json?: any;
-  
+
   /**
    * Chart data if the result is a visualization
    */
   chart?: ChartData;
-  
+
   /**
    * Raw data object
    */
   data?: any;
-  
+
   /**
    * Available output formats
    */
@@ -182,33 +182,40 @@ export interface ChartData {
   /**
    * Type of chart
    */
-  type: 'line' | 'bar' | 'scatter' | 'pie' | 'histogram' | 'heatmap' | 'unknown';
-  
+  type:
+    | "line"
+    | "bar"
+    | "scatter"
+    | "pie"
+    | "histogram"
+    | "heatmap"
+    | "unknown";
+
   /**
    * Chart title
    */
   title?: string;
-  
+
   /**
    * Chart data (format depends on library)
    */
   data: any;
-  
+
   /**
    * Chart layout/configuration
    */
   layout?: any;
-  
+
   /**
    * Additional configuration
    */
   config?: any;
-  
+
   /**
    * Library that generated the chart
    */
-  library?: 'matplotlib' | 'plotly' | 'altair' | 'seaborn' | 'unknown';
-  
+  library?: "matplotlib" | "plotly" | "altair" | "seaborn" | "unknown";
+
   /**
    * Base64 encoded image if available
    */
@@ -221,17 +228,17 @@ export interface ExecutionError {
    * Error name/type (e.g., 'NameError', 'SyntaxError')
    */
   name: string;
-  
+
   /**
    * Error message
    */
   value: string;
-  
+
   /**
    * Stack trace
    */
   traceback: string[];
-  
+
   /**
    * Line number where error occurred
    */
@@ -268,30 +275,30 @@ export class Execution {
    * All results from the execution
    */
   public results: Result[] = [];
-  
+
   /**
    * Accumulated stdout and stderr
    */
   public logs = {
     stdout: [] as string[],
-    stderr: [] as string[]
+    stderr: [] as string[],
   };
-  
+
   /**
    * Execution error if any
    */
   public error?: ExecutionError;
-  
+
   /**
-   * Execution count (for Jupyter)
+   * Execution count (for interpreter)
    */
   public executionCount?: number;
-  
+
   constructor(
     public readonly code: string,
     public readonly context: CodeContext
   ) {}
-  
+
   /**
    * Convert to a plain object for serialization
    */
@@ -301,7 +308,7 @@ export class Execution {
       logs: this.logs,
       error: this.error,
       executionCount: this.executionCount,
-      results: this.results.map(result => ({
+      results: this.results.map((result) => ({
         text: result.text,
         html: result.html,
         png: result.png,
@@ -312,8 +319,8 @@ export class Execution {
         javascript: result.javascript,
         json: result.json,
         chart: result.chart,
-        data: result.data
-      }))
+        data: result.data,
+      })),
     };
   }
 }
@@ -321,63 +328,63 @@ export class Execution {
 // Implementation of Result
 export class ResultImpl implements Result {
   constructor(private raw: any) {}
-  
-  get text(): string | undefined { 
-    return this.raw.text || this.raw.data?.['text/plain']; 
+
+  get text(): string | undefined {
+    return this.raw.text || this.raw.data?.["text/plain"];
   }
-  
-  get html(): string | undefined { 
-    return this.raw.html || this.raw.data?.['text/html']; 
+
+  get html(): string | undefined {
+    return this.raw.html || this.raw.data?.["text/html"];
   }
-  
-  get png(): string | undefined { 
-    return this.raw.png || this.raw.data?.['image/png']; 
+
+  get png(): string | undefined {
+    return this.raw.png || this.raw.data?.["image/png"];
   }
-  
-  get jpeg(): string | undefined { 
-    return this.raw.jpeg || this.raw.data?.['image/jpeg']; 
+
+  get jpeg(): string | undefined {
+    return this.raw.jpeg || this.raw.data?.["image/jpeg"];
   }
-  
-  get svg(): string | undefined { 
-    return this.raw.svg || this.raw.data?.['image/svg+xml']; 
+
+  get svg(): string | undefined {
+    return this.raw.svg || this.raw.data?.["image/svg+xml"];
   }
-  
-  get latex(): string | undefined { 
-    return this.raw.latex || this.raw.data?.['text/latex']; 
+
+  get latex(): string | undefined {
+    return this.raw.latex || this.raw.data?.["text/latex"];
   }
-  
-  get markdown(): string | undefined { 
-    return this.raw.markdown || this.raw.data?.['text/markdown']; 
+
+  get markdown(): string | undefined {
+    return this.raw.markdown || this.raw.data?.["text/markdown"];
   }
-  
-  get javascript(): string | undefined { 
-    return this.raw.javascript || this.raw.data?.['application/javascript']; 
+
+  get javascript(): string | undefined {
+    return this.raw.javascript || this.raw.data?.["application/javascript"];
   }
-  
-  get json(): any { 
-    return this.raw.json || this.raw.data?.['application/json']; 
+
+  get json(): any {
+    return this.raw.json || this.raw.data?.["application/json"];
   }
-  
-  get chart(): ChartData | undefined { 
-    return this.raw.chart; 
+
+  get chart(): ChartData | undefined {
+    return this.raw.chart;
   }
-  
-  get data(): any { 
-    return this.raw.data; 
+
+  get data(): any {
+    return this.raw.data;
   }
-  
+
   formats(): string[] {
     const formats: string[] = [];
-    if (this.text) formats.push('text');
-    if (this.html) formats.push('html');
-    if (this.png) formats.push('png');
-    if (this.jpeg) formats.push('jpeg');
-    if (this.svg) formats.push('svg');
-    if (this.latex) formats.push('latex');
-    if (this.markdown) formats.push('markdown');
-    if (this.javascript) formats.push('javascript');
-    if (this.json) formats.push('json');
-    if (this.chart) formats.push('chart');
+    if (this.text) formats.push("text");
+    if (this.html) formats.push("html");
+    if (this.png) formats.push("png");
+    if (this.jpeg) formats.push("jpeg");
+    if (this.svg) formats.push("svg");
+    if (this.latex) formats.push("latex");
+    if (this.markdown) formats.push("markdown");
+    if (this.javascript) formats.push("javascript");
+    if (this.json) formats.push("json");
+    if (this.chart) formats.push("chart");
     return formats;
   }
-}
+}