@cloudflare/sandbox 0.0.0-cecde0a → 0.0.0-d4bb3b7

package/src/clients/base-client.ts

@@ -0,0 +1,295 @@
+import type { Logger } from '@repo/shared';
+import { createNoOpLogger } from '@repo/shared';
+import { getHttpStatus } from '@repo/shared/errors';
+import type { ErrorResponse as NewErrorResponse } from '../errors';
+import { createErrorFromResponse, ErrorCode } from '../errors';
+import type { SandboxError } from '../errors/classes';
+import type { HttpClientOptions, ResponseHandler } from './types';
+
+// Container provisioning retry configuration
+const TIMEOUT_MS = 60_000; // 60 seconds total timeout budget
+const MIN_TIME_FOR_RETRY_MS = 10_000; // Need at least 10s remaining to retry (8s Container + 2s delay)
+
+/**
+ * Abstract base class providing common HTTP functionality for all domain clients
+ */
+export abstract class BaseHttpClient {
+  protected baseUrl: string;
+  protected options: HttpClientOptions;
+  protected logger: Logger;
+
+  constructor(options: HttpClientOptions = {}) {
+    this.options = options;
+    this.logger = options.logger ?? createNoOpLogger();
+    this.baseUrl = this.options.baseUrl!;
+  }
+
+  /**
+   * Core HTTP request method with automatic retry for container provisioning delays
+   */
+  protected async doFetch(
+    path: string,
+    options?: RequestInit
+  ): Promise<Response> {
+    const startTime = Date.now();
+    let attempt = 0;
+
+    while (true) {
+      const response = await this.executeFetch(path, options);
+
+      // Only retry container provisioning 503s, not user app 503s
+      if (response.status === 503) {
+        const isContainerProvisioning =
+          await this.isContainerProvisioningError(response);
+
+        if (isContainerProvisioning) {
+          const elapsed = Date.now() - startTime;
+          const remaining = TIMEOUT_MS - elapsed;
+
+          // Check if we have enough time for another attempt
+          // (Need at least 10s: 8s for Container timeout + 2s delay)
+          if (remaining > MIN_TIME_FOR_RETRY_MS) {
+            // Exponential backoff: 2s, 4s, 8s, 16s (capped at 16s)
+            const delay = Math.min(2000 * 2 ** attempt, 16000);
+
+            this.logger.info('Container provisioning in progress, retrying', {
+              attempt: attempt + 1,
+              delayMs: delay,
+              remainingSec: Math.floor(remaining / 1000)
+            });
+
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            attempt++;
+            continue;
+          } else {
+            // Exhausted retries - log error and return response
+            // Let existing error handling convert to proper error
+            this.logger.error(
+              'Container failed to provision after multiple attempts',
+              new Error(`Failed after ${attempt + 1} attempts over 60s`)
+            );
+            return response;
+          }
+        }
+      }
+
+      return response;
+    }
+  }
+
+  /**
+   * Make a POST request with JSON body
+   */
+  protected async post<T>(
+    endpoint: string,
+    data: Record<string, any>,
+    responseHandler?: ResponseHandler<T>
+  ): Promise<T> {
+    const response = await this.doFetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(data)
+    });
+
+    return this.handleResponse(response, responseHandler);
+  }
+
+  /**
+   * Make a GET request
+   */
+  protected async get<T>(
+    endpoint: string,
+    responseHandler?: ResponseHandler<T>
+  ): Promise<T> {
+    const response = await this.doFetch(endpoint, {
+      method: 'GET'
+    });
+
+    return this.handleResponse(response, responseHandler);
+  }
+
+  /**
+   * Make a DELETE request
+   */
+  protected async delete<T>(
+    endpoint: string,
+    responseHandler?: ResponseHandler<T>
+  ): Promise<T> {
+    const response = await this.doFetch(endpoint, {
+      method: 'DELETE'
+    });
+
+    return this.handleResponse(response, responseHandler);
+  }
+
+  /**
+   * Handle HTTP response with error checking and parsing
+   */
+  protected async handleResponse<T>(
+    response: Response,
+    customHandler?: ResponseHandler<T>
+  ): Promise<T> {
+    if (!response.ok) {
+      await this.handleErrorResponse(response);
+    }
+
+    if (customHandler) {
+      return customHandler(response);
+    }
+
+    try {
+      return await response.json();
+    } catch (error) {
+      // Handle malformed JSON responses gracefully
+      const errorResponse: NewErrorResponse = {
+        code: ErrorCode.INVALID_JSON_RESPONSE,
+        message: `Invalid JSON response: ${
+          error instanceof Error ? error.message : 'Unknown parsing error'
+        }`,
+        context: {},
+        httpStatus: response.status,
+        timestamp: new Date().toISOString()
+      };
+      throw createErrorFromResponse(errorResponse);
+    }
+  }
+
+  /**
+   * Handle error responses with consistent error throwing
+   */
+  protected async handleErrorResponse(response: Response): Promise<never> {
+    let errorData: NewErrorResponse;
+
+    try {
+      errorData = await response.json();
+    } catch {
+      // Fallback if response isn't JSON or parsing fails
+      errorData = {
+        code: ErrorCode.INTERNAL_ERROR,
+        message: `HTTP error! status: ${response.status}`,
+        context: { statusText: response.statusText },
+        httpStatus: response.status,
+        timestamp: new Date().toISOString()
+      };
+    }
+
+    // Convert ErrorResponse to appropriate Error class
+    const error = createErrorFromResponse(errorData);
+
+    // Call error callback if provided
+    this.options.onError?.(errorData.message, undefined);
+
+    throw error;
+  }
+
+  /**
+   * Create a streaming response handler for Server-Sent Events
+   */
+  protected async handleStreamResponse(
+    response: Response
+  ): Promise<ReadableStream<Uint8Array>> {
+    if (!response.ok) {
+      await this.handleErrorResponse(response);
+    }
+
+    if (!response.body) {
+      throw new Error('No response body for streaming');
+    }
+
+    return response.body;
+  }
+
+  /**
+   * Utility method to log successful operations
+   */
+  protected logSuccess(operation: string, details?: string): void {
+    this.logger.info(
+      `${operation} completed successfully`,
+      details ? { details } : undefined
+    );
+  }
+
+  /**
+   * Utility method to log errors intelligently
+   * Only logs unexpected errors (5xx), not expected errors (4xx)
+   *
+   * - 4xx errors (validation, not found, conflicts): Don't log (expected client errors)
+   * - 5xx errors (server failures, internal errors): DO log (unexpected server errors)
+   */
+  protected logError(operation: string, error: unknown): void {
+    // Check if it's a SandboxError with HTTP status
+    if (error && typeof error === 'object' && 'httpStatus' in error) {
+      const httpStatus = (error as SandboxError).httpStatus;
+
+      // Only log server errors (5xx), not client errors (4xx)
+      if (httpStatus >= 500) {
+        this.logger.error(
+          `Unexpected error in ${operation}`,
+          error instanceof Error ? error : new Error(String(error)),
+          { httpStatus }
+        );
+      }
+      // 4xx errors are expected (validation, not found, etc.) - don't log
+    } else {
+      // Non-SandboxError (unexpected) - log it
+      this.logger.error(
+        `Error in ${operation}`,
+        error instanceof Error ? error : new Error(String(error))
+      );
+    }
+  }
+
+  /**
+   * Check if 503 response is from container provisioning (retryable)
+   * vs user application (not retryable)
+   */
+  private async isContainerProvisioningError(
+    response: Response
+  ): Promise<boolean> {
+    try {
+      // Clone response so we don't consume the original body
+      const cloned = response.clone();
+      const text = await cloned.text();
+
+      // Container package returns specific message for provisioning errors
+      return text.includes('There is no Container instance available');
+    } catch (error) {
+      this.logger.error(
+        'Error checking response body',
+        error instanceof Error ? error : new Error(String(error))
+      );
+      // If we can't read the body, don't retry to be safe
+      return false;
+    }
+  }
+
+  private async executeFetch(
+    path: string,
+    options?: RequestInit
+  ): Promise<Response> {
+    const url = this.options.stub
+      ? `http://localhost:${this.options.port}${path}`
+      : `${this.baseUrl}${path}`;
+
+    try {
+      if (this.options.stub) {
+        return await this.options.stub.containerFetch(
+          url,
+          options || {},
+          this.options.port
+        );
+      } else {
+        return await fetch(url, options);
+      }
+    } catch (error) {
+      this.logger.error(
+        'HTTP request error',
+        error instanceof Error ? error : new Error(String(error)),
+        { method: options?.method || 'GET', url }
+      );
+      throw error;
+    }
+  }
+}

package/src/clients/command-client.ts

@@ -0,0 +1,115 @@
+import { BaseHttpClient } from './base-client';
+import type {
+  BaseApiResponse,
+  HttpClientOptions,
+  SessionRequest
+} from './types';
+
+/**
+ * Request interface for command execution
+ */
+export interface ExecuteRequest extends SessionRequest {
+  command: string;
+  timeoutMs?: number;
+}
+
+/**
+ * Response interface for command execution
+ */
+export interface ExecuteResponse extends BaseApiResponse {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  command: string;
+}
+
+/**
+ * Client for command execution operations
+ */
+export class CommandClient extends BaseHttpClient {
+  /**
+   * Execute a command and return the complete result
+   * @param command - The command to execute
+   * @param sessionId - The session ID for this command execution
+   * @param timeoutMs - Optional timeout in milliseconds (unlimited by default)
+   */
+  async execute(
+    command: string,
+    sessionId: string,
+    timeoutMs?: number
+  ): Promise<ExecuteResponse> {
+    try {
+      const data: ExecuteRequest = {
+        command,
+        sessionId,
+        ...(timeoutMs !== undefined && { timeoutMs })
+      };
+
+      const response = await this.post<ExecuteResponse>('/api/execute', data);
+
+      this.logSuccess(
+        'Command executed',
+        `${command}, Success: ${response.success}`
+      );
+
+      // Call the callback if provided
+      this.options.onCommandComplete?.(
+        response.success,
+        response.exitCode,
+        response.stdout,
+        response.stderr,
+        response.command
+      );
+
+      return response;
+    } catch (error) {
+      this.logError('execute', error);
+
+      // Call error callback if provided
+      this.options.onError?.(
+        error instanceof Error ? error.message : String(error),
+        command
+      );
+
+      throw error;
+    }
+  }
+
+  /**
+   * Execute a command and return a stream of events
+   * @param command - The command to execute
+   * @param sessionId - The session ID for this command execution
+   */
+  async executeStream(
+    command: string,
+    sessionId: string
+  ): Promise<ReadableStream<Uint8Array>> {
+    try {
+      const data = { command, sessionId };
+
+      const response = await this.doFetch('/api/execute/stream', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(data)
+      });
+
+      const stream = await this.handleStreamResponse(response);
+
+      this.logSuccess('Command stream started', command);
+
+      return stream;
+    } catch (error) {
+      this.logError('executeStream', error);
+
+      // Call error callback if provided
+      this.options.onError?.(
+        error instanceof Error ? error.message : String(error),
+        command
+      );
+
+      throw error;
+    }
+  }
+}

package/src/clients/file-client.ts

@@ -0,0 +1,300 @@
+import type {
+  DeleteFileResult,
+  FileExistsResult,
+  ListFilesOptions,
+  ListFilesResult,
+  MkdirResult,
+  MoveFileResult,
+  ReadFileResult,
+  RenameFileResult,
+  WriteFileResult
+} from '@repo/shared';
+import { BaseHttpClient } from './base-client';
+import type { HttpClientOptions, SessionRequest } from './types';
+
+/**
+ * Request interface for creating directories
+ */
+export interface MkdirRequest extends SessionRequest {
+  path: string;
+  recursive?: boolean;
+}
+
+/**
+ * Request interface for writing files
+ */
+export interface WriteFileRequest extends SessionRequest {
+  path: string;
+  content: string;
+  encoding?: string;
+}
+
+/**
+ * Request interface for reading files
+ */
+export interface ReadFileRequest extends SessionRequest {
+  path: string;
+  encoding?: string;
+}
+
+/**
+ * Request interface for file operations (delete, rename, move)
+ */
+export interface FileOperationRequest extends SessionRequest {
+  path: string;
+  newPath?: string; // For rename/move operations
+}
+
+/**
+ * Client for file system operations
+ */
+export class FileClient extends BaseHttpClient {
+  /**
+   * Create a directory
+   * @param path - Directory path to create
+   * @param sessionId - The session ID for this operation
+   * @param options - Optional settings (recursive)
+   */
+  async mkdir(
+    path: string,
+    sessionId: string,
+    options?: { recursive?: boolean }
+  ): Promise<MkdirResult> {
+    try {
+      const data = {
+        path,
+        sessionId,
+        recursive: options?.recursive ?? false
+      };
+
+      const response = await this.post<MkdirResult>('/api/mkdir', data);
+
+      this.logSuccess(
+        'Directory created',
+        `${path} (recursive: ${data.recursive})`
+      );
+      return response;
+    } catch (error) {
+      this.logError('mkdir', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Write content to a file
+   * @param path - File path to write to
+   * @param content - Content to write
+   * @param sessionId - The session ID for this operation
+   * @param options - Optional settings (encoding)
+   */
+  async writeFile(
+    path: string,
+    content: string,
+    sessionId: string,
+    options?: { encoding?: string }
+  ): Promise<WriteFileResult> {
+    try {
+      const data = {
+        path,
+        content,
+        sessionId,
+        encoding: options?.encoding
+      };
+
+      const response = await this.post<WriteFileResult>('/api/write', data);
+
+      this.logSuccess('File written', `${path} (${content.length} chars)`);
+      return response;
+    } catch (error) {
+      this.logError('writeFile', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Read content from a file
+   * @param path - File path to read from
+   * @param sessionId - The session ID for this operation
+   * @param options - Optional settings (encoding)
+   */
+  async readFile(
+    path: string,
+    sessionId: string,
+    options?: { encoding?: string }
+  ): Promise<ReadFileResult> {
+    try {
+      const data = {
+        path,
+        sessionId,
+        encoding: options?.encoding
+      };
+
+      const response = await this.post<ReadFileResult>('/api/read', data);
+
+      this.logSuccess(
+        'File read',
+        `${path} (${response.content.length} chars)`
+      );
+      return response;
+    } catch (error) {
+      this.logError('readFile', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Stream a file using Server-Sent Events
+   * Returns a ReadableStream of SSE events containing metadata, chunks, and completion
+   * @param path - File path to stream
+   * @param sessionId - The session ID for this operation
+   */
+  async readFileStream(
+    path: string,
+    sessionId: string
+  ): Promise<ReadableStream<Uint8Array>> {
+    try {
+      const data = {
+        path,
+        sessionId
+      };
+
+      const response = await this.doFetch('/api/read/stream', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(data)
+      });
+
+      const stream = await this.handleStreamResponse(response);
+      this.logSuccess('File stream started', path);
+      return stream;
+    } catch (error) {
+      this.logError('readFileStream', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Delete a file
+   * @param path - File path to delete
+   * @param sessionId - The session ID for this operation
+   */
+  async deleteFile(path: string, sessionId: string): Promise<DeleteFileResult> {
+    try {
+      const data = { path, sessionId };
+
+      const response = await this.post<DeleteFileResult>('/api/delete', data);
+
+      this.logSuccess('File deleted', path);
+      return response;
+    } catch (error) {
+      this.logError('deleteFile', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Rename a file
+   * @param path - Current file path
+   * @param newPath - New file path
+   * @param sessionId - The session ID for this operation
+   */
+  async renameFile(
+    path: string,
+    newPath: string,
+    sessionId: string
+  ): Promise<RenameFileResult> {
+    try {
+      const data = { oldPath: path, newPath, sessionId };
+
+      const response = await this.post<RenameFileResult>('/api/rename', data);
+
+      this.logSuccess('File renamed', `${path} -> ${newPath}`);
+      return response;
+    } catch (error) {
+      this.logError('renameFile', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Move a file
+   * @param path - Current file path
+   * @param newPath - Destination file path
+   * @param sessionId - The session ID for this operation
+   */
+  async moveFile(
+    path: string,
+    newPath: string,
+    sessionId: string
+  ): Promise<MoveFileResult> {
+    try {
+      const data = { sourcePath: path, destinationPath: newPath, sessionId };
+
+      const response = await this.post<MoveFileResult>('/api/move', data);
+
+      this.logSuccess('File moved', `${path} -> ${newPath}`);
+      return response;
+    } catch (error) {
+      this.logError('moveFile', error);
+      throw error;
+    }
+  }
+
+  /**
+   * List files in a directory
+   * @param path - Directory path to list
+   * @param sessionId - The session ID for this operation
+   * @param options - Optional settings (recursive, includeHidden)
+   */
+  async listFiles(
+    path: string,
+    sessionId: string,
+    options?: ListFilesOptions
+  ): Promise<ListFilesResult> {
+    try {
+      const data = {
+        path,
+        sessionId,
+        options: options || {}
+      };
+
+      const response = await this.post<ListFilesResult>(
+        '/api/list-files',
+        data
+      );
+
+      this.logSuccess('Files listed', `${path} (${response.count} files)`);
+      return response;
+    } catch (error) {
+      this.logError('listFiles', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Check if a file or directory exists
+   * @param path - Path to check
+   * @param sessionId - The session ID for this operation
+   */
+  async exists(path: string, sessionId: string): Promise<FileExistsResult> {
+    try {
+      const data = {
+        path,
+        sessionId
+      };
+
+      const response = await this.post<FileExistsResult>('/api/exists', data);
+
+      this.logSuccess(
+        'Path existence checked',
+        `${path} (exists: ${response.exists})`
+      );
+      return response;
+    } catch (error) {
+      this.logError('exists', error);
+      throw error;
+    }
+  }
+}