@cloudflare/sandbox 0.8.10 → 0.8.11

package/dist/bridge/index.d.ts

@@ -0,0 +1,187 @@
+import { DurableObject } from "cloudflare:workers";
+
+//#region src/bridge/types.d.ts
+
+/**
+ * Wire types and configuration types for the Cloudflare Sandbox Bridge.
+ *
+ * These types define the JSON payloads exchanged between HTTP clients
+ * (e.g. the Python `CloudflareSandboxClient`) and the bridge worker.
+ */
+/**
+ * Configuration options for the bridge() factory.
+ */
+interface BridgeConfig {
+  /**
+   * Override the default binding names used to look up Durable Objects.
+   *
+   * @default { sandbox: "Sandbox", warmPool: "WarmPool" }
+   */
+  bindings?: {
+    /** Name of the Sandbox Durable Object binding. @default "Sandbox" */
+    sandbox?: string;
+    /** Name of the WarmPool Durable Object binding. @default "WarmPool" */
+    warmPool?: string;
+  };
+  /**
+   * URL prefix for all bridge API routes.
+   *
+   * @default "/v1"
+   */
+  apiRoutePrefix?: string;
+  /**
+   * Path for the health-check endpoint.
+   *
+   * @default "/health"
+   */
+  healthRoute?: string;
+}
+/**
+ * The user-provided worker handlers that bridge() wraps.
+ *
+ * The bridge wraps `fetch` and `scheduled` with its own logic;
+ * all other properties are passed through unchanged.
+ */
+interface WorkerHandlers {
+  fetch?(request: Request, env: any, ctx: ExecutionContext): Response | Promise<Response>;
+  scheduled?(controller: ScheduledController, env: any, ctx: ExecutionContext): void | Promise<void>;
+  [key: string]: unknown;
+}
+/**
+ * Minimum environment shape required by the bridge.
+ * The actual bindings are looked up dynamically by name.
+ */
+interface BridgeEnv {
+  SANDBOX_API_KEY?: string;
+  WARM_POOL_TARGET?: string;
+  WARM_POOL_REFRESH_INTERVAL?: string;
+  [key: string]: unknown;
+}
+//#endregion
+//#region src/bridge/helpers.d.ts
+/**
+ * Shell-quote a single argv token so it is safe to embed in a sh command
+ * string.  Tokens that contain only safe characters are returned unchanged
+ * for readability.  All others are wrapped in ANSI-C $'...' quoting which
+ * can represent newlines, tabs, and other control characters as escape
+ * sequences — unlike plain single quotes which pass content literally and
+ * break when the value contains a real newline.
+ */
+declare function shellQuote(arg: string): string;
+/**
+ * POSIX-normalise a path (resolve `.` / `..` segments) and verify it lives
+ * under /workspace.  Returns the resolved absolute path on success, or null
+ * if the path escapes the workspace.
+ */
+declare function resolveWorkspacePath(userPath: string): string | null;
+//#endregion
+//#region src/bridge/warm-pool.d.ts
+interface WarmPoolConfig {
+  /** Target number of warm (unassigned) containers to maintain. @default 0 */
+  warmTarget?: number;
+  /** How often to check and replenish warm containers (ms). @default 10000 */
+  refreshInterval?: number;
+}
+interface PoolStats {
+  /** Number of warm (unassigned) containers ready for use */
+  warm: number;
+  /** Number of containers assigned to sandbox IDs */
+  assigned: number;
+  /** Total containers tracked by the pool */
+  total: number;
+  /** Current pool configuration */
+  config: Required<WarmPoolConfig>;
+  /** Inferred max_instances limit, or null if not yet known */
+  maxInstances: number | null;
+}
+/**
+ * The WarmPool expects an environment with a `Sandbox` Durable Object binding.
+ * This interface describes the minimum shape; the actual binding name is
+ * configurable via the bridge, but defaults to "Sandbox".
+ */
+interface WarmPoolEnv {
+  Sandbox: DurableObjectNamespace;
+  [key: string]: unknown;
+}
+declare class WarmPool extends DurableObject<WarmPoolEnv> {
+  private config;
+  /** Container UUIDs that are warm and available for assignment */
+  private warmContainers;
+  /** Maps caller-provided sandbox IDs to container UUIDs (1:1, no sharing) */
+  private assignments;
+  /** Containers currently starting — excluded from health checks */
+  private startingContainers;
+  /** Inferred max_instances limit learned from Cloudflare errors, or null */
+  private knownMaxInstances;
+  private capacityExhausted;
+  private initialized;
+  /**
+   * Get a container UUID for the given sandbox ID.
+   * - If this ID already has an assigned container that's still running, return it.
+   * - Otherwise assign a warm container (or start a new one).
+   */
+  getContainer(sandboxId: string): Promise<string>;
+  /**
+   * Look up an existing container assignment without allocating.
+   * Returns the container UUID if the sandbox ID has an active assignment, null otherwise.
+   * Used by DELETE to avoid starting a container just to destroy it.
+   */
+  lookupContainer(sandboxId: string): Promise<string | null>;
+  /**
+   * Report that a container has stopped — removes it from tracking.
+   */
+  reportStopped(containerUUID: string): Promise<void>;
+  /**
+   * Get current pool statistics.
+   */
+  getStats(): Promise<PoolStats>;
+  /**
+   * Update pool configuration. Idempotent — called on every request to keep
+   * config in sync with wrangler vars across deploys.
+   */
+  configure(config: WarmPoolConfig): Promise<void>;
+  /**
+   * Shutdown all pre-warmed (unassigned) containers.
+   * Does not affect containers that are assigned to sandbox IDs.
+   */
+  shutdownPrewarmed(): Promise<void>;
+  alarm(): Promise<void>;
+  private init;
+  private persist;
+  private scheduleRefresh;
+  private startContainer;
+  private isContainerRunning;
+  private checkContainerHealth;
+  /**
+   * Renew activity timeout on all warm containers to prevent them from sleeping.
+   */
+  private keepWarmContainersAlive;
+  /**
+   * Scale the warm pool towards warmTarget, respecting inferred max_instances.
+   */
+  private adjustPool;
+  private removeContainer;
+  private remainingCapacity;
+  private isMaxInstancesError;
+  private recordCapacityLimit;
+  private throwCapacityError;
+  private getSandboxStub;
+}
+//#endregion
+//#region src/bridge/index.d.ts
+/**
+ * Create a Worker export that wraps user handlers with bridge functionality.
+ *
+ * The bridge:
+ * 1. Checks that required Durable Object bindings exist (logs errors if missing).
+ * 2. Wraps `fetch()` to serve bridge API routes first, then falls through to the user handler.
+ * 3. Wraps `scheduled()` to prime the warm pool, then calls the user handler.
+ * 4. Passes through all other properties unchanged.
+ *
+ * @param worker - The user's worker handlers (fetch, scheduled, and any others).
+ * @param config - Optional configuration for binding names and route paths.
+ */
+declare function bridge(worker: WorkerHandlers, config?: BridgeConfig): ExportedHandler<BridgeEnv>;
+//#endregion
+export { type BridgeConfig, type BridgeEnv, type PoolStats, WarmPool, type WarmPoolConfig, type WorkerHandlers, bridge, resolveWorkspacePath, shellQuote };
+//# sourceMappingURL=index.d.ts.map

package/dist/bridge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/bridge/types.ts","../../src/bridge/helpers.ts","../../src/bridge/warm-pool.ts","../../src/bridge/index.ts"],"sourcesContent":[],"mappings":";;;;;;;AAgBA;AAgCA;;;;;AAKgB,UArCC,YAAA,CAqCD;EAEA;;;;AAehB;;;;ICEgB;IAyBA,QAAA,CAAA,EAAA,MAAA;;;;AC7EhB;AAOA;AAWC;EA6CY,cAAS,CAAA,EAAA,MAAA;EAAsB;;;;;EA6FxB,WAAA,CAAA,EAAA,MAAA;;;;;;;;UFhIH,cAAA;kBAEJ,wBAEJ,mBACJ,WAAW,QAAQ;EGiCR,SAAM,EAAA,UAAA,EH/BN,mBG+BM,EAAA,GAAA,EAAA,GAAA,EAAA,GAAA,EH7Bb,gBG6Ba,CAAA,EAAA,IAAA,GH5BV,OG4BU,CAAA,IAAA,CAAA;EACZ,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;;;;;;UHjBO,SAAA;;;;;;;;;;;AAAjB;;;;ACEA;AAyBgB,iBAzBA,UAAA,CAyBoB,GAAA,EAAA,MAAA,CAAA,EAAA,MAAA;;;;AC7EpC;AAOA;AAmDU,iBDmBM,oBAAA,CClBL,QAAsB,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,IAAA;;;AFThB,UElDA,cAAA,CFkDS;;;;ECEV,eAAU,CAAA,EAAA,MAAA;AAyB1B;UCtEiB,SAAA;;;EAPA;EAOA,QAAA,EAAA,MAAS;EAmDhB;EAKG,KAAA,EAAA,MAAS;EAAsB;EA2BH,MAAA,EA3E/B,QA2E+B,CA3EtB,cA2EsB,CAAA;EA6CG;EAYE,YAAA,EAAA,MAAA,GAAA,IAAA;;;;;;;UAzFpC,WAAA,CAKoB;EAAa,OAAA,EAJhC,sBAIgC;;;cAA9B,QAAA,SAAiB,cAAc;ECG5B,QAAA,MAAM;EACZ;EACC,QAAA,cAAA;EACQ;EAAhB,QAAA,WAAA;EAAe;;;;;;;;;;;mCDqBuB;;;;;;sCA6CG;;;;wCAYE;;;;cAS1B,QAAQ;;;;;oBAeF,iBAAiB;;;;;uBAUd;WAyBZ;;;;;;;;;;;;;;;;;;;;;;;;AAvMjB;AAWC;AA6CD;;;;;;;;;;AA+IiB,iBC5ID,MAAA,CD4IC,MAAA,EC3IP,cD2IO,EAAA,MAAA,CAAA,EC1IN,YD0IM,CAAA,ECzId,eDyIc,CCzIE,SDyIF,CAAA"}