@cloudflare/sandbox 0.0.0-eec5bb6 → 0.0.0-f06fee3

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 {
+  /**
+   * 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,39 @@
+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: HttpClientOptions = {
+      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);
+  }
+}

package/src/clients/types.ts

@@ -0,0 +1,88 @@
+import type { Logger } from '@repo/shared';
+
+/**
+ * Minimal interface for container fetch functionality
+ */
+export interface ContainerStub {
+  containerFetch(
+    url: string,
+    options: RequestInit,
+    port?: number
+  ): Promise<Response>;
+}
+
+/**
+ * Shared HTTP client configuration options
+ */
+export interface HttpClientOptions {
+  logger?: Logger;
+  baseUrl?: string;
+  port?: number;
+  stub?: ContainerStub;
+  onCommandComplete?: (
+    success: boolean,
+    exitCode: number,
+    stdout: string,
+    stderr: string,
+    command: string
+  ) => void;
+  onError?: (error: string, command?: string) => void;
+}
+
+/**
+ * Base response interface for all API responses
+ */
+export interface BaseApiResponse {
+  success: boolean;
+  timestamp: string;
+}
+
+/**
+ * Standard error response structure - matches BaseHandler.createErrorResponse()
+ */
+export interface ApiErrorResponse {
+  success: false;
+  error: string;
+  code: string;
+  details?: any;
+  timestamp: string;
+}
+
+/**
+ * Validation error response structure - matches ValidationMiddleware
+ */
+export interface ValidationErrorResponse {
+  error: string;
+  message: string;
+  details?: any[];
+  timestamp: string;
+}
+
+/**
+ * Legacy error response interface - deprecated, use ApiErrorResponse
+ */
+export interface ErrorResponse {
+  error: string;
+  details?: string;
+  code?: string;
+}
+
+/**
+ * HTTP request configuration
+ */
+export interface RequestConfig extends RequestInit {
+  endpoint: string;
+  data?: Record<string, any>;
+}
+
+/**
+ * Typed response handler
+ */
+export type ResponseHandler<T> = (response: Response) => Promise<T>;
+
+/**
+ * Common session-aware request interface
+ */
+export interface SessionRequest {
+  sessionId?: string;
+}

package/src/clients/utility-client.ts

@@ -0,0 +1,123 @@
+import { BaseHttpClient } from './base-client';
+import type { BaseApiResponse, HttpClientOptions } from './types';
+
+/**
+ * Response interface for ping operations
+ */
+export interface PingResponse extends BaseApiResponse {
+  message: string;
+  uptime?: number;
+}
+
+/**
+ * Response interface for getting available commands
+ */
+export interface CommandsResponse extends BaseApiResponse {
+  availableCommands: string[];
+  count: number;
+}
+
+/**
+ * Response interface for getting container version
+ */
+export interface VersionResponse extends BaseApiResponse {
+  version: string;
+}
+
+/**
+ * Request interface for creating sessions
+ */
+export interface CreateSessionRequest {
+  id: string;
+  env?: Record<string, string>;
+  cwd?: string;
+}
+
+/**
+ * Response interface for creating sessions
+ */
+export interface CreateSessionResponse extends BaseApiResponse {
+  id: string;
+  message: string;
+}
+
+/**
+ * Client for health checks and utility operations
+ */
+export class UtilityClient extends BaseHttpClient {
+  /**
+   * Ping the sandbox to check if it's responsive
+   */
+  async ping(): Promise<string> {
+    try {
+      const response = await this.get<PingResponse>('/api/ping');
+
+      this.logSuccess('Ping successful', response.message);
+      return response.message;
+    } catch (error) {
+      this.logError('ping', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get list of available commands in the sandbox environment
+   */
+  async getCommands(): Promise<string[]> {
+    try {
+      const response = await this.get<CommandsResponse>('/api/commands');
+
+      this.logSuccess(
+        'Commands retrieved',
+        `${response.count} commands available`
+      );
+
+      return response.availableCommands;
+    } catch (error) {
+      this.logError('getCommands', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Create a new execution session
+   * @param options - Session configuration (id, env, cwd)
+   */
+  async createSession(
+    options: CreateSessionRequest
+  ): Promise<CreateSessionResponse> {
+    try {
+      const response = await this.post<CreateSessionResponse>(
+        '/api/session/create',
+        options
+      );
+
+      this.logSuccess('Session created', `ID: ${options.id}`);
+      return response;
+    } catch (error) {
+      this.logError('createSession', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get the container version
+   * Returns the version embedded in the Docker image during build
+   */
+  async getVersion(): Promise<string> {
+    try {
+      const response = await this.get<VersionResponse>('/api/version');
+
+      this.logSuccess('Version retrieved', response.version);
+      return response.version;
+    } catch (error) {
+      // If version endpoint doesn't exist (old container), return 'unknown'
+      // This allows for backward compatibility
+      this.logger.debug(
+        'Failed to get container version (may be old container)',
+        { error }
+      );
+      return 'unknown';
+    }
+  }
+}

package/src/errors/adapter.ts

@@ -0,0 +1,238 @@
+/**
+ * Error adapter that converts ErrorResponse to appropriate Error class
+ *
+ * Simple switch statement - we trust the container sends correct context
+ * No validation overhead since we control both sides
+ */
+
+import type {
+  CodeExecutionContext,
+  CommandErrorContext,
+  CommandNotFoundContext,
+  ContextNotFoundContext,
+  ErrorResponse,
+  FileExistsContext,
+  FileNotFoundContext,
+  FileSystemContext,
+  GitAuthFailedContext,
+  GitBranchNotFoundContext,
+  GitErrorContext,
+  GitRepositoryNotFoundContext,
+  InternalErrorContext,
+  InterpreterNotReadyContext,
+  InvalidPortContext,
+  PortAlreadyExposedContext,
+  PortErrorContext,
+  PortNotExposedContext,
+  ProcessErrorContext,
+  ProcessNotFoundContext,
+  ValidationFailedContext
+} from '@repo/shared/errors';
+import { ErrorCode } from '@repo/shared/errors';
+
+import {
+  CodeExecutionError,
+  CommandError,
+  CommandNotFoundError,
+  ContextNotFoundError,
+  CustomDomainRequiredError,
+  FileExistsError,
+  FileNotFoundError,
+  FileSystemError,
+  GitAuthenticationError,
+  GitBranchNotFoundError,
+  GitCheckoutError,
+  GitCloneError,
+  GitError,
+  GitNetworkError,
+  GitRepositoryNotFoundError,
+  InterpreterNotReadyError,
+  InvalidGitUrlError,
+  InvalidPortError,
+  PermissionDeniedError,
+  PortAlreadyExposedError,
+  PortError,
+  PortInUseError,
+  PortNotExposedError,
+  ProcessError,
+  ProcessNotFoundError,
+  SandboxError,
+  ServiceNotRespondingError,
+  ValidationFailedError
+} from './classes';
+
+/**
+ * Convert ErrorResponse to appropriate Error class
+ * Simple switch statement - we trust the container sends correct context
+ */
+export function createErrorFromResponse(errorResponse: ErrorResponse): Error {
+  // We trust the container sends correct context, use type assertions
+  switch (errorResponse.code) {
+    // File System Errors
+    case ErrorCode.FILE_NOT_FOUND:
+      return new FileNotFoundError(
+        errorResponse as unknown as ErrorResponse<FileNotFoundContext>
+      );
+
+    case ErrorCode.FILE_EXISTS:
+      return new FileExistsError(
+        errorResponse as unknown as ErrorResponse<FileExistsContext>
+      );
+
+    case ErrorCode.PERMISSION_DENIED:
+      return new PermissionDeniedError(
+        errorResponse as unknown as ErrorResponse<FileSystemContext>
+      );
+
+    case ErrorCode.IS_DIRECTORY:
+    case ErrorCode.NOT_DIRECTORY:
+    case ErrorCode.NO_SPACE:
+    case ErrorCode.TOO_MANY_FILES:
+    case ErrorCode.RESOURCE_BUSY:
+    case ErrorCode.READ_ONLY:
+    case ErrorCode.NAME_TOO_LONG:
+    case ErrorCode.TOO_MANY_LINKS:
+    case ErrorCode.FILESYSTEM_ERROR:
+      return new FileSystemError(
+        errorResponse as unknown as ErrorResponse<FileSystemContext>
+      );
+
+    // Command Errors
+    case ErrorCode.COMMAND_NOT_FOUND:
+      return new CommandNotFoundError(
+        errorResponse as unknown as ErrorResponse<CommandNotFoundContext>
+      );
+
+    case ErrorCode.COMMAND_PERMISSION_DENIED:
+    case ErrorCode.COMMAND_EXECUTION_ERROR:
+    case ErrorCode.INVALID_COMMAND:
+    case ErrorCode.STREAM_START_ERROR:
+      return new CommandError(
+        errorResponse as unknown as ErrorResponse<CommandErrorContext>
+      );
+
+    // Process Errors
+    case ErrorCode.PROCESS_NOT_FOUND:
+      return new ProcessNotFoundError(
+        errorResponse as unknown as ErrorResponse<ProcessNotFoundContext>
+      );
+
+    case ErrorCode.PROCESS_PERMISSION_DENIED:
+    case ErrorCode.PROCESS_ERROR:
+      return new ProcessError(
+        errorResponse as unknown as ErrorResponse<ProcessErrorContext>
+      );
+
+    // Port Errors
+    case ErrorCode.PORT_ALREADY_EXPOSED:
+      return new PortAlreadyExposedError(
+        errorResponse as unknown as ErrorResponse<PortAlreadyExposedContext>
+      );
+
+    case ErrorCode.PORT_NOT_EXPOSED:
+      return new PortNotExposedError(
+        errorResponse as unknown as ErrorResponse<PortNotExposedContext>
+      );
+
+    case ErrorCode.INVALID_PORT_NUMBER:
+    case ErrorCode.INVALID_PORT:
+      return new InvalidPortError(
+        errorResponse as unknown as ErrorResponse<InvalidPortContext>
+      );
+
+    case ErrorCode.SERVICE_NOT_RESPONDING:
+      return new ServiceNotRespondingError(
+        errorResponse as unknown as ErrorResponse<PortErrorContext>
+      );
+
+    case ErrorCode.PORT_IN_USE:
+      return new PortInUseError(
+        errorResponse as unknown as ErrorResponse<PortErrorContext>
+      );
+
+    case ErrorCode.PORT_OPERATION_ERROR:
+      return new PortError(
+        errorResponse as unknown as ErrorResponse<PortErrorContext>
+      );
+
+    case ErrorCode.CUSTOM_DOMAIN_REQUIRED:
+      return new CustomDomainRequiredError(
+        errorResponse as unknown as ErrorResponse<InternalErrorContext>
+      );
+
+    // Git Errors
+    case ErrorCode.GIT_REPOSITORY_NOT_FOUND:
+      return new GitRepositoryNotFoundError(
+        errorResponse as unknown as ErrorResponse<GitRepositoryNotFoundContext>
+      );
+
+    case ErrorCode.GIT_AUTH_FAILED:
+      return new GitAuthenticationError(
+        errorResponse as unknown as ErrorResponse<GitAuthFailedContext>
+      );
+
+    case ErrorCode.GIT_BRANCH_NOT_FOUND:
+      return new GitBranchNotFoundError(
+        errorResponse as unknown as ErrorResponse<GitBranchNotFoundContext>
+      );
+
+    case ErrorCode.GIT_NETWORK_ERROR:
+      return new GitNetworkError(
+        errorResponse as unknown as ErrorResponse<GitErrorContext>
+      );
+
+    case ErrorCode.GIT_CLONE_FAILED:
+      return new GitCloneError(
+        errorResponse as unknown as ErrorResponse<GitErrorContext>
+      );
+
+    case ErrorCode.GIT_CHECKOUT_FAILED:
+      return new GitCheckoutError(
+        errorResponse as unknown as ErrorResponse<GitErrorContext>
+      );
+
+    case ErrorCode.INVALID_GIT_URL:
+      return new InvalidGitUrlError(
+        errorResponse as unknown as ErrorResponse<ValidationFailedContext>
+      );
+
+    case ErrorCode.GIT_OPERATION_FAILED:
+      return new GitError(
+        errorResponse as unknown as ErrorResponse<GitErrorContext>
+      );
+
+    // Code Interpreter Errors
+    case ErrorCode.INTERPRETER_NOT_READY:
+      return new InterpreterNotReadyError(
+        errorResponse as unknown as ErrorResponse<InterpreterNotReadyContext>
+      );
+
+    case ErrorCode.CONTEXT_NOT_FOUND:
+      return new ContextNotFoundError(
+        errorResponse as unknown as ErrorResponse<ContextNotFoundContext>
+      );
+
+    case ErrorCode.CODE_EXECUTION_ERROR:
+      return new CodeExecutionError(
+        errorResponse as unknown as ErrorResponse<CodeExecutionContext>
+      );
+
+    // Validation Errors
+    case ErrorCode.VALIDATION_FAILED:
+      return new ValidationFailedError(
+        errorResponse as unknown as ErrorResponse<ValidationFailedContext>
+      );
+
+    // Generic Errors
+    case ErrorCode.INVALID_JSON_RESPONSE:
+    case ErrorCode.UNKNOWN_ERROR:
+    case ErrorCode.INTERNAL_ERROR:
+      return new SandboxError(
+        errorResponse as unknown as ErrorResponse<InternalErrorContext>
+      );
+
+    default:
+      // Fallback for unknown error codes
+      return new SandboxError(errorResponse);
+  }
+}