@cloudflare/sandbox 0.12.3 → 0.12.5

package/README.md

@@ -98,6 +98,26 @@ export default {
 };
 ```
 
+## Sandbox options
+
+Pass options as the third argument to `getSandbox()` to configure sandbox
+lifetime and container startup metadata:
+
+```ts
+const sandbox = getSandbox(env.Sandbox, 'tenant-workspace', {
+  sleepAfter: '30m',
+  labels: {
+    tenantId: 'tenant_123',
+    workload: 'code-workspace'
+  }
+});
+```
+
+Container labels are attached to the underlying Cloudflare Container for
+analytics and observability. Labels are applied when the container starts; if
+labels are changed while a container is already running, the new labels apply
+the next time the container starts.
+
 ## Quick tunnels
 
 `sandbox.tunnels.get(port)` exposes a service running inside the

package/dist/bridge/index.d.ts

@@ -49,6 +49,8 @@ interface BridgeEnv {
   SANDBOX_API_KEY?: string;
   WARM_POOL_TARGET?: string;
   WARM_POOL_REFRESH_INTERVAL?: string;
+  WARM_POOL_MAX_INSTANCES?: string;
+  WARM_POOL_SCALE_BATCH_SIZE?: string;
   [key: string]: unknown;
 }
 //#endregion
@@ -75,6 +77,20 @@ interface WarmPoolConfig {
   warmTarget?: number;
   /** How often to check and replenish warm containers (ms). @default 10000 */
   refreshInterval?: number;
+  /**
+   * Operator-declared max_instances ceiling, mirroring
+   * `containers[].max_instances` in wrangler.jsonc. Seeds the pool's capacity
+   * math so it never blindly attempts doomed starts. 0/undefined = auto-learn
+   * the ceiling reactively from platform errors (legacy behaviour).
+   * @default 0
+   */
+  maxInstances?: number;
+  /**
+   * Number of containers to start in parallel per scale-up batch. Higher
+   * values fill the pool faster but risk the platform throttling a cold-start
+   * stampede. Clamped to [1, MAX_BATCH_SIZE]. @default 5
+   */
+  scaleBatchSize?: number;
 }
 interface PoolStats {
   /** Number of warm (unassigned) containers ready for use */
@@ -109,6 +125,13 @@ declare class WarmPool extends DurableObject<WarmPoolEnv> {
   private knownMaxInstances;
   private capacityExhausted;
   private initialized;
+  /** Guards against overlapping eager refills triggered by concurrent pops. */
+  private refillInFlight;
+  /**
+   * The currently in-flight eager refill, or null. Exposed for tests to await
+   * the otherwise fire-and-forget refill deterministically.
+   */
+  private refillPromise;
   /**
    * Get a container UUID for the given sandbox ID.
    * - If this ID already has an assigned container that's still running, return it.
@@ -139,6 +162,13 @@ declare class WarmPool extends DurableObject<WarmPoolEnv> {
    * Does not affect containers that are assigned to sandbox IDs.
    */
   shutdownPrewarmed(): Promise<void>;
+  /**
+   * Kick a non-blocking refill toward warmTarget. Debounced via refillInFlight
+   * so a burst of concurrent pops triggers at most one adjustPool sweep at a
+   * time; capacity is respected because adjustPool clamps to remainingCapacity.
+   * Errors are swallowed so a failed refill never rejects the triggering call.
+   */
+  private requestRefill;
   alarm(): Promise<void>;
   private init;
   private persist;

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

@@ -1 +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":";;;;;;;AA6DgB,UAvCC,YAAA,CAuCD;EAEP;;;AAaT;;;;ICJgB,OAAA,CAAA,EAAU,MAAA;IAyBV;;;;AC7EhB;AAOA;AAWC;AA6CD;EAA4C,cAAA,CAAA,EAAA,MAAA;EA2BH;;;;;EAiFf,WAAA,CAAA,EAAA,MAAA;;;;;;;;UFzIT,cAAA;EGgCD,KAAA,EAAA,OAAM,EH9BT,OG8BS,EAAA,GAAA,EAAA,GAAA,EAAA,GAAA,EH5Bb,gBG4Ba,CAAA,EH3BjB,QG2BiB,GH3BN,OG2BM,CH3BE,QG2BF,CAAA;EACZ,SAAA,EAAA,UAAA,EH1BM,mBG0BN,EAAA,GAAA,EAAA,GAAA,EAAA,GAAA,EHxBD,gBGwBC,CAAA,EAAA,IAAA,GHvBE,OGuBF,CAAA,IAAA,CAAA;EACC,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;;;;;;UHZM,SAAA;;;;;;;;;;;AAAjB;;;;ACJA;AAyBgB,iBAzBA,UAAA,CAyBoB,GAAA,EAAA,MAAA,CAAA,EAAA,MAAA;;;;AC7EpC;AAOA;AAmDU,iBDmBM,oBAAA,CClBL,QAAsB,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,IAAA;;;AFHhB,UExDA,cAAA,CFwDS;;;;ECJV,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"}
+{"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":";;;;;;;AA6DgB,UAvCC,YAAA,CAuCD;EAEP;;;AAaT;;;;ICJgB,OAAA,CAAA,EAAU,MAAA;IAyBV;;;;AC7EhB;AAqBA;AAWC;AAoDD;EAA4C,cAAA,CAAA,EAAA,MAAA;EAoCH;;;;;EAqFf,WAAA,CAAA,EAAA,MAAA;;;;;;;;UF3KT,cAAA;EGgCD,KAAA,EAAA,OAAM,EH9BT,OG8BS,EAAA,GAAA,EAAA,GAAA,EAAA,GAAA,EH5Bb,gBG4Ba,CAAA,EH3BjB,QG2BiB,GH3BN,OG2BM,CH3BE,QG2BF,CAAA;EACZ,SAAA,EAAA,UAAA,EH1BM,mBG0BN,EAAA,GAAA,EAAA,GAAA,EAAA,GAAA,EHxBD,gBGwBC,CAAA,EAAA,IAAA,GHvBE,OGuBF,CAAA,IAAA,CAAA;EACC,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;;;;;;UHZM,SAAA;;;;;;;;;;;;;AAAjB;;;;ACJA;AAyBgB,iBAzBA,UAAA,CAyBoB,GAAA,EAAA,MAAA,CAAA,EAAA,MAAA;;;;AC7EpC;AAqBA;AA0DU,iBDFM,oBAAA,CCGL,QAAsB,EAAA,MAAA,CAAA,EAAA,MAAA,GAAA,IAAA;;;AFxBhB,UExDA,cAAA,CFwDS;;;;ECJV,eAAU,CAAA,EAAA,MAAA;EAyBV;;;;AC7EhB;AAqBA;AAWC;EAoDY,YAAS,CAAA,EAAA,MAAA;EAAsB;;;;;EA0GxB,cAAA,CAAA,EAAA,MAAA;;AAeuB,UAxL1B,SAAA,CAwL0B;EA+Bd;EAyDZ,IAAA,EAAA,MAAA;EAjNa;EAAa,QAAA,EAAA,MAAA;;;;EClB3B,MAAA,EDrCN,QCqCY,CDrCH,cCqCG,CAAA;EACZ;EACC,YAAA,EAAA,MAAA,GAAA,IAAA;;;;;;;UDWD,WAAA;WACC;;;cAIE,QAAA,SAAiB,cAAc;;;;;;;;;;;;;;;;;;;;;;;;mCAoCH;;;;;;sCAiDG;;;;wCAYE;;;;cAS1B,QAAQ;;;;;oBAeF,iBAAiB;;;;;uBA+Bd;;;;;;;;WAyDZ;;;;;;;;;;;;;;;;;;;;;;;;AAhRjB;AAWC;AAoDD;;;;;;;;;;AAiNiB,iBCnOD,MAAA,CDmOC,MAAA,EClOP,cDkOO,EAAA,MAAA,CAAA,ECjON,YDiOM,CAAA,EChOd,eDgOc,CChOE,SDgOF,CAAA"}