@cloudflare/sandbox 0.4.11 → 0.4.14

package/dist/request-handler.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/sandbox-DWQVgVTY.d.ts

@@ -1,603 +0,0 @@
-import * as _repo_shared from '@repo/shared';
-import { Logger, MkdirResult, WriteFileResult, ReadFileResult, DeleteFileResult, RenameFileResult, MoveFileResult, ListFilesOptions, ListFilesResult, FileExistsResult, GitCheckoutResult, CreateContextOptions, CodeContext, OutputMessage, Result, ExecutionError, PortExposeResult, PortCloseResult, PortListResult, ProcessStartResult, ProcessListResult, ProcessInfoResult, ProcessKillResult, ProcessCleanupResult, ProcessLogsResult, ISandbox, ExecOptions, ExecResult, ProcessOptions, Process, StreamOptions, SessionOptions, ExecutionSession, RunCodeOptions, ExecutionResult, SandboxOptions } from '@repo/shared';
-import { DurableObject } from 'cloudflare:workers';
-import { Container } from '@cloudflare/containers';
-
-/**
- * Minimal interface for container fetch functionality
- */
-interface ContainerStub {
-    containerFetch(url: string, options: RequestInit, port?: number): Promise<Response>;
-}
-/**
- * Shared HTTP client configuration options
- */
-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
- */
-interface BaseApiResponse {
-    success: boolean;
-    timestamp: string;
-}
-/**
- * Legacy error response interface - deprecated, use ApiErrorResponse
- */
-interface ErrorResponse {
-    error: string;
-    details?: string;
-    code?: string;
-}
-/**
- * HTTP request configuration
- */
-interface RequestConfig extends RequestInit {
-    endpoint: string;
-    data?: Record<string, any>;
-}
-/**
- * Typed response handler
- */
-type ResponseHandler<T> = (response: Response) => Promise<T>;
-/**
- * Common session-aware request interface
- */
-interface SessionRequest {
-    sessionId?: string;
-}
-
-/**
- * Abstract base class providing common HTTP functionality for all domain clients
- */
-declare abstract class BaseHttpClient {
-    protected baseUrl: string;
-    protected options: HttpClientOptions;
-    protected logger: Logger;
-    constructor(options?: HttpClientOptions);
-    /**
-     * Core HTTP request method with automatic retry for container provisioning delays
-     */
-    protected doFetch(path: string, options?: RequestInit): Promise<Response>;
-    /**
-     * Make a POST request with JSON body
-     */
-    protected post<T>(endpoint: string, data: Record<string, any>, responseHandler?: ResponseHandler<T>): Promise<T>;
-    /**
-     * Make a GET request
-     */
-    protected get<T>(endpoint: string, responseHandler?: ResponseHandler<T>): Promise<T>;
-    /**
-     * Make a DELETE request
-     */
-    protected delete<T>(endpoint: string, responseHandler?: ResponseHandler<T>): Promise<T>;
-    /**
-     * Handle HTTP response with error checking and parsing
-     */
-    protected handleResponse<T>(response: Response, customHandler?: ResponseHandler<T>): Promise<T>;
-    /**
-     * Handle error responses with consistent error throwing
-     */
-    protected handleErrorResponse(response: Response): Promise<never>;
-    /**
-     * Create a streaming response handler for Server-Sent Events
-     */
-    protected handleStreamResponse(response: Response): Promise<ReadableStream<Uint8Array>>;
-    /**
-     * Utility method to log successful operations
-     */
-    protected logSuccess(operation: string, details?: string): void;
-    /**
-     * 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 503 response is from container provisioning (retryable)
-     * vs user application (not retryable)
-     */
-    private isContainerProvisioningError;
-    private executeFetch;
-}
-
-/**
- * Request interface for command execution
- */
-interface ExecuteRequest extends SessionRequest {
-    command: string;
-    timeoutMs?: number;
-}
-/**
- * Response interface for command execution
- */
-interface ExecuteResponse extends BaseApiResponse {
-    stdout: string;
-    stderr: string;
-    exitCode: number;
-    command: string;
-}
-/**
- * Client for command execution operations
- */
-declare 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)
-     */
-    execute(command: string, sessionId: string, timeoutMs?: number): Promise<ExecuteResponse>;
-    /**
-     * Execute a command and return a stream of events
-     * @param command - The command to execute
-     * @param sessionId - The session ID for this command execution
-     */
-    executeStream(command: string, sessionId: string): Promise<ReadableStream<Uint8Array>>;
-}
-
-/**
- * Request interface for creating directories
- */
-interface MkdirRequest extends SessionRequest {
-    path: string;
-    recursive?: boolean;
-}
-/**
- * Request interface for writing files
- */
-interface WriteFileRequest extends SessionRequest {
-    path: string;
-    content: string;
-    encoding?: string;
-}
-/**
- * Request interface for reading files
- */
-interface ReadFileRequest extends SessionRequest {
-    path: string;
-    encoding?: string;
-}
-/**
- * Request interface for file operations (delete, rename, move)
- */
-interface FileOperationRequest extends SessionRequest {
-    path: string;
-    newPath?: string;
-}
-/**
- * Client for file system operations
- */
-declare 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)
-     */
-    mkdir(path: string, sessionId: string, options?: {
-        recursive?: boolean;
-    }): Promise<MkdirResult>;
-    /**
-     * 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)
-     */
-    writeFile(path: string, content: string, sessionId: string, options?: {
-        encoding?: string;
-    }): Promise<WriteFileResult>;
-    /**
-     * 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)
-     */
-    readFile(path: string, sessionId: string, options?: {
-        encoding?: string;
-    }): Promise<ReadFileResult>;
-    /**
-     * 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
-     */
-    readFileStream(path: string, sessionId: string): Promise<ReadableStream<Uint8Array>>;
-    /**
-     * Delete a file
-     * @param path - File path to delete
-     * @param sessionId - The session ID for this operation
-     */
-    deleteFile(path: string, sessionId: string): Promise<DeleteFileResult>;
-    /**
-     * Rename a file
-     * @param path - Current file path
-     * @param newPath - New file path
-     * @param sessionId - The session ID for this operation
-     */
-    renameFile(path: string, newPath: string, sessionId: string): Promise<RenameFileResult>;
-    /**
-     * Move a file
-     * @param path - Current file path
-     * @param newPath - Destination file path
-     * @param sessionId - The session ID for this operation
-     */
-    moveFile(path: string, newPath: string, sessionId: string): Promise<MoveFileResult>;
-    /**
-     * 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)
-     */
-    listFiles(path: string, sessionId: string, options?: ListFilesOptions): Promise<ListFilesResult>;
-    /**
-     * Check if a file or directory exists
-     * @param path - Path to check
-     * @param sessionId - The session ID for this operation
-     */
-    exists(path: string, sessionId: string): Promise<FileExistsResult>;
-}
-
-/**
- * Request interface for Git checkout operations
- */
-interface GitCheckoutRequest extends SessionRequest {
-    repoUrl: string;
-    branch?: string;
-    targetDir?: string;
-}
-/**
- * Client for Git repository operations
- */
-declare 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)
-     */
-    checkout(repoUrl: string, sessionId: string, options?: {
-        branch?: string;
-        targetDir?: string;
-    }): Promise<GitCheckoutResult>;
-    /**
-     * Extract repository name from URL for default directory name
-     */
-    private extractRepoName;
-}
-
-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>;
-}
-declare class InterpreterClient extends BaseHttpClient {
-    private readonly maxRetries;
-    private readonly retryDelayMs;
-    createCodeContext(options?: CreateContextOptions): Promise<CodeContext>;
-    runCodeStream(contextId: string | undefined, code: string, language: string | undefined, callbacks: ExecutionCallbacks, timeoutMs?: number): Promise<void>;
-    listCodeContexts(): Promise<CodeContext[]>;
-    deleteCodeContext(contextId: string): Promise<void>;
-    /**
-     * Execute an operation with automatic retry for transient errors
-     */
-    private executeWithRetry;
-    private isRetryableError;
-    private parseErrorResponse;
-    private readLines;
-    private parseExecutionResult;
-}
-
-/**
- * Request interface for exposing ports
- */
-interface ExposePortRequest {
-    port: number;
-    name?: string;
-}
-/**
- * Request interface for unexposing ports
- */
-interface UnexposePortRequest {
-    port: number;
-}
-/**
- * Client for port management and preview URL operations
- */
-declare 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
-     */
-    exposePort(port: number, sessionId: string, name?: string): Promise<PortExposeResult>;
-    /**
-     * Unexpose a port and remove its preview URL
-     * @param port - Port number to unexpose
-     * @param sessionId - The session ID for this operation
-     */
-    unexposePort(port: number, sessionId: string): Promise<PortCloseResult>;
-    /**
-     * Get all currently exposed ports
-     * @param sessionId - The session ID for this operation
-     */
-    getExposedPorts(sessionId: string): Promise<PortListResult>;
-}
-
-/**
- * Client for background process management
- */
-declare 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)
-     */
-    startProcess(command: string, sessionId: string, options?: {
-        processId?: string;
-    }): Promise<ProcessStartResult>;
-    /**
-     * List all processes (sandbox-scoped, not session-scoped)
-     */
-    listProcesses(): Promise<ProcessListResult>;
-    /**
-     * Get information about a specific process (sandbox-scoped, not session-scoped)
-     * @param processId - ID of the process to retrieve
-     */
-    getProcess(processId: string): Promise<ProcessInfoResult>;
-    /**
-     * Kill a specific process (sandbox-scoped, not session-scoped)
-     * @param processId - ID of the process to kill
-     */
-    killProcess(processId: string): Promise<ProcessKillResult>;
-    /**
-     * Kill all running processes (sandbox-scoped, not session-scoped)
-     */
-    killAllProcesses(): Promise<ProcessCleanupResult>;
-    /**
-     * Get logs from a specific process (sandbox-scoped, not session-scoped)
-     * @param processId - ID of the process to get logs from
-     */
-    getProcessLogs(processId: string): Promise<ProcessLogsResult>;
-    /**
-     * Stream logs from a specific process (sandbox-scoped, not session-scoped)
-     * @param processId - ID of the process to stream logs from
-     */
-    streamProcessLogs(processId: string): Promise<ReadableStream<Uint8Array>>;
-}
-
-/**
- * Response interface for ping operations
- */
-interface PingResponse extends BaseApiResponse {
-    message: string;
-    uptime?: number;
-}
-/**
- * Response interface for getting available commands
- */
-interface CommandsResponse extends BaseApiResponse {
-    availableCommands: string[];
-    count: number;
-}
-/**
- * Request interface for creating sessions
- */
-interface CreateSessionRequest {
-    id: string;
-    env?: Record<string, string>;
-    cwd?: string;
-}
-/**
- * Response interface for creating sessions
- */
-interface CreateSessionResponse extends BaseApiResponse {
-    id: string;
-    message: string;
-}
-/**
- * Client for health checks and utility operations
- */
-declare class UtilityClient extends BaseHttpClient {
-    /**
-     * Ping the sandbox to check if it's responsive
-     */
-    ping(): Promise<string>;
-    /**
-     * Get list of available commands in the sandbox environment
-     */
-    getCommands(): Promise<string[]>;
-    /**
-     * Create a new execution session
-     * @param options - Session configuration (id, env, cwd)
-     */
-    createSession(options: CreateSessionRequest): Promise<CreateSessionResponse>;
-    /**
-     * Get the container version
-     * Returns the version embedded in the Docker image during build
-     */
-    getVersion(): Promise<string>;
-}
-
-/**
- * Main sandbox client that composes all domain-specific clients
- * Provides organized access to all sandbox functionality
- */
-declare class SandboxClient {
-    readonly commands: CommandClient;
-    readonly files: FileClient;
-    readonly processes: ProcessClient;
-    readonly ports: PortClient;
-    readonly git: GitClient;
-    readonly interpreter: InterpreterClient;
-    readonly utils: UtilityClient;
-    constructor(options: HttpClientOptions);
-}
-
-declare function getSandbox(ns: DurableObjectNamespace<Sandbox>, id: string, options?: SandboxOptions): DurableObjectStub<Sandbox<unknown>>;
-declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
-    defaultPort: number;
-    sleepAfter: string | number;
-    client: SandboxClient;
-    private codeInterpreter;
-    private sandboxName;
-    private baseUrl;
-    private portTokens;
-    private defaultSession;
-    envVars: Record<string, string>;
-    private logger;
-    constructor(ctx: DurableObject['ctx'], env: Env);
-    setSandboxName(name: string): Promise<void>;
-    setBaseUrl(baseUrl: string): Promise<void>;
-    setSleepAfter(sleepAfter: string | number): Promise<void>;
-    setEnvVars(envVars: Record<string, string>): Promise<void>;
-    /**
-     * Cleanup and destroy the sandbox container
-     */
-    destroy(): Promise<void>;
-    onStart(): void;
-    /**
-     * Check if the container version matches the SDK version
-     * Logs a warning if there's a mismatch
-     */
-    private checkVersionCompatibility;
-    onStop(): void;
-    onError(error: unknown): void;
-    fetch(request: Request): Promise<Response>;
-    private determinePort;
-    /**
-     * Ensure default session exists - lazy initialization
-     * This is called automatically by all public methods that need a session
-     *
-     * The session is persisted to Durable Object storage to survive hot reloads
-     * during development. If a session already exists in the container after reload,
-     * we reuse it instead of trying to create a new one.
-     */
-    private ensureDefaultSession;
-    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
-    /**
-     * Internal session-aware exec implementation
-     * Used by both public exec() and session wrappers
-     */
-    private execWithSession;
-    private executeWithStreaming;
-    private mapExecuteResponseToExecResult;
-    /**
-     * Create a Process domain object from HTTP client DTO
-     * Centralizes process object creation with bound methods
-     * This eliminates duplication across startProcess, listProcesses, getProcess, and session wrappers
-     */
-    private createProcessFromDTO;
-    startProcess(command: string, options?: ProcessOptions, sessionId?: string): Promise<Process>;
-    listProcesses(sessionId?: string): Promise<Process[]>;
-    getProcess(id: string, sessionId?: string): Promise<Process | null>;
-    killProcess(id: string, signal?: string, sessionId?: string): Promise<void>;
-    killAllProcesses(sessionId?: string): Promise<number>;
-    cleanupCompletedProcesses(sessionId?: string): Promise<number>;
-    getProcessLogs(id: string, sessionId?: string): Promise<{
-        stdout: string;
-        stderr: string;
-        processId: string;
-    }>;
-    execStream(command: string, options?: StreamOptions): Promise<ReadableStream<Uint8Array>>;
-    /**
-     * Internal session-aware execStream implementation
-     */
-    private execStreamWithSession;
-    streamProcessLogs(processId: string, options?: {
-        signal?: AbortSignal;
-    }): Promise<ReadableStream<Uint8Array>>;
-    gitCheckout(repoUrl: string, options: {
-        branch?: string;
-        targetDir?: string;
-        sessionId?: string;
-    }): Promise<_repo_shared.GitCheckoutResult>;
-    mkdir(path: string, options?: {
-        recursive?: boolean;
-        sessionId?: string;
-    }): Promise<_repo_shared.MkdirResult>;
-    writeFile(path: string, content: string, options?: {
-        encoding?: string;
-        sessionId?: string;
-    }): Promise<_repo_shared.WriteFileResult>;
-    deleteFile(path: string, sessionId?: string): Promise<_repo_shared.DeleteFileResult>;
-    renameFile(oldPath: string, newPath: string, sessionId?: string): Promise<_repo_shared.RenameFileResult>;
-    moveFile(sourcePath: string, destinationPath: string, sessionId?: string): Promise<_repo_shared.MoveFileResult>;
-    readFile(path: string, options?: {
-        encoding?: string;
-        sessionId?: string;
-    }): Promise<_repo_shared.ReadFileResult>;
-    /**
-     * Stream a file from the sandbox using Server-Sent Events
-     * Returns a ReadableStream that can be consumed with streamFile() or collectFile() utilities
-     * @param path - Path to the file to stream
-     * @param options - Optional session ID
-     */
-    readFileStream(path: string, options?: {
-        sessionId?: string;
-    }): Promise<ReadableStream<Uint8Array>>;
-    listFiles(path: string, options?: {
-        recursive?: boolean;
-        includeHidden?: boolean;
-    }): Promise<_repo_shared.ListFilesResult>;
-    exists(path: string, sessionId?: string): Promise<_repo_shared.FileExistsResult>;
-    exposePort(port: number, options: {
-        name?: string;
-        hostname: string;
-    }): Promise<{
-        url: string;
-        port: number;
-        name: string | undefined;
-    }>;
-    unexposePort(port: number): Promise<void>;
-    getExposedPorts(hostname: string): Promise<{
-        url: string;
-        port: number;
-        status: "active" | "inactive";
-    }[]>;
-    isPortExposed(port: number): Promise<boolean>;
-    validatePortToken(port: number, token: string): Promise<boolean>;
-    private generatePortToken;
-    private persistPortTokens;
-    private constructPreviewUrl;
-    /**
-     * Create isolated execution session for advanced use cases
-     * Returns ExecutionSession with full sandbox API bound to specific session
-     */
-    createSession(options?: SessionOptions): Promise<ExecutionSession>;
-    /**
-     * Get an existing session by ID
-     * Returns ExecutionSession wrapper bound to the specified session
-     *
-     * This is useful for retrieving sessions across different requests/contexts
-     * without storing the ExecutionSession object (which has RPC lifecycle limitations)
-     *
-     * @param sessionId - The ID of an existing session
-     * @returns ExecutionSession wrapper bound to the session
-     */
-    getSession(sessionId: string): Promise<ExecutionSession>;
-    /**
-     * Internal helper to create ExecutionSession wrapper for a given sessionId
-     * Used by both createSession and getSession
-     */
-    private getSessionWrapper;
-    createCodeContext(options?: CreateContextOptions): Promise<CodeContext>;
-    runCode(code: string, options?: RunCodeOptions): Promise<ExecutionResult>;
-    runCodeStream(code: string, options?: RunCodeOptions): Promise<ReadableStream>;
-    listCodeContexts(): Promise<CodeContext[]>;
-    deleteCodeContext(contextId: string): Promise<void>;
-}
-
-export { type BaseApiResponse as B, CommandClient as C, type ErrorResponse as E, FileClient as F, GitClient as G, type HttpClientOptions as H, InterpreterClient as I, type MkdirRequest as M, PortClient as P, type ReadFileRequest as R, SandboxClient as S, UtilityClient as U, type WriteFileRequest as W, ProcessClient as a, Sandbox as b, type CommandsResponse as c, type ContainerStub as d, type ExecuteRequest as e, type ExecuteResponse as f, getSandbox as g, type ExposePortRequest as h, type FileOperationRequest as i, type GitCheckoutRequest as j, type PingResponse as k, type RequestConfig as l, type ResponseHandler as m, type SessionRequest as n, type UnexposePortRequest as o, type ExecutionCallbacks as p };

package/dist/sandbox.d.ts

@@ -1,4 +0,0 @@
-import '@repo/shared';
-import 'cloudflare:workers';
-import '@cloudflare/containers';
-export { b as Sandbox, g as getSandbox } from './sandbox-DWQVgVTY.js';

package/dist/sandbox.js

@@ -1,13 +0,0 @@
-import {
-  Sandbox,
-  getSandbox
-} from "./chunk-SVWLTRHD.js";
-import "./chunk-JXZMAU2C.js";
-import "./chunk-Z532A7QC.js";
-import "./chunk-EKSWCBCA.js";
-import "./chunk-FE4PJSRB.js";
-export {
-  Sandbox,
-  getSandbox
-};
-//# sourceMappingURL=sandbox.js.map

package/dist/sandbox.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/security.d.ts

@@ -1,31 +0,0 @@
-/**
- * Security utilities for URL construction and input validation
- *
- * This module contains critical security functions to prevent:
- * - URL injection attacks
- * - SSRF (Server-Side Request Forgery) attacks
- * - DNS rebinding attacks
- * - Host header injection
- * - Open redirect vulnerabilities
- */
-declare class SecurityError extends Error {
-    readonly code?: string | undefined;
-    constructor(message: string, code?: string | undefined);
-}
-/**
- * Validates port numbers for sandbox services
- * Only allows non-system ports to prevent conflicts and security issues
- */
-declare function validatePort(port: number): boolean;
-/**
- * Sanitizes and validates sandbox IDs for DNS compliance and security
- * Only enforces critical requirements - allows maximum developer flexibility
- */
-declare function sanitizeSandboxId(id: string): string;
-/**
- * Validates language for code interpreter
- * Only allows supported languages
- */
-declare function validateLanguage(language: string | undefined): void;
-
-export { SecurityError, sanitizeSandboxId, validateLanguage, validatePort };

package/dist/security.js

@@ -1,13 +0,0 @@
-import {
-  SecurityError,
-  sanitizeSandboxId,
-  validateLanguage,
-  validatePort
-} from "./chunk-Z532A7QC.js";
-export {
-  SecurityError,
-  sanitizeSandboxId,
-  validateLanguage,
-  validatePort
-};
-//# sourceMappingURL=security.js.map

package/dist/security.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}