@cloudflare/sandbox 0.0.0-02ee8fe

package/src/clients/types.ts

@@ -0,0 +1,84 @@
+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,119 @@
+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,180 @@
+/**
+ * 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);
+  }
+}