@cloudflare/sandbox 0.0.0-c87db11 → 0.0.0-cdb8197

package/src/errors.ts

@@ -23,17 +23,17 @@ export class SandboxError extends Error {
 }
 
 /**
- * Error thrown when Jupyter functionality is requested but the service is still initializing.
+ * Error thrown when interpreter functionality is requested but the service is still initializing.
  *
- * Note: With the current implementation, requests wait for Jupyter to be ready.
+ * 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 Jupyter (default: 30 seconds)
- * 2. Jupyter initialization actually fails
+ * 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 JupyterNotReadyError extends SandboxError {
-  public readonly code = "JUPYTER_NOT_READY";
+export class InterpreterNotReadyError extends SandboxError {
+  public readonly code = "INTERPRETER_NOT_READY";
   public readonly retryAfter: number;
   public readonly progress?: number;
 
@@ -42,7 +42,8 @@ export class JupyterNotReadyError extends SandboxError {
     options?: { retryAfter?: number; progress?: number }
   ) {
     super(
-      message || "Jupyter is still initializing. Please retry in a few seconds."
+      message ||
+        "Interpreter is still initializing. Please retry in a few seconds."
     );
     this.retryAfter = options?.retryAfter || 5;
     this.progress = options?.progress;
@@ -123,12 +124,12 @@ export class ServiceUnavailableError extends SandboxError {
 }
 
 /**
- * Type guard to check if an error is a JupyterNotReadyError
+ * Type guard to check if an error is a InterpreterNotReadyError
  */
-export function isJupyterNotReadyError(
+export function isInterpreterNotReadyError(
   error: unknown
-): error is JupyterNotReadyError {
-  return error instanceof JupyterNotReadyError;
+): error is InterpreterNotReadyError {
+  return error instanceof InterpreterNotReadyError;
 }
 
 /**
@@ -143,7 +144,7 @@ export function isSandboxError(error: unknown): error is SandboxError {
  */
 export function isRetryableError(error: unknown): boolean {
   if (
-    error instanceof JupyterNotReadyError ||
+    error instanceof InterpreterNotReadyError ||
     error instanceof ContainerNotReadyError ||
     error instanceof ServiceUnavailableError
   ) {
@@ -189,9 +190,9 @@ export async function parseErrorResponse(
       );
     }
 
-    // Jupyter initialization error
+    // Interpreter initialization error
     if (data.status === "initializing") {
-      return new JupyterNotReadyError(data.error, {
+      return new InterpreterNotReadyError(data.error, {
         retryAfter: parseInt(response.headers.get("Retry-After") || "5"),
         progress: data.progress,
       });

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,29 +1,31 @@
-// Export types from client
-export type {
-  DeleteFileResponse,
-  ExecuteResponse,
-  GitCheckoutResponse,
-  MkdirResponse,
-  MoveFileResponse,
-  ReadFileResponse,
-  RenameFileResponse,
-  WriteFileResponse,
-} from "./client";
-// Export errors
+// 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 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,
@@ -50,5 +52,30 @@ export {
   parseSSEStream,
   responseToAsyncIterable,
 } from "./sse-parser";
-// Export event types for streaming
-export type { ExecEvent, LogEvent } from "./types";
+// 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";

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) {