@cloudflare/sandbox 0.0.0-ee8c772 → 0.0.0-eec5bb6

package/src/interpreter-types.ts

@@ -0,0 +1,390 @@
+// Context Management
+export interface CreateContextOptions {
+  /**
+   * Programming language for the context
+   * @default 'python'
+   */
+  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
+   */
+  timeout?: number;
+}
+
+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
+   */
+  readonly lastUsed: Date;
+}
+
+// Execution Options
+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";
+
+  /**
+   * 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
+   */
+  onError?: (error: ExecutionError) => void | Promise<void>;
+}
+
+// Output Messages
+export interface OutputMessage {
+  /**
+   * The output text
+   */
+  text: string;
+
+  /**
+   * Timestamp of the output
+   */
+  timestamp: number;
+}
+
+// Execution Results
+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
+   */
+  formats(): string[];
+}
+
+// Chart Data
+export interface ChartData {
+  /**
+   * Type of chart
+   */
+  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";
+
+  /**
+   * Base64 encoded image if available
+   */
+  image?: string;
+}
+
+// Execution Error
+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
+   */
+  lineNumber?: number;
+}
+
+// Serializable execution result
+export interface ExecutionResult {
+  code: string;
+  logs: {
+    stdout: string[];
+    stderr: string[];
+  };
+  error?: ExecutionError;
+  executionCount?: number;
+  results: Array<{
+    text?: string;
+    html?: string;
+    png?: string;
+    jpeg?: string;
+    svg?: string;
+    latex?: string;
+    markdown?: string;
+    javascript?: string;
+    json?: any;
+    chart?: ChartData;
+    data?: any;
+  }>;
+}
+
+// Execution Result Container
+export class Execution {
+  /**
+   * All results from the execution
+   */
+  public results: Result[] = [];
+
+  /**
+   * Accumulated stdout and stderr
+   */
+  public logs = {
+    stdout: [] as string[],
+    stderr: [] as string[],
+  };
+
+  /**
+   * Execution error if any
+   */
+  public error?: ExecutionError;
+
+  /**
+   * Execution count (for interpreter)
+   */
+  public executionCount?: number;
+
+  constructor(
+    public readonly code: string,
+    public readonly context: CodeContext
+  ) {}
+
+  /**
+   * Convert to a plain object for serialization
+   */
+  toJSON(): ExecutionResult {
+    return {
+      code: this.code,
+      logs: this.logs,
+      error: this.error,
+      executionCount: this.executionCount,
+      results: this.results.map((result) => ({
+        text: result.text,
+        html: result.html,
+        png: result.png,
+        jpeg: result.jpeg,
+        svg: result.svg,
+        latex: result.latex,
+        markdown: result.markdown,
+        javascript: result.javascript,
+        json: result.json,
+        chart: result.chart,
+        data: result.data,
+      })),
+    };
+  }
+}
+
+// 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 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 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 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 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 chart(): ChartData | undefined {
+    return this.raw.chart;
+  }
+
+  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");
+    return formats;
+  }
+}

package/src/interpreter.ts

@@ -0,0 +1,150 @@
+import type { InterpreterClient } from "./interpreter-client.js";
+import {
+  type CodeContext,
+  type CreateContextOptions,
+  Execution,
+  ResultImpl,
+  type RunCodeOptions,
+} from "./interpreter-types.js";
+import type { Sandbox } from "./sandbox.js";
+
+export class CodeInterpreter {
+  private interpreterClient: InterpreterClient;
+  private contexts = new Map<string, CodeContext>();
+
+  constructor(sandbox: Sandbox) {
+    this.interpreterClient = sandbox.client as InterpreterClient;
+  }
+
+  /**
+   * Create a new code execution context
+   */
+  async createCodeContext(
+    options: CreateContextOptions = {}
+  ): Promise<CodeContext> {
+    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) => {
+        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);
+      },
+    });
+
+    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
+    const response = await this.interpreterClient.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,144 @@
+import { getSandbox, type Sandbox } from "./sandbox";
+import {
+  logSecurityEvent,
+  sanitizeSandboxId,
+  validatePort
+} from "./security";
+
+export interface SandboxEnv {
+  Sandbox: DurableObjectNamespace<Sandbox>;
+}
+
+export interface RouteInfo {
+  port: number;
+  sandboxId: string;
+  path: string;
+}
+
+export async function proxyToSandbox<E extends SandboxEnv>(
+  request: Request,
+  env: E
+): Promise<Response | null> {
+  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 } = routeInfo;
+    const sandbox = getSandbox(env.Sandbox, sandboxId);
+
+    // 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,
+    });
+
+    return sandbox.containerFetch(proxyRequest, port);
+  } catch (error) {
+    console.error('[Sandbox] Proxy routing error:', error);
+    return new Response('Proxy routing error', { status: 500 });
+  }
+}
+
+function extractSandboxRoute(url: URL): RouteInfo | null {
+  // Parse subdomain pattern: port-sandboxId.domain
+  const subdomainMatch = url.hostname.match(/^(\d{4,5})-([^.-][^.]*[^.-]|[^.-])\.(.+)$/);
+
+  if (!subdomainMatch) {
+    // Log malformed subdomain attempts
+    if (url.hostname.includes('-') && url.hostname.includes('.')) {
+      logSecurityEvent('MALFORMED_SUBDOMAIN_ATTEMPT', {
+        hostname: url.hostname,
+        url: url.toString()
+      }, 'medium');
+    }
+    return null;
+  }
+
+  const portStr = subdomainMatch[1];
+  const sandboxId = subdomainMatch[2];
+  const domain = subdomainMatch[3];
+
+  const port = parseInt(portStr, 10);
+  if (!validatePort(port)) {
+    logSecurityEvent('INVALID_PORT_IN_SUBDOMAIN', {
+      port,
+      portStr,
+      sandboxId,
+      hostname: url.hostname,
+      url: url.toString()
+    }, 'high');
+    return null;
+  }
+
+  let sanitizedSandboxId: string;
+  try {
+    sanitizedSandboxId = sanitizeSandboxId(sandboxId);
+  } catch (error) {
+    logSecurityEvent('INVALID_SANDBOX_ID_IN_SUBDOMAIN', {
+      sandboxId,
+      port,
+      hostname: url.hostname,
+      url: url.toString(),
+      error: error instanceof Error ? error.message : 'Unknown error'
+    }, 'high');
+    return null;
+  }
+
+  // DNS subdomain length limit is 63 characters
+  if (sandboxId.length > 63) {
+    logSecurityEvent('SANDBOX_ID_LENGTH_VIOLATION', {
+      sandboxId,
+      length: sandboxId.length,
+      port,
+      hostname: url.hostname
+    }, 'medium');
+    return null;
+  }
+
+  logSecurityEvent('SANDBOX_ROUTE_EXTRACTED', {
+    port,
+    sandboxId: sanitizedSandboxId,
+    domain,
+    path: url.pathname || "/",
+    hostname: url.hostname
+  }, 'low');
+
+  return {
+    port,
+    sandboxId: sanitizedSandboxId,
+    path: url.pathname || "/",
+  };
+}
+
+export function isLocalhostPattern(hostname: string): boolean {
+  const hostPart = hostname.split(":")[0];
+  return (
+    hostPart === "localhost" ||
+    hostPart === "127.0.0.1" ||
+    hostPart === "::1" ||
+    hostPart === "[::1]" ||
+    hostPart === "0.0.0.0"
+  );
+}