@cloudflare/sandbox 0.0.0-feafd32 → 0.0.0-ff2fa91

package/src/clients/git-client.ts

@@ -0,0 +1,91 @@
+import type { GitCheckoutResult } from '@repo/shared';
+import { BaseHttpClient } from './base-client';
+import type { HttpClientOptions, SessionRequest } from './types';
+
+// Re-export for convenience
+export type { GitCheckoutResult };
+
+/**
+ * Request interface for Git checkout operations
+ */
+export interface GitCheckoutRequest extends SessionRequest {
+  repoUrl: string;
+  branch?: string;
+  targetDir?: string;
+}
+
+/**
+ * Client for Git repository operations
+ */
+export class GitClient extends BaseHttpClient {
+  /**
+   * Clone a Git repository
+   * @param repoUrl - URL of the Git repository to clone
+   * @param sessionId - The session ID for this operation
+   * @param options - Optional settings (branch, targetDir)
+   */
+  async checkout(
+    repoUrl: string,
+    sessionId: string,
+    options?: {
+      branch?: string;
+      targetDir?: string;
+    }
+  ): Promise<GitCheckoutResult> {
+    try {
+      // Determine target directory - use provided path or generate from repo name
+      let targetDir = options?.targetDir;
+      if (!targetDir) {
+        const repoName = this.extractRepoName(repoUrl);
+        // Ensure absolute path in /workspace
+        targetDir = `/workspace/${repoName}`;
+      }
+
+      const data: GitCheckoutRequest = {
+        repoUrl,
+        sessionId,
+        targetDir
+      };
+
+      // Only include branch if explicitly specified
+      // This allows Git to use the repository's default branch
+      if (options?.branch) {
+        data.branch = options.branch;
+      }
+
+      const response = await this.post<GitCheckoutResult>(
+        '/api/git/checkout',
+        data
+      );
+
+      this.logSuccess(
+        'Repository cloned',
+        `${repoUrl} (branch: ${response.branch}) -> ${response.targetDir}`
+      );
+
+      return response;
+    } catch (error) {
+      this.logError('checkout', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Extract repository name from URL for default directory name
+   */
+  private extractRepoName(repoUrl: string): string {
+    try {
+      const url = new URL(repoUrl);
+      const pathParts = url.pathname.split('/');
+      const repoName = pathParts[pathParts.length - 1];
+
+      // Remove .git extension if present
+      return repoName.replace(/\.git$/, '');
+    } catch {
+      // Fallback for invalid URLs
+      const parts = repoUrl.split('/');
+      const repoName = parts[parts.length - 1];
+      return repoName.replace(/\.git$/, '') || 'repo';
+    }
+  }
+}

package/src/clients/index.ts

@@ -0,0 +1,60 @@
+// Main client exports
+
+// Command client types
+export type { ExecuteRequest, ExecuteResponse } from './command-client';
+
+// Domain-specific clients
+export { CommandClient } from './command-client';
+// File client types
+export type {
+  FileOperationRequest,
+  MkdirRequest,
+  ReadFileRequest,
+  WriteFileRequest
+} from './file-client';
+export { FileClient } from './file-client';
+// Git client types
+export type { GitCheckoutRequest, GitCheckoutResult } from './git-client';
+export { GitClient } from './git-client';
+export {
+  type ExecutionCallbacks,
+  InterpreterClient
+} from './interpreter-client';
+// Port client types
+export type {
+  ExposePortRequest,
+  PortCloseResult,
+  PortExposeResult,
+  PortListResult,
+  UnexposePortRequest
+} from './port-client';
+export { PortClient } from './port-client';
+// Process client types
+export type {
+  ProcessCleanupResult,
+  ProcessInfoResult,
+  ProcessKillResult,
+  ProcessListResult,
+  ProcessLogsResult,
+  ProcessStartResult,
+  StartProcessRequest
+} from './process-client';
+export { ProcessClient } from './process-client';
+export { SandboxClient } from './sandbox-client';
+// Types and interfaces
+export type {
+  BaseApiResponse,
+  ContainerStub,
+  ErrorResponse,
+  HttpClientOptions,
+  RequestConfig,
+  ResponseHandler,
+  SessionRequest
+} from './types';
+// Utility client types
+export type {
+  CommandsResponse,
+  PingResponse,
+  VersionResponse
+} from './utility-client';
+export { UtilityClient } from './utility-client';

package/src/clients/interpreter-client.ts

@@ -0,0 +1,333 @@
+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;
+
+  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) {
+        this.logError('executeWithRetry', 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) {
+      this.logError('parseExecutionResult', error);
+    }
+  }
+}

package/src/clients/port-client.ts

@@ -0,0 +1,105 @@
+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 {
+  /**
+   * 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;
+    }
+  }
+}