@cloudflare/sandbox 0.0.0-02ee8fe

package/dist/sandbox.js

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

package/dist/sandbox.js.map

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

package/dist/security.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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

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

package/dist/security.js.map

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

package/dist/sse-parser.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Server-Sent Events (SSE) parser for streaming responses
+ * Converts ReadableStream<Uint8Array> to typed AsyncIterable<T>
+ */
+/**
+ * Parse a ReadableStream of SSE events into typed AsyncIterable
+ * @param stream - The ReadableStream from fetch response
+ * @param signal - Optional AbortSignal for cancellation
+ */
+declare function parseSSEStream<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncIterable<T>;
+/**
+ * Helper to convert a Response with SSE stream directly to AsyncIterable
+ * @param response - Response object with SSE stream
+ * @param signal - Optional AbortSignal for cancellation
+ */
+declare function responseToAsyncIterable<T>(response: Response, signal?: AbortSignal): AsyncIterable<T>;
+/**
+ * Create an SSE-formatted ReadableStream from an AsyncIterable
+ * (Useful for Worker endpoints that need to forward AsyncIterable as SSE)
+ * @param events - AsyncIterable of events
+ * @param options - Stream options
+ */
+declare function asyncIterableToSSEStream<T>(events: AsyncIterable<T>, options?: {
+    signal?: AbortSignal;
+    serialize?: (event: T) => string;
+}): ReadableStream<Uint8Array>;
+
+export { asyncIterableToSSEStream, parseSSEStream, responseToAsyncIterable };

package/dist/sse-parser.js

@@ -0,0 +1,11 @@
+import {
+  asyncIterableToSSEStream,
+  parseSSEStream,
+  responseToAsyncIterable
+} from "./chunk-EKSWCBCA.js";
+export {
+  asyncIterableToSSEStream,
+  parseSSEStream,
+  responseToAsyncIterable
+};
+//# sourceMappingURL=sse-parser.js.map

package/dist/sse-parser.js.map

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

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * SDK version - automatically synchronized with package.json by Changesets
+ * This file is auto-updated by .github/changeset-version.ts during releases
+ * DO NOT EDIT MANUALLY - Changes will be overwritten on the next version bump
+ */
+declare const SDK_VERSION = "0.4.12";
+
+export { SDK_VERSION };

package/dist/version.js

@@ -0,0 +1,7 @@
+import {
+  SDK_VERSION
+} from "./chunk-UJ3TV4M6.js";
+export {
+  SDK_VERSION
+};
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

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

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@cloudflare/sandbox",
+  "version": "0.0.0-02ee8fe",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cloudflare/sandbox-sdk"
+  },
+  "description": "A sandboxed environment for running commands",
+  "dependencies": {
+    "@cloudflare/containers": "^0.0.29"
+  },
+  "devDependencies": {
+    "@repo/shared": "^0.0.0"
+  },
+  "tags": [
+    "sandbox",
+    "codegen",
+    "containers",
+    "cloudflare",
+    "durable objects"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsup src/*.ts --outDir dist --dts --sourcemap --format esm",
+    "check": "biome check && npm run typecheck",
+    "fix": "biome check --fix && npm run typecheck",
+    "typecheck": "tsc --noEmit",
+    "docker:local": "cd ../.. && docker build -f packages/sandbox/Dockerfile --build-arg SANDBOX_VERSION=$npm_package_version -t cloudflare/sandbox-test:$npm_package_version .",
+    "docker:publish": "cd ../.. && docker buildx build --platform linux/amd64,linux/arm64 -f packages/sandbox/Dockerfile --build-arg SANDBOX_VERSION=$npm_package_version -t cloudflare/sandbox:$npm_package_version --push .",
+    "docker:publish:beta": "cd ../.. && docker buildx build --platform linux/amd64,linux/arm64 -f packages/sandbox/Dockerfile --build-arg SANDBOX_VERSION=$npm_package_version -t cloudflare/sandbox:$npm_package_version-beta --push .",
+    "test": "vitest run --config vitest.config.ts \"$@\"",
+    "test:e2e": "cd ../.. && vitest run --config vitest.e2e.config.ts \"$@\""
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module"
+}

package/src/clients/base-client.ts

@@ -0,0 +1,280 @@
+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;
+    }
+  }
+}