@cloudflare/sandbox 0.0.0-02ee8fe

package/src/file-stream.ts

@@ -0,0 +1,164 @@
+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

@@ -0,0 +1,93 @@
+// Export the main Sandbox class and utilities
+
+
+// Export the new client architecture
+export {
+  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 {
+  BaseExecOptions,
+  ExecEvent,
+  ExecOptions,
+  ExecResult,FileChunk, FileMetadata, FileStreamEvent, 
+  ISandbox,
+  LogEvent,
+  Process,
+  ProcessOptions,
+  ProcessStatus,
+  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

@@ -0,0 +1,159 @@
+import {
+  type CodeContext,
+  type CreateContextOptions,
+  Execution,
+  type ExecutionError,
+  type OutputMessage,
+  type Result,
+  ResultImpl,
+  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 interpreterClient: InterpreterClient;
+  private contexts = new Map<string, CodeContext>();
+
+  constructor(sandbox: Sandbox) {
+    // In init-testing architecture, client is a SandboxClient with an interpreter property
+    this.interpreterClient = (sandbox.client as any).interpreter as InterpreterClient;
+  }
+
+  /**
+   * Create a new code execution context
+   */
+  async createCodeContext(
+    options: CreateContextOptions = {}
+  ): Promise<CodeContext> {
+    // Validate language before sending to container
+    validateLanguage(options.language);
+
+    const context = await this.interpreterClient.createCodeContext(options);
+    this.contexts.set(context.id, context);
+    return context;
+  }
+
+  /**
+   * Run code with optional context
+   */
+  async runCode(
+    code: string,
+    options: RunCodeOptions = {}
+  ): Promise<Execution> {
+    // Get or create context
+    let context = options.context;
+    if (!context) {
+      // Try to find or create a default context for the language
+      const language = options.language || "python";
+      context = await this.getOrCreateDefaultContext(language);
+    }
+
+    // Create execution object to collect results
+    const execution = new Execution(code, context);
+
+    // Stream execution
+    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;
+  }
+
+  /**
+   * Run code and return a streaming response
+   */
+  async runCodeStream(
+    code: string,
+    options: RunCodeOptions = {}
+  ): Promise<ReadableStream> {
+    // Get or create context
+    let context = options.context;
+    if (!context) {
+      const language = options.language || "python";
+      context = await this.getOrCreateDefaultContext(language);
+    }
+
+    // Create streaming response
+    // 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 };
+      throw new Error(
+        errorData.error || `Failed to execute code: ${response.status}`
+      );
+    }
+
+    if (!response.body) {
+      throw new Error("No response body for streaming execution");
+    }
+
+    return response.body;
+  }
+
+  /**
+   * List all code contexts
+   */
+  async listCodeContexts(): Promise<CodeContext[]> {
+    const contexts = await this.interpreterClient.listCodeContexts();
+
+    // Update local cache
+    for (const context of contexts) {
+      this.contexts.set(context.id, context);
+    }
+
+    return contexts;
+  }
+
+  /**
+   * Delete a code context
+   */
+  async deleteCodeContext(contextId: string): Promise<void> {
+    await this.interpreterClient.deleteCodeContext(contextId);
+    this.contexts.delete(contextId);
+  }
+
+  private async getOrCreateDefaultContext(
+    language: "python" | "javascript" | "typescript"
+  ): Promise<CodeContext> {
+    // Check if we have a cached context for this language
+    for (const context of this.contexts.values()) {
+      if (context.language === language) {
+        return context;
+      }
+    }
+
+    // Create new default context
+    return this.createCodeContext({ language });
+  }
+}

package/src/request-handler.ts

@@ -0,0 +1,180 @@
+import { switchPort } from "@cloudflare/containers";
+import { createLogger, type LogContext, TraceContext } from "@repo/shared";
+import { getSandbox, type Sandbox } from "./sandbox";
+import {
+  sanitizeSandboxId,
+  validatePort
+} from "./security";
+
+export interface SandboxEnv {
+  Sandbox: DurableObjectNamespace<Sandbox>;
+}
+
+export interface RouteInfo {
+  port: number;
+  sandboxId: string;
+  path: string;
+  token: string;
+}
+
+export async function proxyToSandbox<E extends SandboxEnv>(
+  request: Request,
+  env: E
+): Promise<Response | null> {
+  // Create logger context for this request
+  const traceId = TraceContext.fromHeaders(request.headers) || TraceContext.generate();
+  const logger = createLogger({
+    component: 'sandbox-do',
+    traceId,
+    operation: 'proxy'
+  });
+
+  try {
+    const url = new URL(request.url);
+    const routeInfo = extractSandboxRoute(url);
+
+    if (!routeInfo) {
+      return null; // Not a request to an exposed container port
+    }
+
+    const { sandboxId, port, path, token } = routeInfo;
+    const sandbox = getSandbox(env.Sandbox, sandboxId);
+
+    // Critical security check: Validate token (mandatory for all user ports)
+    // Skip check for control plane port 3000
+    if (port !== 3000) {
+      // Validate the token matches the port
+      const isValidToken = await sandbox.validatePortToken(port, token);
+      if (!isValidToken) {
+        logger.warn('Invalid token access blocked', {
+          port,
+          sandboxId,
+          path,
+          hostname: url.hostname,
+          url: request.url,
+          method: request.method,
+          userAgent: request.headers.get('User-Agent') || 'unknown'
+        });
+
+        return new Response(
+          JSON.stringify({
+            error: `Access denied: Invalid token or port not exposed`,
+            code: 'INVALID_TOKEN'
+          }),
+          {
+            status: 404,
+            headers: {
+              'Content-Type': 'application/json'
+            }
+          }
+        );
+      }
+    }
+
+    // Detect WebSocket upgrade request
+    const upgradeHeader = request.headers.get('Upgrade');
+    if (upgradeHeader?.toLowerCase() === 'websocket') {
+      // WebSocket path: Must use fetch() not containerFetch()
+      // This bypasses JSRPC serialization boundary which cannot handle WebSocket upgrades
+      return await sandbox.fetch(switchPort(request, port));
+    }
+
+    // Build proxy request with proper headers
+    let proxyUrl: string;
+
+    // Route based on the target port
+    if (port !== 3000) {
+      // Route directly to user's service on the specified port
+      proxyUrl = `http://localhost:${port}${path}${url.search}`;
+    } else {
+      // Port 3000 is our control plane - route normally
+      proxyUrl = `http://localhost:3000${path}${url.search}`;
+    }
+
+    const proxyRequest = new Request(proxyUrl, {
+      method: request.method,
+      headers: {
+        ...Object.fromEntries(request.headers),
+        'X-Original-URL': request.url,
+        'X-Forwarded-Host': url.hostname,
+        'X-Forwarded-Proto': url.protocol.replace(':', ''),
+        'X-Sandbox-Name': sandboxId, // Pass the friendly name
+      },
+      body: request.body,
+      // @ts-expect-error - duplex required for body streaming in modern runtimes
+      duplex: 'half',
+    });
+
+    return await sandbox.containerFetch(proxyRequest, port);
+  } catch (error) {
+    logger.error('Proxy routing error', error instanceof Error ? error : new Error(String(error)));
+    return new Response('Proxy routing error', { status: 500 });
+  }
+}
+
+function extractSandboxRoute(url: URL): RouteInfo | null {
+  // Parse subdomain pattern: port-sandboxId-token.domain (tokens mandatory)
+  // Token is always exactly 16 chars (generated by generatePortToken)
+  const subdomainMatch = url.hostname.match(/^(\d{4,5})-([^.-][^.]*?[^.-]|[^.-])-([a-z0-9_-]{16})\.(.+)$/);
+
+  if (!subdomainMatch) {
+    return null;
+  }
+
+  const portStr = subdomainMatch[1];
+  const sandboxId = subdomainMatch[2];
+  const token = subdomainMatch[3]; // Mandatory token
+  const domain = subdomainMatch[4];
+
+  const port = parseInt(portStr, 10);
+  if (!validatePort(port)) {
+    return null;
+  }
+
+  let sanitizedSandboxId: string;
+  try {
+    sanitizedSandboxId = sanitizeSandboxId(sandboxId);
+  } catch (error) {
+    return null;
+  }
+
+  // DNS subdomain length limit is 63 characters
+  if (sandboxId.length > 63) {
+    return null;
+  }
+
+  return {
+    port,
+    sandboxId: sanitizedSandboxId,
+    path: url.pathname || "/",
+    token,
+  };
+}
+
+export function isLocalhostPattern(hostname: string): boolean {
+  // Handle IPv6 addresses in brackets (with or without port)
+  if (hostname.startsWith('[')) {
+    if (hostname.includes(']:')) {
+      // [::1]:port format
+      const ipv6Part = hostname.substring(0, hostname.indexOf(']:') + 1);
+      return ipv6Part === '[::1]';
+    } else {
+      // [::1] format without port
+      return hostname === '[::1]';
+    }
+  }
+  
+  // Handle bare IPv6 without brackets
+  if (hostname === '::1') {
+    return true;
+  }
+  
+  // For IPv4 and regular hostnames, split on colon to remove port
+  const hostPart = hostname.split(":")[0];
+  
+  return (
+    hostPart === "localhost" ||
+    hostPart === "127.0.0.1" ||
+    hostPart === "0.0.0.0"
+  );
+}