@cloudflare/sandbox 0.0.0-44e584c → 0.0.0-485cf61

package/src/clients/interpreter-client.ts

@@ -0,0 +1,332 @@
+import {
+  type CodeContext,
+  type ContextCreateResult,
+  type ContextListResult,
+  type CreateContextOptions,
+  type ExecutionError,
+  type OutputMessage,
+  type Result,
+  ResultImpl,
+} from '@repo/shared';
+import type { ErrorResponse } from '../errors';
+import { createErrorFromResponse, ErrorCode, InterpreterNotReadyError } from '../errors';
+import { BaseHttpClient } from './base-client.js';
+import type { HttpClientOptions } from './types.js';
+
+// Streaming execution data from the server
+interface StreamingExecutionData {
+  type: "result" | "stdout" | "stderr" | "error" | "execution_complete";
+  text?: string;
+  html?: string;
+  png?: string; // base64
+  jpeg?: string; // base64
+  svg?: string;
+  latex?: string;
+  markdown?: string;
+  javascript?: string;
+  json?: unknown;
+  chart?: {
+    type:
+      | "line"
+      | "bar"
+      | "scatter"
+      | "pie"
+      | "histogram"
+      | "heatmap"
+      | "unknown";
+    data: unknown;
+    options?: unknown;
+  };
+  data?: unknown;
+  metadata?: Record<string, unknown>;
+  execution_count?: number;
+  ename?: string;
+  evalue?: string;
+  traceback?: string[];
+  lineNumber?: number;
+  timestamp?: number;
+}
+
+export interface ExecutionCallbacks {
+  onStdout?: (output: OutputMessage) => void | Promise<void>;
+  onStderr?: (output: OutputMessage) => void | Promise<void>;
+  onResult?: (result: Result) => void | Promise<void>;
+  onError?: (error: ExecutionError) => void | Promise<void>;
+}
+
+export class InterpreterClient extends BaseHttpClient {
+  private readonly maxRetries = 3;
+  private readonly retryDelayMs = 1000;
+
+  constructor(options: HttpClientOptions = {}) {
+    super(options);
+  }
+
+  async createCodeContext(
+    options: CreateContextOptions = {}
+  ): Promise<CodeContext> {
+    return this.executeWithRetry(async () => {
+      const response = await this.doFetch("/api/contexts", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          language: options.language || "python",
+          cwd: options.cwd || "/workspace",
+          env_vars: options.envVars,
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await this.parseErrorResponse(response);
+        throw error;
+      }
+
+      const data = (await response.json()) as ContextCreateResult;
+      if (!data.success) {
+        throw new Error(`Failed to create context: ${JSON.stringify(data)}`);
+      }
+
+      return {
+        id: data.contextId,
+        language: data.language,
+        cwd: data.cwd || '/workspace',
+        createdAt: new Date(data.timestamp),
+        lastUsed: new Date(data.timestamp),
+      };
+    });
+  }
+
+  async runCodeStream(
+    contextId: string | undefined,
+    code: string,
+    language: string | undefined,
+    callbacks: ExecutionCallbacks,
+    timeoutMs?: number
+  ): Promise<void> {
+    return this.executeWithRetry(async () => {
+      const response = await this.doFetch("/api/execute/code", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "text/event-stream",
+        },
+        body: JSON.stringify({
+          context_id: contextId,
+          code,
+          language,
+          ...(timeoutMs !== undefined && { timeout_ms: timeoutMs })
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await this.parseErrorResponse(response);
+        throw error;
+      }
+
+      if (!response.body) {
+        throw new Error("No response body for streaming execution");
+      }
+
+      // Process streaming response
+      for await (const chunk of this.readLines(response.body)) {
+        await this.parseExecutionResult(chunk, callbacks);
+      }
+    });
+  }
+
+  async listCodeContexts(): Promise<CodeContext[]> {
+    return this.executeWithRetry(async () => {
+      const response = await this.doFetch("/api/contexts", {
+        method: "GET",
+        headers: { "Content-Type": "application/json" },
+      });
+
+      if (!response.ok) {
+        const error = await this.parseErrorResponse(response);
+        throw error;
+      }
+
+      const data = (await response.json()) as ContextListResult;
+      if (!data.success) {
+        throw new Error(`Failed to list contexts: ${JSON.stringify(data)}`);
+      }
+
+      return data.contexts.map((ctx) => ({
+        id: ctx.id,
+        language: ctx.language,
+        cwd: ctx.cwd || '/workspace',
+        createdAt: new Date(data.timestamp),
+        lastUsed: new Date(data.timestamp),
+      }));
+    });
+  }
+
+  async deleteCodeContext(contextId: string): Promise<void> {
+    return this.executeWithRetry(async () => {
+      const response = await this.doFetch(`/api/contexts/${contextId}`, {
+        method: "DELETE",
+        headers: { "Content-Type": "application/json" },
+      });
+
+      if (!response.ok) {
+        const error = await this.parseErrorResponse(response);
+        throw error;
+      }
+    });
+  }
+
+  /**
+   * Execute an operation with automatic retry for transient errors
+   */
+  private async executeWithRetry<T>(operation: () => Promise<T>): Promise<T> {
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        return await operation();
+      } catch (error) {
+        lastError = error as Error;
+
+        // Check if it's a retryable error (interpreter not ready)
+        if (this.isRetryableError(error)) {
+          // Don't retry on the last attempt
+          if (attempt < this.maxRetries - 1) {
+            // Exponential backoff with jitter
+            const delay =
+              this.retryDelayMs * 2 ** attempt + Math.random() * 1000;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            continue;
+          }
+        }
+
+        // Not retryable or last attempt - throw the error
+        throw error;
+      }
+    }
+
+    throw lastError || new Error("Execution failed after retries");
+  }
+
+  private isRetryableError(error: unknown): boolean {
+    if (error instanceof InterpreterNotReadyError) {
+      return true;
+    }
+
+    if (error instanceof Error) {
+      return (
+        error.message.includes("not ready") ||
+        error.message.includes("initializing")
+      );
+    }
+
+    return false;
+  }
+
+  private async parseErrorResponse(response: Response): Promise<Error> {
+    try {
+      const errorData = await response.json() as ErrorResponse;
+      return createErrorFromResponse(errorData);
+    } catch {
+      // Fallback if response isn't JSON
+      const errorResponse: ErrorResponse = {
+        code: ErrorCode.INTERNAL_ERROR,
+        message: `HTTP ${response.status}: ${response.statusText}`,
+        context: {},
+        httpStatus: response.status,
+        timestamp: new Date().toISOString()
+      };
+      return createErrorFromResponse(errorResponse);
+    }
+  }
+
+  private async *readLines(
+    stream: ReadableStream<Uint8Array>
+  ): AsyncGenerator<string> {
+    const reader = stream.getReader();
+    let buffer = "";
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (value) {
+          buffer += new TextDecoder().decode(value);
+        }
+        if (done) break;
+
+        let newlineIdx = buffer.indexOf("\n");
+        while (newlineIdx !== -1) {
+          yield buffer.slice(0, newlineIdx);
+          buffer = buffer.slice(newlineIdx + 1);
+          newlineIdx = buffer.indexOf("\n");
+        }
+      }
+
+      // Yield any remaining data
+      if (buffer.length > 0) {
+        yield buffer;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  private async parseExecutionResult(
+    line: string,
+    callbacks: ExecutionCallbacks
+  ) {
+    if (!line.trim()) return;
+
+    // Skip lines that don't start with "data: " (SSE format)
+    if (!line.startsWith('data: ')) return;
+
+    try {
+      // Strip "data: " prefix and parse JSON
+      const jsonData = line.substring(6); // "data: " is 6 characters
+      const data = JSON.parse(jsonData) as StreamingExecutionData;
+
+      switch (data.type) {
+        case "stdout":
+          if (callbacks.onStdout && data.text) {
+            await callbacks.onStdout({
+              text: data.text,
+              timestamp: data.timestamp || Date.now(),
+            });
+          }
+          break;
+
+        case "stderr":
+          if (callbacks.onStderr && data.text) {
+            await callbacks.onStderr({
+              text: data.text,
+              timestamp: data.timestamp || Date.now(),
+            });
+          }
+          break;
+
+        case "result":
+          if (callbacks.onResult) {
+            // Create a ResultImpl instance from the raw data
+            const result = new ResultImpl(data);
+            await callbacks.onResult(result);
+          }
+          break;
+
+        case "error":
+          if (callbacks.onError) {
+            await callbacks.onError({
+              name: data.ename || "Error",
+              message: data.evalue || "Unknown error",
+              traceback: data.traceback || [],
+            });
+          }
+          break;
+
+        case "execution_complete":
+          // Signal completion - callbacks can handle cleanup if needed
+          break;
+      }
+    } catch (error) {
+      console.error("Failed to parse execution result:", error);
+    }
+  }
+}

package/src/clients/port-client.ts

@@ -0,0 +1,108 @@
+import type {
+  PortCloseResult,
+  PortExposeResult,
+  PortListResult,
+} from '@repo/shared';
+import { BaseHttpClient } from './base-client';
+import type { HttpClientOptions } from './types';
+
+// Re-export for convenience
+export type {
+  PortExposeResult,
+  PortCloseResult,
+  PortListResult,
+};
+
+/**
+ * Request interface for exposing ports
+ */
+export interface ExposePortRequest {
+  port: number;
+  name?: string;
+}
+
+/**
+ * Request interface for unexposing ports
+ */
+export interface UnexposePortRequest {
+  port: number;
+}
+
+/**
+ * Client for port management and preview URL operations
+ */
+export class PortClient extends BaseHttpClient {
+  constructor(options: HttpClientOptions = {}) {
+    super(options);
+  }
+
+  /**
+   * Expose a port and get a preview URL
+   * @param port - Port number to expose
+   * @param sessionId - The session ID for this operation
+   * @param name - Optional name for the port
+   */
+  async exposePort(
+    port: number,
+    sessionId: string,
+    name?: string
+  ): Promise<PortExposeResult> {
+    try {
+      const data = { port, sessionId, name };
+
+      const response = await this.post<PortExposeResult>(
+        '/api/expose-port',
+        data
+      );
+
+      this.logSuccess(
+        'Port exposed',
+        `${port} exposed at ${response.url}${name ? ` (${name})` : ''}`
+      );
+
+      return response;
+    } catch (error) {
+      this.logError('exposePort', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Unexpose a port and remove its preview URL
+   * @param port - Port number to unexpose
+   * @param sessionId - The session ID for this operation
+   */
+  async unexposePort(port: number, sessionId: string): Promise<PortCloseResult> {
+    try {
+      const url = `/api/exposed-ports/${port}?session=${encodeURIComponent(sessionId)}`;
+      const response = await this.delete<PortCloseResult>(url);
+
+      this.logSuccess('Port unexposed', `${port}`);
+      return response;
+    } catch (error) {
+      this.logError('unexposePort', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get all currently exposed ports
+   * @param sessionId - The session ID for this operation
+   */
+  async getExposedPorts(sessionId: string): Promise<PortListResult> {
+    try {
+      const url = `/api/exposed-ports?session=${encodeURIComponent(sessionId)}`;
+      const response = await this.get<PortListResult>(url);
+
+      this.logSuccess(
+        'Exposed ports retrieved',
+        `${response.ports.length} ports exposed`
+      );
+
+      return response;
+    } catch (error) {
+      this.logError('getExposedPorts', error);
+      throw error;
+    }
+  }
+}

package/src/clients/process-client.ts

@@ -0,0 +1,180 @@
+import type {
+  ProcessCleanupResult,
+  ProcessInfoResult,
+  ProcessKillResult,
+  ProcessListResult,
+  ProcessLogsResult,
+  ProcessStartResult,
+  StartProcessRequest,
+} from '@repo/shared';
+import { BaseHttpClient } from './base-client';
+import type { HttpClientOptions } from './types';
+
+// Re-export for convenience
+export type {
+  StartProcessRequest,
+  ProcessStartResult,
+  ProcessListResult,
+  ProcessInfoResult,
+  ProcessKillResult,
+  ProcessLogsResult,
+  ProcessCleanupResult,
+};
+
+
+/**
+ * Client for background process management
+ */
+export class ProcessClient extends BaseHttpClient {
+  constructor(options: HttpClientOptions = {}) {
+    super(options);
+  }
+
+  /**
+   * Start a background process
+   * @param command - Command to execute as a background process
+   * @param sessionId - The session ID for this operation
+   * @param options - Optional settings (processId)
+   */
+  async startProcess(
+    command: string,
+    sessionId: string,
+    options?: { processId?: string }
+  ): Promise<ProcessStartResult> {
+    try {
+      const data: StartProcessRequest = {
+        command,
+        sessionId,
+        processId: options?.processId,
+      };
+
+      const response = await this.post<ProcessStartResult>(
+        '/api/process/start',
+        data
+      );
+
+      this.logSuccess(
+        'Process started',
+        `${command} (ID: ${response.processId})`
+      );
+
+      return response;
+    } catch (error) {
+      this.logError('startProcess', error);
+      throw error;
+    }
+  }
+
+  /**
+   * List all processes (sandbox-scoped, not session-scoped)
+   */
+  async listProcesses(): Promise<ProcessListResult> {
+    try {
+      const url = `/api/process/list`;
+      const response = await this.get<ProcessListResult>(url);
+
+      this.logSuccess('Processes listed', `${response.processes.length} processes`);
+      return response;
+    } catch (error) {
+      this.logError('listProcesses', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get information about a specific process (sandbox-scoped, not session-scoped)
+   * @param processId - ID of the process to retrieve
+   */
+  async getProcess(processId: string): Promise<ProcessInfoResult> {
+    try {
+      const url = `/api/process/${processId}`;
+      const response = await this.get<ProcessInfoResult>(url);
+
+      this.logSuccess('Process retrieved', `ID: ${processId}`);
+      return response;
+    } catch (error) {
+      this.logError('getProcess', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Kill a specific process (sandbox-scoped, not session-scoped)
+   * @param processId - ID of the process to kill
+   */
+  async killProcess(processId: string): Promise<ProcessKillResult> {
+    try {
+      const url = `/api/process/${processId}`;
+      const response = await this.delete<ProcessKillResult>(url);
+
+      this.logSuccess('Process killed', `ID: ${processId}`);
+      return response;
+    } catch (error) {
+      this.logError('killProcess', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Kill all running processes (sandbox-scoped, not session-scoped)
+   */
+  async killAllProcesses(): Promise<ProcessCleanupResult> {
+    try {
+      const url = `/api/process/kill-all`;
+      const response = await this.delete<ProcessCleanupResult>(url);
+
+      this.logSuccess(
+        'All processes killed',
+        `${response.cleanedCount} processes terminated`
+      );
+
+      return response;
+    } catch (error) {
+      this.logError('killAllProcesses', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get logs from a specific process (sandbox-scoped, not session-scoped)
+   * @param processId - ID of the process to get logs from
+   */
+  async getProcessLogs(processId: string): Promise<ProcessLogsResult> {
+    try {
+      const url = `/api/process/${processId}/logs`;
+      const response = await this.get<ProcessLogsResult>(url);
+
+      this.logSuccess(
+        'Process logs retrieved',
+        `ID: ${processId}, stdout: ${response.stdout.length} chars, stderr: ${response.stderr.length} chars`
+      );
+
+      return response;
+    } catch (error) {
+      this.logError('getProcessLogs', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Stream logs from a specific process (sandbox-scoped, not session-scoped)
+   * @param processId - ID of the process to stream logs from
+   */
+  async streamProcessLogs(processId: string): Promise<ReadableStream<Uint8Array>> {
+    try {
+      const url = `/api/process/${processId}/stream`;
+      const response = await this.doFetch(url, {
+        method: 'GET',
+      });
+
+      const stream = await this.handleStreamResponse(response);
+
+      this.logSuccess('Process log stream started', `ID: ${processId}`);
+
+      return stream;
+    } catch (error) {
+      this.logError('streamProcessLogs', error);
+      throw error;
+    }
+  }
+}

package/src/clients/sandbox-client.ts

@@ -0,0 +1,41 @@
+import { CommandClient } from './command-client';
+import { FileClient } from './file-client';
+import { GitClient } from './git-client';
+import { InterpreterClient } from './interpreter-client';
+import { PortClient } from './port-client';
+import { ProcessClient } from './process-client';
+import type { HttpClientOptions } from './types';
+import { UtilityClient } from './utility-client';
+
+/**
+ * Main sandbox client that composes all domain-specific clients
+ * Provides organized access to all sandbox functionality
+ */
+export class SandboxClient {
+  public readonly commands: CommandClient;
+  public readonly files: FileClient;
+  public readonly processes: ProcessClient;
+  public readonly ports: PortClient;
+  public readonly git: GitClient;
+  public readonly interpreter: InterpreterClient;
+  public readonly utils: UtilityClient;
+
+  constructor(options: HttpClientOptions = {}) {
+    // Ensure baseUrl is provided for all clients
+    const clientOptions = {
+      baseUrl: 'http://localhost:3000',
+      ...options,
+    };
+
+    // Initialize all domain clients with shared options
+    this.commands = new CommandClient(clientOptions);
+    this.files = new FileClient(clientOptions);
+    this.processes = new ProcessClient(clientOptions);
+    this.ports = new PortClient(clientOptions);
+    this.git = new GitClient(clientOptions);
+    this.interpreter = new InterpreterClient(clientOptions);
+    this.utils = new UtilityClient(clientOptions);
+  }
+
+
+}