@cloudflare/sandbox 0.13.0-next.633.1 → 0.13.0-next.651.1

package/dist/sandbox-D_MMqExx.d.ts

@@ -0,0 +1,1077 @@
+import { $ as RenameFileResult, A as ExecResult, B as ListFilesOptions, D as DirectoryBackup, E as DeleteFileResult, G as MountBucketOptions, J as ProcessOptions, K as MoveFileResult, N as FileEncoding, P as FileExistsResult, R as GitCheckoutResult, T as CheckChangesResult, V as ListFilesResult, W as MkdirResult, X as ReadFileResult, Z as ReadFileStreamResult, _ as SandboxWatchAPI, _t as RunCodeOptions, b as BackupOptions, c as SandboxControlCallback, ct as WriteFileResult, d as SandboxGitAPI, et as RestoreBackupResult, f as SandboxInterpreterAPI, g as SandboxUtilsAPI, gt as ExecutionResult, h as SandboxTunnelsAPI, it as StreamOptions, j as ExecutionSession, k as ExecOptions, l as SandboxExtensionsAPI, m as SandboxProcessesAPI, mt as CreateContextOptions, nt as SessionDeleteResult, o as SandboxBackupAPI, p as SandboxPortsAPI, pt as CodeContext, q as Process, rt as SessionOptions, s as SandboxCommandsAPI, st as WatchOptions, tt as SandboxOptions, u as SandboxFilesAPI, v as TunnelInfo, w as CheckChangesOptions, y as TunnelOptions, z as ISandbox } from "./rpc-types-PBUY-xXM.js";
+import { Container, ContainerProxy } from "@cloudflare/containers";
+import { RpcTarget, RpcTransport } from "capnweb";
+
+//#region ../shared/dist/logger/types.d.ts
+
+type LogComponent = 'container' | 'sandbox-do' | 'executor';
+/**
+ * Context metadata included in every log entry
+ */
+interface LogContext {
+  /**
+   * Unique trace ID for request correlation across distributed components
+   * Format: "tr_" + 16 hex chars (e.g., "tr_7f3a9b2c4e5d6f1a")
+   */
+  traceId: string;
+  /**
+   * Component that generated the log
+   */
+  component: LogComponent;
+  /**
+   * Sandbox identifier (which sandbox instance)
+   */
+  sandboxId?: string;
+  /**
+   * Session identifier (which session within sandbox)
+   */
+  sessionId?: string;
+  /**
+   * Process identifier (which background process)
+   */
+  processId?: string;
+  /**
+   * Command identifier (which command execution)
+   */
+  commandId?: string;
+  /**
+   * Duration in milliseconds
+   */
+  durationMs?: number;
+  /**
+   * Service version (from SANDBOX_VERSION env var)
+   */
+  serviceVersion?: string;
+  /**
+   * Instance identifier (hostname or container ID)
+   */
+  instanceId?: string;
+  /**
+   * Extensible for additional metadata
+   */
+  [key: string]: unknown;
+}
+/**
+ * Logger interface for structured logging
+ *
+ * All methods accept optional context that gets merged with the logger's base context.
+ */
+interface Logger {
+  /**
+   * Log debug-level message (most verbose, typically disabled in production)
+   *
+   * @param message Human-readable message
+   * @param context Optional additional context
+   */
+  debug(message: string, context?: Partial<LogContext>): void;
+  /**
+   * Log info-level message (normal operational events)
+   *
+   * @param message Human-readable message
+   * @param context Optional additional context
+   */
+  info(message: string, context?: Partial<LogContext>): void;
+  /**
+   * Log warning-level message (recoverable issues, degraded state)
+   *
+   * @param message Human-readable message
+   * @param context Optional additional context
+   */
+  warn(message: string, context?: Partial<LogContext>): void;
+  /**
+   * Log error-level message (failures, exceptions)
+   *
+   * @param message Human-readable message
+   * @param error Optional Error object to include
+   * @param context Optional additional context
+   */
+  error(message: string, error?: Error, context?: Partial<LogContext>): void;
+  /**
+   * Create a child logger with additional context
+   *
+   * The child logger inherits all context from the parent and adds new context.
+   * This is useful for adding request-specific context without passing through parameters.
+   *
+   * @param context Additional context to merge
+   * @returns New logger instance with merged context
+   *
+   * @example
+   * const logger = createLogger({ component: 'sandbox-do', traceId: 'tr_abc123' });
+   * const execLogger = logger.child({ commandId: 'cmd-456' });
+   * execLogger.info('Command started'); // Includes all context: component, traceId, commandId
+   */
+  child(context: Partial<LogContext>): Logger;
+}
+//#endregion
+//#region src/container-control/connection.d.ts
+/** Stub that can issue a WebSocket-upgrade fetch through the DO's Container base class. */
+interface ContainerFetchStub {
+  fetch(request: Request): Promise<Response>;
+}
+interface ContainerControlConnectionOptions {
+  stub: ContainerFetchStub;
+  port?: number;
+  logger?: Logger;
+  /**
+   * Total retry budget (ms) for retryable upgrade responses while the
+   * container is unavailable. Defaults to 120 000 (2 minutes). Set to 0 to
+   * disable retries.
+   */
+  retryTimeoutMs?: number;
+  /**
+   * Optional `localMain` exposed to the container side of the capnweb
+   * session. The container reaches it via
+   * `session.getRemoteMain()` and uses it for control-plane callbacks
+   * (e.g. notifying the DO when a tunnel's cloudflared process has
+   * exited). When omitted, the container sees an empty remote main.
+   */
+  localMain?: SandboxControlCallback & RpcTarget;
+  /**
+   * Invoked when an active WebSocket transitions to closed/errored.
+   * Fired at most once per successful connection from the WS event
+   * handlers in `doConnect`. Gives owners a synchronous teardown
+   * signal so recovery doesn't depend on a periodic poller running
+   * inside what may be an idle isolate.
+   *
+   * Also fired for `doConnect` failures after the deferred transport is
+   * aborted. A failed upgrade poisons the transport, so owners must discard
+   * the connection and create a fresh one for subsequent calls. Not fired for
+   * `disconnect()`.
+   */
+  onClose?: () => void;
+}
+//#endregion
+//#region src/container-control/client.d.ts
+
+interface ContainerControlClientOptions extends ContainerControlConnectionOptions {
+  /** Idle timeout before disconnecting the WebSocket (ms). Defaults to 1 000. */
+  idleDisconnectMs?: number;
+  /** Busy/idle poll interval (ms). Defaults to 1 000. */
+  busyPollIntervalMs?: number;
+  /**
+   * Renew the DO's activity timeout. Fires at the start of every RPC call
+   * and on every busy-poll tick while the session has work in flight.
+   * Mirrors what `containerFetch()` does at the top of each HTTP request.
+   */
+  onActivity?: () => void;
+  /**
+   * Fires once when the capnweb session transitions from idle to busy
+   * (an RPC call was started or a stream return is now in flight). The
+   * Sandbox DO wires this to increment the Container base class's
+   * in-flight request counter, which makes `isActivityExpired()` skip the
+   * sleepAfter comparison.
+   */
+  onSessionBusy?: () => void;
+  /**
+   * Fires once when the session transitions from busy back to idle
+   * (all RPC promises settled and all stream exports released). The
+   * Sandbox DO wires this to `inflightRequests = max(0, n-1)` and a
+   * final `renewActivityTimeout()`, matching containerFetch's finally
+   * block.
+   */
+  onSessionIdle?: () => void;
+}
+/**
+ * Sandbox control facade backed by direct capnweb RPC.
+ *
+ * All operations call the container's SandboxAPI control interface directly
+ * over capnweb, bypassing the HTTP handler/router layer entirely.
+ *
+ * Manages its own WebSocket lifecycle: a fresh `ContainerControlConnection` is
+ * created on demand and torn down after `idleDisconnectMs` of inactivity.
+ * Busy/idle detection relies on `RpcSession.getStats()` which tracks all
+ * in-flight RPC calls and stream exports — including long-lived streaming
+ * RPCs that would be invisible to a simple per-call request counter (see
+ * the file-level comment for the full rationale).
+ */
+declare class ContainerControlClient {
+  private readonly connOptions;
+  private readonly idleDisconnectMs;
+  private readonly busyPollIntervalMs;
+  private readonly logger;
+  private readonly onActivity;
+  private readonly onSessionBusy;
+  private readonly onSessionIdle;
+  private conn;
+  private idleTimer;
+  private busyPollTimer;
+  /** Tracks whether we currently believe the session is busy. */
+  private busy;
+  constructor(options: ContainerControlClientOptions);
+  /**
+   * Return the current connection, creating one when the client is disconnected.
+   * Starts the busy-poll timer the first time a connection is materialized.
+   */
+  private getConnection;
+  /**
+   * Called synchronously at the start of each RPC method invocation.
+   * Renews the DO activity timeout so the sleepAfter alarm is pushed
+   * forward before the container processes the call.
+   */
+  private renewActivity;
+  /**
+   * Sample `getStats()` and update busy/idle state. While busy, renews the
+   * activity timeout each tick so an in-flight stream keeps pushing the
+   * sleepAfter deadline forward. On the busy → idle edge, fires
+   * `onSessionIdle` and schedules the WebSocket disconnect.
+   *
+   * If the WebSocket has dropped underneath us (container crash, network
+   * blip) we tear the connection down here. `destroyConnection()` fires
+   * `onSessionIdle` if we were busy, so the DO's inflight counter doesn't
+   * stay pinned forever waiting for a peer that's never going to reply.
+   */
+  private pollBusyState;
+  private startBusyPoll;
+  private stopBusyPoll;
+  private scheduleIdleDisconnect;
+  private clearIdleTimer;
+  private destroyConnection;
+  get commands(): SandboxCommandsAPI;
+  get files(): SandboxFilesAPI;
+  get processes(): SandboxProcessesAPI;
+  get ports(): SandboxPortsAPI;
+  get git(): SandboxGitAPI;
+  get utils(): SandboxUtilsAPI;
+  get backup(): SandboxBackupAPI;
+  get watch(): SandboxWatchAPI;
+  get tunnels(): SandboxTunnelsAPI;
+  get interpreter(): SandboxInterpreterAPI;
+  get extensions(): SandboxExtensionsAPI;
+  /**
+   * Update the upgrade retry budget. Applies to the current connection
+   * (if any) and is remembered for any future connections created after the
+   * client is torn down and reconnected.
+   */
+  setRetryTimeoutMs(ms: number): void;
+  isWebSocketConnected(): boolean;
+  connect(): Promise<void>;
+  disconnect(): void;
+}
+//#endregion
+//#region src/tunnels/tunnels-handler.d.ts
+
+interface TunnelsHandler {
+  get(port: number, options?: TunnelOptions): Promise<TunnelInfo>;
+  list(): Promise<TunnelInfo[]>;
+  destroy(portOrInfo: number | TunnelInfo): Promise<void>;
+}
+//#endregion
+//#region src/sandbox.d.ts
+type SandboxConfiguration = {
+  sandboxName?: {
+    name: string;
+    normalizeId?: boolean;
+  };
+  sleepAfter?: string | number;
+  keepAlive?: boolean;
+  containerTimeouts?: NonNullable<SandboxOptions['containerTimeouts']>;
+};
+/**
+ * SDK-level ContainerProxy that directly dispatches SDK-internal mount hosts
+ * (r2.internal, s3-credential-proxy.internal) without relying on
+ * outboundHandlersRegistry lookups, which are NOT shared between the Durable
+ * Object's execution context and the ContainerProxy WorkerEntrypoint context.
+ *
+ * Users must export this class from their Worker entrypoint so the Sandbox DO
+ * can create outbound-interception fetchers that reference it.
+ */
+declare class ContainerProxy$1 extends ContainerProxy {
+  fetch(request: Request): Promise<Response>;
+}
+declare function getSandbox<T extends Sandbox<any>>(ns: DurableObjectNamespace<T>, id: string, options?: SandboxOptions): T;
+declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
+  defaultPort: number;
+  sleepAfter: string | number;
+  client: ContainerControlClient;
+  private codeInterpreter;
+  private sandboxName;
+  private tunnelsHandler;
+  private tunnelExitHandler;
+  private destroyAllTunnels;
+  private readonly controlCallback;
+  private normalizeId;
+  private defaultSession;
+  private containerGeneration;
+  private defaultSessionInit;
+  envVars: Record<string, string>;
+  private logger;
+  private keepAliveEnabled;
+  private activeMounts;
+  private mountOperationQueue;
+  private currentRuntime;
+  private backupBucket;
+  /**
+   * Serializes backup operations to prevent concurrent create/restore on the same sandbox.
+   *
+   * This is in-memory state — it resets if the Durable Object is evicted and
+   * re-instantiated (e.g. after sleep). This is acceptable because the container
+   * filesystem is also lost on eviction, so there is no archive to race on.
+   */
+  private backupInProgress;
+  /**
+   * R2 presigned URL credentials for direct container-to-R2 transfers.
+   * All four fields plus the R2 binding must be configured for backup to work.
+   */
+  private r2AccessKeyId;
+  private r2SecretAccessKey;
+  private r2AccountId;
+  private backupBucketName;
+  private backupBucketEndpoint;
+  private r2Client;
+  /**
+   * Lazily-resolved Cloudflare account id for named-tunnel provisioning.
+   * Resolved on first access via `tunnels/credentials.ts` and cached for
+   * the lifetime of this DO instance. See the credentials helper for
+   * the precedence chain.
+   */
+  private tunnelAccountIdPromise;
+  /**
+   * Lazily-resolved Cloudflare zone id for named-tunnel provisioning.
+   * Falls back to the single zone the token can see under the resolved
+   * account id when `CLOUDFLARE_ZONE_ID` is not set. Cached for the
+   * lifetime of this DO instance.
+   */
+  private tunnelZoneIdPromise;
+  /**
+   * Default container startup timeouts (conservative for production)
+   * Based on Cloudflare docs: "Containers take several minutes to provision"
+   */
+  private readonly DEFAULT_CONTAINER_TIMEOUTS;
+  /**
+   * Active container timeout configuration
+   * Can be set via options, env vars, or defaults
+   */
+  private containerTimeouts;
+  /**
+   * True once containerTimeouts has been written to storage at least once
+   * (either via setContainerTimeouts or restored on cold start). Gates the
+   * idempotency check in setContainerTimeouts so a first explicit call
+   * persists even when the requested values already equal the in-memory
+   * defaults, distinguishing "user intent recorded" from "running on
+   * env/SDK defaults".
+   */
+  private hasStoredContainerTimeouts;
+  /**
+   * Dispatch method for tunnel operations.
+   * Called by the client-side proxy created in getSandbox() to provide
+   * the `sandbox.tunnels` API without relying on RPC pipelining
+   * through property getters which is broken when using vite-plugin.
+   */
+  callTunnels(method: string, args: unknown[]): Promise<unknown>;
+  /**
+   * Compute the control-channel upgrade retry budget from current container
+   * timeouts.
+   *
+   * The budget covers the full container startup window (instance provisioning
+   * + port readiness) plus a 30s margin for the maximum single backoff delay.
+   * The 120s floor preserves the default for short timeout configurations.
+   */
+  private computeRetryTimeoutMs;
+  /**
+   * Create the single control-plane client used for all SDK operations.
+   */
+  private createClient;
+  constructor(ctx: DurableObjectState<{}>, env: Env);
+  setSandboxName(name: string, normalizeId?: boolean): Promise<void>;
+  configure(configuration: SandboxConfiguration): Promise<void>;
+  setSleepAfter(sleepAfter: string | number): Promise<void>;
+  setKeepAlive(keepAlive: boolean): Promise<void>;
+  setEnvVars(envVars: Record<string, string | undefined>): Promise<void>;
+  setContainerTimeouts(timeouts: NonNullable<SandboxOptions['containerTimeouts']>): Promise<void>;
+  private validateTimeout;
+  private getDefaultTimeouts;
+  /**
+   * Mount an S3-compatible bucket as a local directory.
+   *
+   * Requires explicit endpoint URL for production. Credentials are auto-detected from environment
+   * variables or can be provided explicitly.
+   *
+   * @param bucket - Bucket name (or R2 binding name when localBucket is true)
+   * @param mountPath - Absolute path in container to mount at
+   * @param options - Mount configuration
+   * @throws MissingCredentialsError if no credentials found in environment
+   * @throws S3FSMountError if S3FS mount command fails
+   * @throws InvalidMountConfigError if bucket name, mount path, or endpoint is invalid
+   */
+  mountBucket(bucket: string, mountPath: string, options: MountBucketOptions): Promise<void>;
+  private runMountOperation;
+  private mountBucketUnlocked;
+  /**
+   * Local dev mount: bidirectional sync via R2 binding + file/watch APIs
+   */
+  private mountBucketLocal;
+  private getR2EgressParams;
+  private validateProtectedS3fsOptions;
+  private getS3CredentialProxyParams;
+  private resolveCredentialProxyAuthStrategy;
+  /**
+   * Credential-less R2 mount: egress interception routes s3fs requests to the
+   * R2 binding. No S3 credentials are needed in the container or Worker env.
+   */
+  private mountBucketR2Egress;
+  /**
+   * Production mount: S3FS-FUSE inside the container
+   */
+  private mountBucketFuse;
+  /**
+   * Manually unmount a bucket filesystem
+   *
+   * @param mountPath - Absolute path where the bucket is mounted
+   * @throws InvalidMountConfigError if mount path doesn't exist or isn't mounted
+   */
+  unmountBucket(mountPath: string): Promise<void>;
+  private unmountBucketUnlocked;
+  /**
+   * Shared validation for mount path (absolute, not already in use).
+   */
+  private validateMountPath;
+  /**
+   * Validate mount options for remote (FUSE) mounts
+   */
+  private validateMountOptions;
+  /**
+   * Generate unique password file path for s3fs credentials
+   */
+  private generatePasswordFilePath;
+  /**
+   * Generate unique ahbe_conf file path for s3fs additional header config
+   */
+  private generateS3FSAdditionalHeaderFilePath;
+  /**
+   * Create s3fs ahbe_conf file that suppresses the Expect: 100-continue header.
+   * Restricted to 0600 so s3fs will accept it (same requirement as passwd files).
+   */
+  private createDisableExpectHeaderFile;
+  /**
+   * Create password file with s3fs credentials
+   * Format: bucket:accessKeyId:secretAccessKey
+   */
+  private createPasswordFile;
+  /**
+   * Delete password file
+   */
+  private deletePasswordFile;
+  private deleteAdditionalHeaderFile;
+  /**
+   * Execute S3FS mount command
+   */
+  private executeS3FSMount;
+  private unmountTrackedFuseMount;
+  /**
+   * In-flight `destroy()` promise. While set, concurrent callers coalesce
+   * onto the same teardown instead of triggering a second one. Cleared when
+   * the underlying work settles, so a later call that genuinely needs to
+   * recreate a destroyed sandbox still runs.
+   *
+   * If the underlying teardown hangs (e.g. `super.destroy()` never resolves
+   * because the Containers control plane is unresponsive), every coalesced
+   * caller hangs on the same promise until the Durable Object is evicted.
+   * This is deliberate: a second concurrent teardown would not make a stuck
+   * control plane unstuck, and spawning one would defeat the point of
+   * coalescing. Callers that need bounded waits must apply their own
+   * timeout around `destroy()`.
+   */
+  private inflightDestroy;
+  /**
+   * Cleanup and destroy the sandbox container.
+   *
+   * Concurrent calls coalesce: if a previous `destroy()` is still in flight,
+   * subsequent calls await the same underlying work instead of starting a
+   * second teardown. A canonical `sandbox.destroy.coalesced` event is logged
+   * per coalesced call so repeated destroy traffic is observable.
+   */
+  destroy(): Promise<void>;
+  private doDestroy;
+  onStart(): Promise<void>;
+  stop(signal?: Parameters<Container<Env>['stop']>[0]): Promise<void>;
+  /**
+   * Read the `portTokens` map from DO storage, normalizing the legacy
+   * string-valued format (just a token) to the current object format
+   * ({ token, name? }). The legacy format predates port-name persistence and
+   * can appear on any DO whose storage was written before that change.
+   */
+  private readPortTokens;
+  private readActivePreviewPorts;
+  private writeActivePreviewPorts;
+  private readPreviewState;
+  private clearActivePreviewPorts;
+  /**
+   * Check if the container version matches the SDK version
+   * Logs a warning if there's a mismatch
+   */
+  private checkVersionCompatibility;
+  onStop(): Promise<void>;
+  onError(error: unknown): void;
+  /**
+   * Override Container.containerFetch to use production-friendly timeouts
+   * Automatically starts container with longer timeouts if not running
+   */
+  containerFetch(requestOrUrl: Request | string | URL, portOrInit?: number | RequestInit, portParam?: number): Promise<Response>;
+  /**
+   * Helper: Check if error is "no container instance available"
+   * This indicates the container VM is still being provisioned.
+   */
+  private isNoInstanceError;
+  /**
+   * Helper: Check if error is a transient startup error that should trigger retry
+   *
+   * These errors occur during normal container startup and are recoverable:
+   * - Port not yet mapped (container starting, app not listening yet)
+   * - Connection refused (port mapped but app not ready)
+   * - Timeouts during startup (recoverable with retry)
+   * - Network transients (temporary connectivity issues)
+   *
+   * Errors NOT included (permanent failures):
+   * - "no such image" - missing Docker image
+   * - "container already exists" - name collision
+   * - Configuration errors
+   */
+  private isTransientStartupError;
+  /**
+   * Helper: Check if error is a permanent startup failure that will never recover
+   *
+   * These errors indicate resource exhaustion, misconfiguration, or missing images.
+   * Retrying will never succeed, so the SDK should fail fast with HTTP 500.
+   *
+   * Error sources (traced from platform internals):
+   *   - Container runtime: OOM, PID limit
+   *   - Scheduling/provisioning: no matching app, no namespace configured
+   *   - workerd container-client.c++: no such image
+   *   - @cloudflare/containers: did not call start
+   */
+  private isPermanentStartupError;
+  /**
+   * Helper: Parse containerFetch arguments (supports multiple signatures)
+   */
+  private parseContainerFetchArgs;
+  /**
+   * Override onActivityExpired to prevent automatic shutdown when keepAlive is enabled
+   * When keepAlive is disabled, calls parent implementation which stops the container
+   */
+  onActivityExpired(): Promise<void>;
+  private isPreviewProxyRequest;
+  private invalidPreviewTokenResponse;
+  private stalePreviewURLResponse;
+  private getPreviewForwardingContainer;
+  private beginPreviewForward;
+  private fetchPreviewIfRunning;
+  private buildPreviewProxyRequest;
+  private proxyPreviewRequest;
+  fetch(request: Request): Promise<Response>;
+  wsConnect(request: Request, port: number): Promise<Response>;
+  private determinePort;
+  /**
+   * Return the default session id, lazily creating the container session
+   * on first use. Called by every public method that needs a session.
+   * Concurrent callers that target the same sessionId share one
+   * in-flight initialization promise.
+   */
+  private ensureDefaultSession;
+  private getOrInitializeDefaultSession;
+  private isDefaultSessionInitContainerRestart;
+  private initializeDefaultSession;
+  /**
+   * Persist the container's placement ID in DO storage.
+   *
+   * Called from the session-create handshake so subsequent reads via
+   * `getContainerPlacementId()` do not require a round-trip to the container. The value
+   * is overwritten on every handshake so that container replacements (which
+   * assign a new placement ID) are reflected on the next session-create.
+   *
+   * A value of `undefined` means the handshake response omitted the field
+   * (older container, unexpected error shape) and the stored value is left
+   * untouched. `null` means the env var is not set in the container and is
+   * stored as-is so callers can distinguish "observed and absent" from "not
+   * yet observed."
+   */
+  private capturePlacementId;
+  private resolveExecution;
+  private validateExplicitSessionId;
+  private serializeExecutionContext;
+  private getPublicExecutionSessionId;
+  /**
+   * Resolves the session ID to annotate returned Process objects.
+   *
+   * Unlike `resolveExecution`, this is synchronous and never creates a
+   * session. When the default session hasn't been established yet, it returns
+   * `undefined` rather than triggering session creation. The resolved value is
+   * only used to populate `Process.sessionId` on the returned object — it is
+   * never sent to the container API.
+   */
+  private getProcessSessionBinding;
+  private resolveExecutionEnv;
+  private buildExecutionRequestOptions;
+  exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+  execWithSessionToken(command: string, sessionId: string, options?: ExecOptions): Promise<ExecResult>;
+  /**
+   * Execute an infrastructure command (backup, mount, env setup, etc.)
+   * tagged with origin: 'internal' so logging demotes it to debug level.
+   */
+  private execInternal;
+  /**
+   * 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;
+  /**
+   * Wait for a log pattern to appear in process output
+   */
+  private waitForLogPattern;
+  /**
+   * Wait for a port to become available (for process readiness checking)
+   */
+  private waitForPortReady;
+  /**
+   * Wait for a process to exit
+   * Returns the exit code
+   */
+  private waitForProcessExit;
+  /**
+   * Match a pattern against text
+   */
+  private matchPattern;
+  /**
+   * Convert a log pattern to a human-readable string
+   */
+  private conditionToString;
+  /**
+   * Create a ProcessReadyTimeoutError
+   */
+  private createReadyTimeoutError;
+  /**
+   * Create a ProcessExitedBeforeReadyError
+   */
+  private createExitedBeforeReadyError;
+  startProcess(command: string, options?: ProcessOptions, sessionId?: string): Promise<Process>;
+  /**
+   * Start background streaming for process callbacks
+   * Opens SSE stream to container and routes events to callbacks
+   */
+  private startProcessCallbackStream;
+  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>>;
+  execStreamWithSessionToken(command: string, sessionId: string, options?: StreamOptions): Promise<ReadableStream<Uint8Array>>;
+  /**
+   * Internal session-aware execStream implementation
+   */
+  private execStreamWithSession;
+  /**
+   * Stream logs from a background process as a ReadableStream.
+   */
+  streamProcessLogs(processId: string, options?: {
+    signal?: AbortSignal;
+  }): Promise<ReadableStream<Uint8Array>>;
+  gitCheckout(repoUrl: string, options?: {
+    branch?: string;
+    targetDir?: string;
+    sessionId?: string;
+    /** Clone depth for shallow clones (e.g., 1 for latest commit only) */
+    depth?: number;
+    /** Maximum wall-clock time for the git clone subprocess in milliseconds */
+    cloneTimeoutMs?: number;
+  }): Promise<GitCheckoutResult>;
+  mkdir(path: string, options?: {
+    recursive?: boolean;
+    sessionId?: string;
+  }): Promise<MkdirResult>;
+  writeFile(path: string, content: string | ReadableStream<Uint8Array>, options?: {
+    encoding?: string;
+    sessionId?: string;
+  }): Promise<{
+    success: boolean;
+    path: string;
+    bytesWritten: number;
+    timestamp: string;
+  } | WriteFileResult>;
+  deleteFile(path: string, sessionId?: string): Promise<DeleteFileResult>;
+  renameFile(oldPath: string, newPath: string, sessionId?: string): Promise<RenameFileResult>;
+  moveFile(sourcePath: string, destinationPath: string, sessionId?: string): Promise<MoveFileResult>;
+  /**
+   * Read a file from the sandbox.
+   *
+   * @param encoding - How to encode the returned content:
+   *   - `undefined` (default): auto-detect from MIME type (text → UTF-8 string, binary → base64 string)
+   *   - `'utf-8'` / `'utf8'`: always return as UTF-8 string
+   *   - `'base64'`: always return as base64-encoded string
+   *   - `'none'`: return a result whose `content` is a raw binary `ReadableStream<Uint8Array>`
+   *              with no encoding overhead.
+   */
+  readFile(path: string, options: {
+    encoding: 'none';
+    sessionId?: string;
+  }): Promise<ReadFileStreamResult>;
+  readFile(path: string, options?: {
+    encoding?: Exclude<FileEncoding, 'none'>;
+    sessionId?: string;
+  }): Promise<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?: ListFilesOptions): Promise<ListFilesResult>;
+  exists(path: string, sessionId?: string): Promise<FileExistsResult>;
+  /**
+   * Watch a directory for file system changes using native inotify.
+   *
+   * The returned promise resolves only after the watcher is established on the
+   * filesystem, so callers can immediately perform actions that depend on the
+   * watch being active. The returned stream contains the full event sequence
+   * starting with the `watching` event.
+   *
+   * Consume the stream with `parseSSEStream<FileWatchSSEEvent>(stream)`.
+   *
+   * @param path - Path to watch (absolute or relative to /workspace)
+   * @param options - Watch options
+   */
+  watch(path: string, options?: WatchOptions): Promise<ReadableStream<Uint8Array>>;
+  /**
+   * Check whether a path changed while this caller was disconnected.
+   *
+   * Pass the `version` returned from a prior call in `options.since` to learn
+   * whether the path is unchanged, changed, or needs a full resync because the
+   * retained change state was reset.
+   *
+   * @param path - Path to check (absolute or relative to /workspace)
+   * @param options - Change-check options
+   */
+  checkChanges(path: string, options?: CheckChangesOptions): Promise<CheckChangesResult>;
+  /**
+   * Expose a port and get a preview URL for accessing services running in the sandbox
+   *
+   * Preview URL authorization survives transient container restarts, but
+   * forwarding is active only for the runtime where `exposePort()` was last
+   * called. Call `exposePort()` again after a restart to reactivate an
+   * existing URL for the current runtime.
+   *
+   * @param port - Port number to expose (1024-65535)
+   * @param options - Configuration options
+   * @param options.hostname - Your Worker's domain name (required for preview URL construction)
+   * @param options.name - Optional friendly name for the port
+   * @param options.token - Optional custom token for the preview URL (1-16 characters: lowercase letters, numbers, underscores)
+   *                       If not provided, a random 16-character token will be generated automatically
+   * @returns Preview URL information including the full URL, port number, and optional name
+   *
+   * @example
+   * // With auto-generated token
+   * const { url } = await sandbox.exposePort(8080, { hostname: 'example.com' });
+   * // url: https://8080-sandbox-id-abc123random4567.example.com
+   *
+   * @example
+   * // With custom token for stable URLs across deployments
+   * const { url } = await sandbox.exposePort(8080, {
+   *   hostname: 'example.com',
+   *   token: 'my_token_v1'
+   * });
+   * // url: https://8080-sandbox-id-my_token_v1.example.com
+   */
+  exposePort(port: number, options: {
+    name?: string;
+    hostname: string;
+    token?: string;
+  }): Promise<{
+    url: string;
+    port: number;
+    name: string | undefined;
+  }>;
+  /**
+   * Revoke preview URL authorization and current-runtime activation for a port.
+   *
+   * Revocation is idempotent: calling this for a port with no preview state is
+   * still successful. The operation clears Durable Object-owned preview state
+   * only and does not contact, probe, wake, or clean up the container runtime.
+   */
+  unexposePort(port: number): Promise<void>;
+  /**
+   * Returns preview URLs that are currently forwardable in the active runtime.
+   * Durable authorization without current-runtime activation is omitted.
+   */
+  getExposedPorts(hostname: string): Promise<{
+    url: string;
+    port: number;
+    status: "active";
+  }[]>;
+  /**
+   * Namespaced tunnel API. Quick tunnels are zero-config preview URLs
+   * backed by Cloudflare's trycloudflare service. Named tunnels bind a
+   * stable hostname under the configured Cloudflare zone.
+   *
+   * - `tunnels.get(port)` — idempotent. Returns the cached tunnel for
+   *   `port` if one exists in DO storage, otherwise spawns a fresh
+   *   cloudflared process and persists the record.
+   * - `tunnels.list()` — records currently known to this sandbox, from
+   *   DO storage.
+   * - `tunnels.destroy(portOrInfo)` — tear down by port number or by
+   *   the record returned from `get()`.
+   *
+   * Container restarts drop quick-tunnel records because their
+   * `*.trycloudflare.com` URLs are tied to the dead cloudflared process.
+   * Named-tunnel records stay in storage and are marked for respawn so the
+   * next `get(port, { name })` call reuses the Cloudflare tunnel and DNS
+   * record while starting a fresh cloudflared process.
+   */
+  get tunnels(): TunnelsHandler;
+  /**
+   * Lazily construct both the public tunnels handler and its sibling
+   * exit-handler callback. Called from the `tunnels` getter on first
+   * access.
+   */
+  private ensureTunnelsBuilt;
+  /**
+   * Resolve the Cloudflare account id used for named-tunnel provisioning.
+   *
+   * Memoised for the lifetime of this DO instance. The first call may hit
+   * `GET /user/tokens/verify` to derive the account id from the configured
+   * `CLOUDFLARE_API_TOKEN`; subsequent calls return the cached promise.
+   *
+   * Only successful resolutions are cached: a rejected lookup clears the
+   * slot so the next caller retries. Otherwise a transient failure on
+   * first use would permanently poison every later named-tunnel `get()`
+   * on this DO instance.
+   */
+  private getTunnelAccountId;
+  /**
+   * Resolve the Cloudflare zone id used for named-tunnel provisioning.
+   *
+   * Memoised for the lifetime of this DO instance. Falls back to the
+   * single zone the token can see under `accountId` via `GET /zones`
+   * when `CLOUDFLARE_ZONE_ID` is not set. Failed lookups clear the cache
+   * so the next caller retries — see `getTunnelAccountId` for the
+   * rationale.
+   */
+  private getTunnelZoneId;
+  /**
+   * Returns whether a port is currently preview-forwardable.
+   * This checks Durable Object-owned auth and runtime activation without
+   * contacting or waking the container.
+   */
+  isPortExposed(port: number): Promise<boolean>;
+  /**
+   * Checks durable preview URL authorization for a port/token pair.
+   *
+   * This does not check whether the port is activated for the current runtime
+   * and is not sufficient to decide whether preview traffic may forward.
+   */
+  validatePortToken(port: number, token: string): Promise<boolean>;
+  private validatePreviewURLForRuntime;
+  private getCurrentPreviewPorts;
+  private previewTokensMatch;
+  private validateCustomToken;
+  private generatePortToken;
+  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>;
+  /**
+   * Delete an execution session
+   * Cleans up session resources and removes it from the container
+   * Note: Cannot delete the default session. To reset the default session,
+   * use sandbox.destroy() to terminate the entire sandbox.
+   *
+   * @param sessionId - The ID of the session to delete
+   * @returns Result with success status, sessionId, and timestamp
+   * @throws Error if attempting to delete the default session
+   */
+  deleteSession(sessionId: string): Promise<SessionDeleteResult>;
+  /**
+   * Get the Cloudflare placement ID observed for the underlying container.
+   *
+   * The placement ID is captured during the first session-create handshake
+   * after a container start and stored in Durable Object storage, so this
+   * method returns the cached value without contacting the container. A new
+   * placement ID is captured on each subsequent session-create handshake,
+   * which occurs whenever the container has been replaced.
+   *
+   * Returns `null` when a handshake has completed but the container's
+   * `CLOUDFLARE_PLACEMENT_ID` environment variable is not set (for example,
+   * in local development).
+   *
+   * Returns `undefined` when no handshake has been observed yet on this
+   * sandbox. Call any method that triggers session creation (such as
+   * `exec()`) to populate the value.
+   */
+  getContainerPlacementId(): Promise<string | null | undefined>;
+  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>;
+  /** UUID v4 format validator for backup IDs */
+  private static readonly UUID_REGEX;
+  /**
+   * Validate that a directory path is safe for backup operations.
+   * Rejects empty, relative, traversal, null-byte, and unsupported-root paths.
+   */
+  private static validateBackupDir;
+  /**
+   * Returns the R2 bucket or throws if backup is not configured.
+   */
+  private requireBackupBucket;
+  private normalizeBackupExcludes;
+  private resolveBackupCompression;
+  private static readonly PRESIGNED_URL_EXPIRY_SECONDS;
+  /**
+   * Create a unique, dedicated session for a single backup operation.
+   * Each call produces a fresh session ID so concurrent or sequential
+   * operations never share shell state. Callers must destroy the session
+   * in a finally block via `client.utils.deleteSession()`.
+   */
+  private ensureBackupSession;
+  /**
+   * Returns validated presigned URL configuration or throws if not configured.
+   * All credential fields plus the R2 binding are required for backup to work.
+   */
+  private requirePresignedURLSupport;
+  private getBackupBucketEndpoint;
+  private getBackupObjectURL;
+  /**
+   * Generate a presigned GET URL for downloading an object from R2.
+   * The container can curl this URL directly without credentials.
+   */
+  private generatePresignedGetURL;
+  /**
+   * Generate a presigned PUT URL for uploading an object to R2.
+   * The container can curl PUT to this URL directly without credentials.
+   */
+  private generatePresignedPutURL;
+  /**
+   * Upload a backup archive via presigned PUT URL.
+   * The container curls the archive directly to R2, bypassing the DO.
+   * ~24 MB/s throughput vs ~0.6 MB/s for base64 readFile.
+   */
+  private uploadBackupPresigned;
+  /**
+   * Generate a presigned PUT URL for a single part in a multipart upload.
+   */
+  private generatePresignedPartURL;
+  /**
+   * Upload a backup archive to R2 using parallel multipart upload.
+   * Uses the S3-compatible API exclusively for create/complete/abort so that
+   * the uploadId is in the same namespace as the presigned part PUT URLs.
+   */
+  private uploadBackupMultipart;
+  /**
+   * Download a backup archive from R2 via presigned GET URL.
+   * For archives >= BACKUP_DOWNLOAD_PARALLEL_MIN_SIZE, uses BACKUP_DOWNLOAD_PARALLEL_PARTS
+   * concurrent curl processes (each downloading a byte-range) to maximise both
+   * network and disk-write throughput. Parts are written into a pre-sized file
+   * with dd using byte offsets, then atomically moved to the final path.
+   */
+  private downloadBackupParallel;
+  /**
+   * Serialize backup operations on this sandbox instance.
+   * Concurrent backup/restore calls are queued so the multi-step
+   * create-archive → read → upload (or mount → extract) flow
+   * is not interleaved with another backup operation on the same directory.
+   */
+  private enqueueBackupOp;
+  /**
+   * Create a backup of a directory and upload it to R2.
+   *
+   * Flow:
+   *   1. Container creates squashfs archive from the directory
+   *   2. Container uploads the archive directly to R2 via presigned URL
+   *   3. DO writes metadata to R2
+   *   4. Container cleans up the local archive
+   *
+   * The returned DirectoryBackup handle is serializable. Store it anywhere
+   * (KV, D1, DO storage) and pass it to restoreBackup() later.
+   *
+   * Concurrent backup/restore calls on the same sandbox are serialized.
+   *
+   * Partially-written files in the target directory may not be captured
+   * consistently. Completed writes are captured.
+   *
+   * NOTE: Expired backups are not automatically deleted from R2. Configure
+   * R2 lifecycle rules on the BACKUP_BUCKET to garbage-collect objects
+   * under the `backups/` prefix after the desired retention period.
+   */
+  createBackup(options: BackupOptions): Promise<DirectoryBackup>;
+  private doCreateBackup;
+  /**
+   * Local-dev implementation of createBackup.
+   * Uses the R2 binding directly instead of presigned URLs.
+   * Archive format is identical to production (squashfs + meta.json).
+   */
+  private doCreateBackupLocal;
+  /**
+   * Restore a backup from R2 into a directory.
+   *
+   * **Production flow** (`localBucket` not set):
+   *   1. DO reads metadata from R2 and checks TTL
+   *   2. Container mounts the backup archive from R2 via s3fs
+   *   3. Container mounts the squashfs archive with FUSE overlayfs
+   *
+   * The target directory becomes an overlay mount with the backup as a
+   * read-only lower layer and a writable upper layer for copy-on-write.
+   * Any processes writing to the directory should be stopped first.
+   *
+   * **Mount Lifecycle**: The FUSE overlay mount persists only while the
+   * container is running. When the sandbox sleeps or the container restarts,
+   * the mount is lost and the directory becomes empty. Re-restore from the
+   * backup handle to recover. This is an ephemeral restore, not a persistent
+   * extraction.
+   *
+   * **Local-dev flow** (`localBucket: true` on the originating `createBackup` call):
+   *   1. DO reads metadata and checks TTL via R2 binding
+   *   2. DO downloads the archive from R2 and writes it to the container
+   *   3. Container extracts the archive with `unsquashfs` (no FUSE needed)
+   *
+   * The backup is restored into `backup.dir`. This may differ from the
+   * directory that was originally backed up, allowing cross-directory restore.
+   *
+   * Overlapping backups are independent: restoring a parent directory
+   * overwrites everything inside it, including subdirectories that were
+   * backed up separately. When restoring both, restore the parent first.
+   *
+   * Concurrent backup/restore calls on the same sandbox are serialized.
+   */
+  restoreBackup(backup: DirectoryBackup): Promise<RestoreBackupResult>;
+  private doRestoreBackup;
+  /**
+   * Local-dev implementation of restoreBackup.
+   * Uses the R2 binding directly instead of presigned URLs, and
+   * unsquashfs for extraction instead of squashfuse + fuse-overlayfs.
+   */
+  private doRestoreBackupLocal;
+  private configureR2EgressOutbound;
+  private configureS3CredentialProxyOutbound;
+}
+//#endregion
+export { Sandbox as n, getSandbox as r, ContainerProxy$1 as t };
+//# sourceMappingURL=sandbox-D_MMqExx.d.ts.map