@cloudflare/sandbox 0.10.3 → 0.11.0

package/dist/{sandbox-CwcSm_60.d.ts → sandbox-B9LOT0cg.d.ts}

@@ -1200,26 +1200,6 @@ interface SessionDeleteResult {
   sessionId: string;
   timestamp: string;
 }
-interface PortExposeResult {
-  success: boolean;
-  port: number;
-  url: string;
-  timestamp: string;
-}
-interface PortListResult {
-  success: boolean;
-  ports: Array<{
-    port: number;
-    url: string;
-    status: 'active' | 'inactive';
-  }>;
-  timestamp: string;
-}
-interface PortCloseResult {
-  success: boolean;
-  port: number;
-  timestamp: string;
-}
 interface ExecutionSession {
   /** Unique session identifier */
   readonly id: string;
@@ -1571,13 +1551,6 @@ interface StartProcessRequest {
   autoCleanup?: boolean;
   origin?: 'user' | 'internal';
 }
-/**
- * Request to expose a port
- */
-interface ExposePortRequest {
-  port: number;
-  name?: string;
-}
 /**
  * Request to create a backup archive from a directory.
  * The container creates a squashfs archive at archivePath.
@@ -1715,9 +1688,6 @@ interface SandboxProcessesAPI {
   streamProcessLogs(id: string): Promise<ReadableStream<Uint8Array>>;
 }
 interface SandboxPortsAPI {
-  exposePort(port: number, sessionId: string, name?: string): Promise<PortExposeResult>;
-  getExposedPorts(sessionId: string): Promise<PortListResult>;
-  unexposePort(port: number, sessionId: string): Promise<PortCloseResult>;
   watchPort(request: PortWatchRequest): Promise<ReadableStream<Uint8Array>>;
 }
 interface SandboxGitAPI {
@@ -1837,26 +1807,61 @@ interface SandboxWatchAPI {
   checkChanges(request: CheckChangesRequest): Promise<CheckChangesResult>;
 }
 /**
- * Public-facing tunnel record.
- *
- * Today only quick tunnels (`*.trycloudflare.com`) are supported. Future
- * PRs will add named tunnels, which will carry a `name: string` field;
- * `TunnelInfo` will then become a discriminated union keyed on the
- * presence of `name`. The quick variant declares `name?: never` so the
- * narrowing works without a breaking change here.
+ * Public-facing tunnel record. Discriminated on the presence of `name`:
+ * quick tunnels (`*.trycloudflare.com`) omit it, named tunnels carry the
+ * label that was passed to `get(port, { name })`.
  */
-interface TunnelInfo {
+type TunnelInfo = QuickTunnelInfo | NamedTunnelInfo;
+interface QuickTunnelInfo {
   id: string;
   port: number;
+  /** `https://<random>.trycloudflare.com`. */
   url: string;
+  /** Hostname portion of `url`. */
   hostname: string;
   createdAt: string;
-  /** Reserved for the named-tunnel variant in a future PR. */
+  /** Absent on quick tunnels; narrows the union. */
   name?: never;
 }
+interface NamedTunnelInfo {
+  /** Cloudflare tunnel UUID (8-4-4-4-12). */
+  id: string;
+  port: number;
+  /** `https://<hostname>`. */
+  url: string;
+  /** Full hostname bound to the tunnel (without scheme). */
+  hostname: string;
+  createdAt: string;
+  /** Label originally passed via `TunnelOptions.name`. */
+  name: string;
+}
+/**
+ * Options accepted by `sandbox.tunnels.get(port, options)`. Omitting
+ * `name` (or omitting the options object) selects the zero-config quick
+ * tunnel; setting `name` selects the named-tunnel flow.
+ */
+interface TunnelOptions {
+  /**
+   * Single DNS label under the configured zone. The full hostname is
+   * `<name>.<zone-name>`. See `validateTunnelName` for the format rules.
+   */
+  name?: string;
+}
 interface SandboxTunnelsAPI {
   /** Spawn `cloudflared tunnel --url`. No credentials required. */
   runQuickTunnel(id: string, port: number): Promise<TunnelInfo>;
+  /**
+   * Spawn `cloudflared tunnel run --token <token> --url http://localhost:<port>`.
+   *
+   * The SDK is the source of truth for the hostname this tunnel binds to;
+   * the container only sees the opaque token and the local port. The
+   * returned `TunnelInfo` carries empty `url`/`hostname` fields — the SDK
+   * enriches them with the values from the Cloudflare API before handing
+   * the record to user code.
+   *
+   * The token must never be logged, persisted, or echoed back to callers.
+   */
+  runNamedTunnel(id: string, token: string, port: number): Promise<TunnelInfo>;
   /** Stop the cloudflared process for the given tunnel id. */
   destroyTunnel(id: string): Promise<{
     success: true;
@@ -2534,33 +2539,9 @@ declare class InterpreterClient extends BaseHttpClient implements SandboxInterpr
 //#endregion
 //#region src/clients/port-client.d.ts
 /**
- * Request interface for unexposing ports
+ * Client for port readiness operations.
  */
-interface UnexposePortRequest {
-  port: number;
-}
-/**
- * Client for port management and preview URL operations
- */
-declare class PortClient extends BaseHttpClient implements SandboxPortsAPI {
-  /**
-   * 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>;
+declare class PortClient extends BaseHttpClient {
   /**
    * Watch a port for readiness via SSE stream
    * @param request - Port watch configuration
@@ -2933,7 +2914,7 @@ declare class ContainerControlClient {
 //#endregion
 //#region src/tunnels/tunnels-handler.d.ts
 interface TunnelsHandler {
-  get(port: number): Promise<TunnelInfo>;
+  get(port: number, options?: TunnelOptions): Promise<TunnelInfo>;
   list(): Promise<TunnelInfo[]>;
   destroy(portOrInfo: number | TunnelInfo): Promise<void>;
 }
@@ -2958,6 +2939,7 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   private sandboxName;
   private tunnelsHandler;
   private tunnelExitHandler;
+  private destroyAllTunnels;
   private readonly controlCallback;
   private normalizeId;
   private defaultSession;
@@ -2967,6 +2949,7 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   private logger;
   private keepAliveEnabled;
   private activeMounts;
+  private currentRuntime;
   private transport;
   /**
    * True once transport has been written to storage at least once (either
@@ -2992,7 +2975,22 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   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"
@@ -3157,18 +3155,7 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   destroy(): Promise<void>;
   private doDestroy;
   onStart(): Promise<void>;
-  /**
-   * Re-expose ports on the container runtime using tokens persisted in DO
-   * storage. Called from onStart() after a container (re)start.
-   *
-   * The DO storage holds the source of truth for which ports should be
-   * exposed, which tokens authorize them, and the friendly name (if any)
-   * that the caller set when first exposing the port. If a port is already
-   * exposed on the container this is a no-op for that port. Individual port
-   * failures are logged but do not abort the overall restore — a transient
-   * failure for one port must not prevent the others from being restored.
-   */
-  private restoreExposedPorts;
+  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
@@ -3176,6 +3163,10 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * 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
@@ -3230,6 +3221,14 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * 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;
@@ -3448,11 +3447,10 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   /**
    * Expose a port and get a preview URL for accessing services running in the sandbox
    *
-   * Preview URLs survive transient container restarts: the token and any
-   * friendly name are persisted in Durable Object storage, and the port is
-   * automatically re-exposed on the container when it comes back up. Tokens
-   * are cleared only on explicit `unexposePort()` or full sandbox
-   * `destroy()`.
+   * 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
@@ -3484,11 +3482,22 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
     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" | "inactive";
+    status: "active";
   }[]>;
   /**
    * Namespaced tunnel API. Quick tunnels are zero-config preview URLs
@@ -3517,8 +3526,45 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * fields.
    */
   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;
@@ -3598,17 +3644,19 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
    * 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 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;
+  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;
+  private generatePresignedPutURL;
   /**
    * Upload a backup archive via presigned PUT URL.
    * The container curls the archive directly to R2, bypassing the DO.
@@ -3618,7 +3666,7 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   /**
    * Generate a presigned PUT URL for a single part in a multipart upload.
    */
-  private generatePresignedPartUrl;
+  private generatePresignedPartURL;
   /**
    * Upload a backup archive to R2 using parallel multipart upload.
    * Uses the S3-compatible API exclusively for create/complete/abort so that
@@ -3712,5 +3760,5 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
   private configureR2EgressOutbound;
 }
 //#endregion
-export { StartProcessRequest as $, DesktopStopResponse as A, ProcessOptions as At, ExecuteResponse as B, WaitForPortOptions as Bt, ClickOptions as C, PortListResult as Ct, DesktopStartOptions as D, ProcessKillResult as Dt, DesktopClient as E, ProcessInfoResult as Et, ScreenshotRegion as F, SandboxOptions as Ft, HttpClientOptions as G, PtyOptions as Gt, BaseApiResponse as H, isExecResult as Ht, ScreenshotResponse as I, SandboxTransport as It, SessionRequest as J, Execution as Jt, RequestConfig as K, CodeContext as Kt, ScrollDirection as L, SessionOptions as Lt, ScreenSizeResponse as M, ProcessStatus as Mt, ScreenshotBytesResponse as N, RemoteMountBucketOptions as Nt, DesktopStartResponse as O, ProcessListResult as Ot, ScreenshotOptions as P, RestoreBackupResult as Pt, ExposePortRequest as Q, TypeOptions as R, StreamOptions as Rt, WriteFileRequest as S, PortExposeResult as St, Desktop as T, ProcessCleanupResult as Tt, ContainerStub as U, isProcess as Ut, BackupClient as V, WatchOptions as Vt, ErrorResponse as W, isProcessStatus as Wt, TunnelInfo as X, RunCodeOptions as Xt, SandboxInterpreterAPI as Y, ExecutionResult as Yt, ExecuteRequest as Z, GitClient as _, ListFilesOptions as _t, CreateSessionRequest as a, CheckChangesResult as at, MkdirRequest as b, MountBucketOptions as bt, DeleteSessionResponse as c, ExecOptions as ct, ProcessClient as d, FileChunk as dt, BackupOptions as et, PortClient as f, FileMetadata as ft, GitCheckoutRequest as g, ISandbox as gt, InterpreterClient as h, GitCheckoutResult as ht, CommandsResponse as i, CheckChangesOptions as it, KeyInput as j, ProcessStartResult as jt, DesktopStatusResponse as k, ProcessLogsResult as kt, PingResponse as l, ExecResult as lt, ExecutionCallbacks as m, FileWatchSSEEvent as mt, getSandbox as n, BucketCredentials as nt, CreateSessionResponse as o, DirectoryBackup as ot, UnexposePortRequest as p, FileStreamEvent as pt, ResponseHandler as q, CreateContextOptions as qt, SandboxClient as r, BucketProvider as rt, DeleteSessionRequest as s, ExecEvent as st, Sandbox as t, BaseExecOptions as tt, UtilityClient as u, ExecutionSession as ut, FileClient as v, LocalMountBucketOptions as vt, CursorPositionResponse as w, Process as wt, ReadFileRequest as x, PortCloseResult as xt, FileOperationRequest as y, LogEvent as yt, CommandClient as z, WaitForLogResult as zt };
-//# sourceMappingURL=sandbox-CwcSm_60.d.ts.map
+export { ExecuteRequest as $, KeyInput as A, ProcessStatus as At, BackupClient as B, isExecResult as Bt, CursorPositionResponse as C, ProcessCleanupResult as Ct, DesktopStartResponse as D, ProcessLogsResult as Dt, DesktopStartOptions as E, ProcessListResult as Et, ScreenshotResponse as F, SessionOptions as Ft, RequestConfig as G, CreateContextOptions as Gt, ContainerStub as H, isProcessStatus as Ht, ScrollDirection as I, StreamOptions as It, NamedTunnelInfo as J, RunCodeOptions as Jt, ResponseHandler as K, Execution as Kt, TypeOptions as L, WaitForLogResult as Lt, ScreenshotBytesResponse as M, RestoreBackupResult as Mt, ScreenshotOptions as N, SandboxOptions as Nt, DesktopStatusResponse as O, ProcessOptions as Ot, ScreenshotRegion as P, SandboxTransport as Pt, TunnelOptions as Q, CommandClient as R, WaitForPortOptions as Rt, ClickOptions as S, Process as St, DesktopClient as T, ProcessKillResult as Tt, ErrorResponse as U, PtyOptions as Ut, BaseApiResponse as V, isProcess as Vt, HttpClientOptions as W, CodeContext as Wt, SandboxInterpreterAPI as X, QuickTunnelInfo as Y, TunnelInfo as Z, FileClient as _, ISandbox as _t, CreateSessionRequest as a, CheckChangesOptions as at, ReadFileRequest as b, LogEvent as bt, DeleteSessionResponse as c, ExecEvent as ct, ProcessClient as d, ExecutionSession as dt, StartProcessRequest as et, PortClient as f, FileChunk as ft, GitClient as g, GitCheckoutResult as gt, GitCheckoutRequest as h, FileWatchSSEEvent as ht, CommandsResponse as i, BucketProvider as it, ScreenSizeResponse as j, RemoteMountBucketOptions as jt, DesktopStopResponse as k, ProcessStartResult as kt, PingResponse as l, ExecOptions as lt, InterpreterClient as m, FileStreamEvent as mt, getSandbox as n, BaseExecOptions as nt, CreateSessionResponse as o, CheckChangesResult as ot, ExecutionCallbacks as p, FileMetadata as pt, SessionRequest as q, ExecutionResult as qt, SandboxClient as r, BucketCredentials as rt, DeleteSessionRequest as s, DirectoryBackup as st, Sandbox as t, BackupOptions as tt, UtilityClient as u, ExecResult as ut, FileOperationRequest as v, ListFilesOptions as vt, Desktop as w, ProcessInfoResult as wt, WriteFileRequest as x, MountBucketOptions as xt, MkdirRequest as y, LocalMountBucketOptions as yt, ExecuteResponse as z, WatchOptions as zt };
+//# sourceMappingURL=sandbox-B9LOT0cg.d.ts.map