@cloudflare/sandbox 0.0.0-1dfb064 → 0.0.0-2011e85

package/src/file-stream.ts

@@ -0,0 +1,169 @@
+import type { FileChunk, FileMetadata, FileStreamEvent } from '@repo/shared';
+
+/**
+ * Parse SSE (Server-Sent Events) lines from a stream
+ */
+async function* parseSSE(
+  stream: ReadableStream<Uint8Array>
+): AsyncGenerator<FileStreamEvent> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+
+      if (done) {
+        break;
+      }
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
+
+      // Keep the last incomplete line in the buffer
+      buffer = lines.pop() || '';
+
+      for (const line of lines) {
+        if (line.startsWith('data: ')) {
+          const data = line.slice(6); // Remove 'data: ' prefix
+          try {
+            const event = JSON.parse(data) as FileStreamEvent;
+            yield event;
+          } catch {
+            // Skip invalid JSON events and continue processing
+          }
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/**
+ * Stream a file from the sandbox with automatic base64 decoding for binary files
+ *
+ * @param stream - The ReadableStream from readFileStream()
+ * @returns AsyncGenerator that yields FileChunk (string for text, Uint8Array for binary)
+ *
+ * @example
+ * ```ts
+ * const stream = await sandbox.readFileStream('/path/to/file.png');
+ * for await (const chunk of streamFile(stream)) {
+ *   if (chunk instanceof Uint8Array) {
+ *     // Binary chunk
+ *     console.log('Binary chunk:', chunk.length, 'bytes');
+ *   } else {
+ *     // Text chunk
+ *     console.log('Text chunk:', chunk);
+ *   }
+ * }
+ * ```
+ */
+export async function* streamFile(
+  stream: ReadableStream<Uint8Array>
+): AsyncGenerator<FileChunk, FileMetadata> {
+  let metadata: FileMetadata | null = null;
+
+  for await (const event of parseSSE(stream)) {
+    switch (event.type) {
+      case 'metadata':
+        metadata = {
+          mimeType: event.mimeType,
+          size: event.size,
+          isBinary: event.isBinary,
+          encoding: event.encoding
+        };
+        break;
+
+      case 'chunk':
+        if (!metadata) {
+          throw new Error('Received chunk before metadata');
+        }
+
+        if (metadata.isBinary && metadata.encoding === 'base64') {
+          // Decode base64 to Uint8Array for binary files
+          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 files - yield as-is
+          yield event.data;
+        }
+        break;
+
+      case 'complete':
+        if (!metadata) {
+          throw new Error('Stream completed without metadata');
+        }
+        return metadata;
+
+      case 'error':
+        throw new Error(`File streaming error: ${event.error}`);
+    }
+  }
+
+  throw new Error('Stream ended unexpectedly');
+}
+
+/**
+ * Collect an entire file into memory from a stream
+ *
+ * @param stream - The ReadableStream from readFileStream()
+ * @returns Object containing the file content and metadata
+ *
+ * @example
+ * ```ts
+ * const stream = await sandbox.readFileStream('/path/to/file.txt');
+ * const { content, metadata } = await collectFile(stream);
+ * console.log('Content:', content);
+ * console.log('MIME type:', metadata.mimeType);
+ * ```
+ */
+export async function collectFile(stream: ReadableStream<Uint8Array>): Promise<{
+  content: string | Uint8Array;
+  metadata: FileMetadata;
+}> {
+  const chunks: Array<string | Uint8Array> = [];
+
+  // Iterate through the generator and get the return value (metadata)
+  const generator = streamFile(stream);
+  let result = await generator.next();
+
+  while (!result.done) {
+    chunks.push(result.value);
+    result = await generator.next();
+  }
+
+  const metadata = result.value;
+
+  if (!metadata) {
+    throw new Error('Failed to get file metadata');
+  }
+
+  // Combine chunks based on type
+  if (metadata.isBinary) {
+    // Binary file - combine Uint8Arrays
+    const totalLength = chunks.reduce(
+      (sum, chunk) => sum + (chunk instanceof Uint8Array ? chunk.length : 0),
+      0
+    );
+    const combined = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      if (chunk instanceof Uint8Array) {
+        combined.set(chunk, offset);
+        offset += chunk.length;
+      }
+    }
+    return { content: combined, metadata };
+  } else {
+    // Text file - combine strings
+    const combined = chunks.filter((c) => typeof c === 'string').join('');
+    return { content: combined, metadata };
+  }
+}

package/src/index.ts

@@ -1,64 +1,100 @@
-// Export API response types
+// Export the main Sandbox class and utilities
 
-// Export errors
+// Export the new client architecture
 export {
-  CodeExecutionError,
-  ContainerNotReadyError,
-  ContextNotFoundError,
-  isJupyterNotReadyError,
-  isRetryableError,
-  isSandboxError,
-  JupyterNotReadyError,
-  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";
+  CommandClient,
+  FileClient,
+  GitClient,
+  PortClient,
+  ProcessClient,
+  SandboxClient,
+  UtilityClient
+} from './clients';
+export { getSandbox, Sandbox } from './sandbox';
+
+// Legacy types are now imported from the new client architecture
+
+// Export core SDK types for consumers
 export type {
-  DeleteFileResponse,
+  BaseExecOptions,
   ExecEvent,
   ExecOptions,
   ExecResult,
-  ExecuteResponse,
-  ExecutionSession,
-  GitCheckoutResponse,
+  FileChunk,
+  FileMetadata,
+  FileStreamEvent,
   ISandbox,
-  ListFilesResponse,
   LogEvent,
-  MkdirResponse,
-  MoveFileResponse,
   Process,
   ProcessOptions,
   ProcessStatus,
-  ReadFileResponse,
-  RenameFileResponse,
-  StreamOptions,
-  WriteFileResponse
-} from "./types";
+  StreamOptions
+} from '@repo/shared';
+export * from '@repo/shared';
+// Export type guards for runtime validation
+export { isExecResult, isProcess, isProcessStatus } from '@repo/shared';
+// Export all client types from new architecture
+export type {
+  BaseApiResponse,
+  CommandsResponse,
+  ContainerStub,
+  ErrorResponse,
+
+  // Command client types
+  ExecuteRequest,
+  ExecuteResponse as CommandExecuteResponse,
+
+  // Port client types
+  ExposePortRequest,
+  FileOperationRequest,
+
+  // Git client types
+  GitCheckoutRequest,
+  GitCheckoutResult,
+  // Base client types
+  HttpClientOptions as SandboxClientOptions,
+
+  // File client types
+  MkdirRequest,
+
+  // Utility client types
+  PingResponse,
+  PortCloseResult,
+  PortExposeResult,
+  PortListResult,
+  ProcessCleanupResult,
+  ProcessInfoResult,
+  ProcessKillResult,
+  ProcessListResult,
+  ProcessLogsResult,
+  ProcessStartResult,
+  ReadFileRequest,
+  RequestConfig,
+  ResponseHandler,
+  SessionRequest,
+
+  // Process client types
+  StartProcessRequest,
+  UnexposePortRequest,
+  WriteFileRequest
+} from './clients';
+export type {
+  ExecutionCallbacks,
+  InterpreterClient
+} from './clients/interpreter-client.js';
+// Export file streaming utilities for binary file support
+export { collectFile, streamFile } from './file-stream';
+// Export interpreter functionality
+export { CodeInterpreter } from './interpreter.js';
+// Re-export request handler utilities
+export {
+  proxyToSandbox,
+  type RouteInfo,
+  type SandboxEnv
+} from './request-handler';
+// Export SSE parser for converting ReadableStream to AsyncIterable
+export {
+  asyncIterableToSSEStream,
+  parseSSEStream,
+  responseToAsyncIterable
+} from './sse-parser';

package/src/interpreter.ts

@@ -2,18 +2,24 @@ import {
   type CodeContext,
   type CreateContextOptions,
   Execution,
+  type ExecutionError,
+  type OutputMessage,
+  type Result,
   ResultImpl,
-  type RunCodeOptions,
-} from "./interpreter-types.js";
-import type { JupyterClient } from "./jupyter-client.js";
-import type { Sandbox } from "./sandbox.js";
+  type RunCodeOptions
+} from '@repo/shared';
+import type { InterpreterClient } from './clients/interpreter-client.js';
+import type { Sandbox } from './sandbox.js';
+import { validateLanguage } from './security.js';
 
 export class CodeInterpreter {
-  private jupyterClient: JupyterClient;
+  private interpreterClient: InterpreterClient;
   private contexts = new Map<string, CodeContext>();
 
   constructor(sandbox: Sandbox) {
-    this.jupyterClient = sandbox.client as JupyterClient;
+    // In init-testing architecture, client is a SandboxClient with an interpreter property
+    this.interpreterClient = (sandbox.client as any)
+      .interpreter as InterpreterClient;
   }
 
   /**
@@ -22,7 +28,10 @@ export class CodeInterpreter {
   async createCodeContext(
     options: CreateContextOptions = {}
   ): Promise<CodeContext> {
-    const context = await this.jupyterClient.createCodeContext(options);
+    // Validate language before sending to container
+    validateLanguage(options.language);
+
+    const context = await this.interpreterClient.createCodeContext(options);
     this.contexts.set(context.id, context);
     return context;
   }
@@ -38,7 +47,7 @@ export class CodeInterpreter {
     let context = options.context;
     if (!context) {
       // Try to find or create a default context for the language
-      const language = options.language || "python";
+      const language = options.language || 'python';
       context = await this.getOrCreateDefaultContext(language);
     }
 
@@ -46,24 +55,29 @@ export class CodeInterpreter {
     const execution = new Execution(code, context);
 
     // Stream execution
-    await this.jupyterClient.runCodeStream(context.id, code, options.language, {
-      onStdout: (output) => {
-        execution.logs.stdout.push(output.text);
-        if (options.onStdout) return options.onStdout(output);
-      },
-      onStderr: (output) => {
-        execution.logs.stderr.push(output.text);
-        if (options.onStderr) return options.onStderr(output);
-      },
-      onResult: async (result) => {
-        execution.results.push(new ResultImpl(result) as any);
-        if (options.onResult) return options.onResult(result);
-      },
-      onError: (error) => {
-        execution.error = error;
-        if (options.onError) return options.onError(error);
-      },
-    });
+    await this.interpreterClient.runCodeStream(
+      context.id,
+      code,
+      options.language,
+      {
+        onStdout: (output: OutputMessage) => {
+          execution.logs.stdout.push(output.text);
+          if (options.onStdout) return options.onStdout(output);
+        },
+        onStderr: (output: OutputMessage) => {
+          execution.logs.stderr.push(output.text);
+          if (options.onStderr) return options.onStderr(output);
+        },
+        onResult: async (result: Result) => {
+          execution.results.push(new ResultImpl(result) as any);
+          if (options.onResult) return options.onResult(result);
+        },
+        onError: (error: ExecutionError) => {
+          execution.error = error;
+          if (options.onError) return options.onError(error);
+        }
+      }
+    );
 
     return execution;
   }
@@ -78,35 +92,39 @@ export class CodeInterpreter {
     // Get or create context
     let context = options.context;
     if (!context) {
-      const language = options.language || "python";
+      const language = options.language || 'python';
       context = await this.getOrCreateDefaultContext(language);
     }
 
     // Create streaming response
-    const response = await this.jupyterClient.doFetch("/api/execute/code", {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Accept: "text/event-stream",
-      },
-      body: JSON.stringify({
-        context_id: context.id,
-        code,
-        language: options.language,
-      }),
-    });
+    // Note: doFetch is protected but we need direct access for raw stream response
+    const response = await (this.interpreterClient as any).doFetch(
+      '/api/execute/code',
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'text/event-stream'
+        },
+        body: JSON.stringify({
+          context_id: context.id,
+          code,
+          language: options.language
+        })
+      }
+    );
 
     if (!response.ok) {
       const errorData = (await response
         .json()
-        .catch(() => ({ error: "Unknown error" }))) as { error?: string };
+        .catch(() => ({ error: 'Unknown error' }))) as { error?: string };
       throw new Error(
         errorData.error || `Failed to execute code: ${response.status}`
       );
     }
 
     if (!response.body) {
-      throw new Error("No response body for streaming execution");
+      throw new Error('No response body for streaming execution');
     }
 
     return response.body;
@@ -116,7 +134,7 @@ export class CodeInterpreter {
    * List all code contexts
    */
   async listCodeContexts(): Promise<CodeContext[]> {
-    const contexts = await this.jupyterClient.listCodeContexts();
+    const contexts = await this.interpreterClient.listCodeContexts();
 
     // Update local cache
     for (const context of contexts) {
@@ -130,12 +148,12 @@ export class CodeInterpreter {
    * Delete a code context
    */
   async deleteCodeContext(contextId: string): Promise<void> {
-    await this.jupyterClient.deleteCodeContext(contextId);
+    await this.interpreterClient.deleteCodeContext(contextId);
     this.contexts.delete(contextId);
   }
 
   private async getOrCreateDefaultContext(
-    language: "python" | "javascript" | "typescript"
+    language: 'python' | 'javascript' | 'typescript'
   ): Promise<CodeContext> {
     // Check if we have a cached context for this language
     for (const context of this.contexts.values()) {