@cloudflare/sandbox 0.9.2 → 0.9.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -411,64 +411,6 @@ interface PtyOptions {
411
411
  shell?: string;
412
412
  }
413
413
  //#endregion
414
- //#region ../shared/dist/request-types.d.ts
415
- /**
416
- * Request types for API calls to the container
417
- * Single source of truth for the contract between SDK clients and container handlers
418
- */
419
- /**
420
- * Request to execute a command
421
- */
422
- interface ExecuteRequest {
423
- command: string;
424
- sessionId?: string;
425
- background?: boolean;
426
- timeoutMs?: number;
427
- env?: Record<string, string | undefined>;
428
- cwd?: string;
429
- origin?: 'user' | 'internal';
430
- }
431
- /**
432
- * Request to start a background process
433
- * Uses flat structure consistent with other endpoints
434
- */
435
- interface StartProcessRequest {
436
- command: string;
437
- sessionId?: string;
438
- processId?: string;
439
- timeoutMs?: number;
440
- env?: Record<string, string | undefined>;
441
- cwd?: string;
442
- encoding?: string;
443
- autoCleanup?: boolean;
444
- origin?: 'user' | 'internal';
445
- }
446
- /**
447
- * Request to expose a port
448
- */
449
- interface ExposePortRequest {
450
- port: number;
451
- name?: string;
452
- }
453
- /**
454
- * Response from the container after creating a backup archive
455
- */
456
- interface CreateBackupResponse {
457
- success: boolean;
458
- /** Size of the archive in bytes */
459
- sizeBytes: number;
460
- /** Path to the archive file in the container */
461
- archivePath: string;
462
- }
463
- /**
464
- * Response from the container after restoring a backup
465
- */
466
- interface RestoreBackupResponse {
467
- success: boolean;
468
- /** Directory that was restored */
469
- dir: string;
470
- }
471
- //#endregion
472
414
  //#region ../shared/dist/types.d.ts
473
415
  interface BaseExecOptions {
474
416
  /**
@@ -791,6 +733,7 @@ interface SessionOptions {
791
733
  */
792
734
  commandTimeoutMs?: number;
793
735
  }
736
+ type SandboxTransport = 'http' | 'websocket' | 'rpc';
794
737
  interface SandboxOptions {
795
738
  /**
796
739
  * Duration after which the sandbox instance will sleep if no requests are received
@@ -879,13 +822,13 @@ interface SandboxOptions {
879
822
  waitIntervalMS?: number;
880
823
  };
881
824
  /**
882
- * Transport protocol for communication between the Sandbox DO and the container runtime.
825
+ * Transport/control path for communication between the Sandbox DO and the
826
+ * container runtime.
883
827
  *
884
- * - `"http"` (default): Standard HTTP request/response. Works everywhere.
885
- * - `"websocket"`: Multiplexes requests over a single WebSocket connection,
886
- * avoiding sub-request limits in Workers and Durable Objects.
887
- * - `"capnweb"`: Direct RPC over a single WebSocket using the capnweb protocol.
888
- * Lowest latency; automatically disconnects when idle to respect `sleepAfter`.
828
+ * - `"http"` (default): Route-based HTTP compatibility path.
829
+ * - `"websocket"`: Route-based compatibility path multiplexed over a custom
830
+ * WebSocket connection.
831
+ * - `"rpc"`: Primary container-control path over capnweb RPC.
889
832
  *
890
833
  * When set via `getSandbox()` options, this overrides the `SANDBOX_TRANSPORT` env var.
891
834
  *
@@ -896,7 +839,7 @@ interface SandboxOptions {
896
839
  *
897
840
  * @default "http"
898
841
  */
899
- transport?: 'http' | 'websocket' | 'rpc';
842
+ transport?: SandboxTransport;
900
843
  }
901
844
  /**
902
845
  * Execution session - isolated execution context within a sandbox
@@ -1266,6 +1209,10 @@ interface ExecutionSession {
1266
1209
  /**
1267
1210
  * Options for creating a directory backup
1268
1211
  */
1212
+ interface BackupCompressionOptions {
1213
+ format?: 'gzip' | 'lz4' | 'zstd';
1214
+ threads?: number;
1215
+ }
1269
1216
  interface BackupOptions {
1270
1217
  /** Directory to back up. Must be absolute and under `/workspace`, `/home`, `/tmp`, `/var/tmp`, or `/app`. */
1271
1218
  dir: string;
@@ -1294,6 +1241,13 @@ interface BackupOptions {
1294
1241
  * When true, the DO resolves BACKUP_BUCKET from its own env as an R2 binding.
1295
1242
  */
1296
1243
  localBucket?: boolean;
1244
+ compression?: BackupCompressionOptions;
1245
+ /**
1246
+ * Use parallel multipart upload to R2 for large archives.
1247
+ * Significantly speeds up uploads for archives over 10 MiB.
1248
+ * Default: true.
1249
+ */
1250
+ multipart?: boolean;
1297
1251
  }
1298
1252
  /**
1299
1253
  * Handle representing a stored directory backup.
@@ -1482,6 +1436,120 @@ declare function isExecResult(value: any): value is ExecResult;
1482
1436
  declare function isProcess(value: any): value is Process;
1483
1437
  declare function isProcessStatus(value: string): value is ProcessStatus;
1484
1438
  //#endregion
1439
+ //#region ../shared/dist/request-types.d.ts
1440
+ /**
1441
+ * Request types for API calls to the container
1442
+ * Single source of truth for the contract between SDK clients and container handlers
1443
+ */
1444
+ /**
1445
+ * Request to execute a command
1446
+ */
1447
+ interface ExecuteRequest {
1448
+ command: string;
1449
+ sessionId?: string;
1450
+ background?: boolean;
1451
+ timeoutMs?: number;
1452
+ env?: Record<string, string | undefined>;
1453
+ cwd?: string;
1454
+ origin?: 'user' | 'internal';
1455
+ }
1456
+ /**
1457
+ * Request to start a background process
1458
+ * Uses flat structure consistent with other endpoints
1459
+ */
1460
+ interface StartProcessRequest {
1461
+ command: string;
1462
+ sessionId?: string;
1463
+ processId?: string;
1464
+ timeoutMs?: number;
1465
+ env?: Record<string, string | undefined>;
1466
+ cwd?: string;
1467
+ encoding?: string;
1468
+ autoCleanup?: boolean;
1469
+ origin?: 'user' | 'internal';
1470
+ }
1471
+ /**
1472
+ * Request to expose a port
1473
+ */
1474
+ interface ExposePortRequest {
1475
+ port: number;
1476
+ name?: string;
1477
+ }
1478
+ /**
1479
+ * Request to create a backup archive from a directory.
1480
+ * The container creates a squashfs archive at archivePath.
1481
+ * The DO then reads it and uploads to R2.
1482
+ */
1483
+ interface CreateBackupRequest {
1484
+ /** Directory to back up */
1485
+ dir: string;
1486
+ /** Path where the container should write the archive */
1487
+ archivePath: string;
1488
+ /** Respect git ignore rules when the directory is inside a git repository */
1489
+ gitignore?: boolean;
1490
+ /** Glob patterns to exclude from the backup */
1491
+ excludes?: string[];
1492
+ compression?: BackupCompressionOptions;
1493
+ sessionId?: string;
1494
+ }
1495
+ /**
1496
+ * A single part to upload in a multipart upload.
1497
+ * The container reads the byte range from the local archive and PUTs it
1498
+ * to the presigned URL.
1499
+ */
1500
+ interface UploadPart {
1501
+ partNumber: number;
1502
+ /** Presigned PUT URL for this part */
1503
+ url: string;
1504
+ /** Byte offset within the archive file */
1505
+ offset: number;
1506
+ /** Number of bytes in this part */
1507
+ size: number;
1508
+ }
1509
+ /**
1510
+ * Request to upload parts of a backup archive directly from the container to R2.
1511
+ * Used for parallel multipart upload of large archives.
1512
+ */
1513
+ interface UploadPartsRequest {
1514
+ /** Path to the archive file in the container */
1515
+ archivePath: string;
1516
+ /** Parts to upload in parallel */
1517
+ parts: UploadPart[];
1518
+ sessionId?: string;
1519
+ }
1520
+ /**
1521
+ * Result for a single uploaded part (ETag returned by R2).
1522
+ */
1523
+ interface UploadedPart {
1524
+ partNumber: number;
1525
+ etag: string;
1526
+ }
1527
+ /**
1528
+ * Response after the container has uploaded all parts.
1529
+ */
1530
+ interface UploadPartsResponse {
1531
+ success: boolean;
1532
+ parts: UploadedPart[];
1533
+ }
1534
+ /**
1535
+ * Response from the container after creating a backup archive
1536
+ */
1537
+ interface CreateBackupResponse {
1538
+ success: boolean;
1539
+ /** Size of the archive in bytes */
1540
+ sizeBytes: number;
1541
+ /** Path to the archive file in the container */
1542
+ archivePath: string;
1543
+ }
1544
+ /**
1545
+ * Response from the container after restoring a backup
1546
+ */
1547
+ interface RestoreBackupResponse {
1548
+ success: boolean;
1549
+ /** Directory that was restored */
1550
+ dir: string;
1551
+ }
1552
+ //#endregion
1485
1553
  //#region ../shared/dist/rpc-types.d.ts
1486
1554
  interface SandboxCommandsAPI {
1487
1555
  execute(command: string, sessionId: string, options?: {
@@ -1592,8 +1660,19 @@ interface SandboxBackupAPI {
1592
1660
  createArchive(dir: string, archivePath: string, sessionId: string, options?: {
1593
1661
  excludes?: string[];
1594
1662
  gitignore?: boolean;
1663
+ compression?: BackupCompressionOptions;
1595
1664
  }): Promise<CreateBackupResponse>;
1596
1665
  restoreArchive(dir: string, archivePath: string, sessionId: string): Promise<RestoreBackupResponse>;
1666
+ uploadParts(request: {
1667
+ archivePath: string;
1668
+ parts: Array<{
1669
+ partNumber: number;
1670
+ url: string;
1671
+ offset: number;
1672
+ size: number;
1673
+ }>;
1674
+ sessionId?: string;
1675
+ }): Promise<UploadPartsResponse>;
1597
1676
  }
1598
1677
  interface SandboxDesktopAPI {
1599
1678
  start(options?: {
@@ -1661,11 +1740,10 @@ interface HttpClientOptions {
1661
1740
  onCommandComplete?: (success: boolean, exitCode: number, stdout: string, stderr: string, command: string) => void;
1662
1741
  onError?: (error: string, command?: string) => void;
1663
1742
  /**
1664
- * Transport mode: 'http' (default) or 'websocket'
1665
- * WebSocket mode multiplexes all requests over a single connection,
1666
- * reducing sub-request count in Workers/Durable Objects.
1743
+ * Route-based transport mode: 'http' (default) or 'websocket'.
1744
+ * WebSocket mode multiplexes HTTP API requests over a single connection.
1667
1745
  */
1668
- transportMode?: TransportMode;
1746
+ transportMode?: RouteTransportMode;
1669
1747
  /**
1670
1748
  * WebSocket URL for WebSocket transport mode.
1671
1749
  * Required when transportMode is 'websocket'.
@@ -1723,18 +1801,19 @@ interface SessionRequest {
1723
1801
  //#endregion
1724
1802
  //#region src/clients/transport/types.d.ts
1725
1803
  /**
1726
- * Transport mode for SDK communication
1804
+ * Transport modes supported by the route-based compatibility layer.
1727
1805
  */
1728
- type TransportMode = 'http' | 'websocket' | 'rpc';
1806
+ type RouteTransportMode = 'http' | 'websocket';
1729
1807
  interface TransportRequestInit extends RequestInit {
1730
1808
  /** Override the non-streaming request timeout for this single request. */
1731
1809
  requestTimeoutMs?: number;
1732
1810
  }
1733
1811
  /**
1734
- * Transport interface - all transports must implement this
1812
+ * Route transport interface.
1735
1813
  *
1736
- * Provides a unified abstraction over HTTP and WebSocket communication.
1737
- * Both transports support fetch-compatible requests and streaming.
1814
+ * Provides a unified abstraction over the route-based HTTP and custom
1815
+ * WebSocket compatibility paths. Both transports support fetch-compatible
1816
+ * requests and streaming.
1738
1817
  */
1739
1818
  interface ITransport {
1740
1819
  /**
@@ -1750,7 +1829,7 @@ interface ITransport {
1750
1829
  /**
1751
1830
  * Get the transport mode
1752
1831
  */
1753
- getMode(): TransportMode;
1832
+ getMode(): RouteTransportMode;
1754
1833
  /**
1755
1834
  * Connect the transport (no-op for HTTP)
1756
1835
  */
@@ -1771,15 +1850,15 @@ interface ITransport {
1771
1850
  //#endregion
1772
1851
  //#region src/clients/base-client.d.ts
1773
1852
  /**
1774
- * Abstract base class providing common HTTP/WebSocket functionality for all domain clients
1853
+ * Abstract base class for route-based HTTP/WebSocket compatibility clients.
1775
1854
  *
1776
- * All requests go through the Transport abstraction layer, which handles:
1777
- * - HTTP and WebSocket modes transparently
1778
- * - Automatic retry for 503 errors (container starting)
1779
- * - Streaming responses
1855
+ * Requests go through the Transport abstraction layer, which handles:
1856
+ * - HTTP and WebSocket route-based modes transparently
1857
+ * - Automatic retry for 503 errors while the container is starting
1858
+ * - Streaming responses for the existing route API
1780
1859
  *
1781
- * WebSocket mode is useful when running inside Workers/Durable Objects
1782
- * where sub-request limits apply.
1860
+ * DO-to-container control-channel capabilities live in `container-control/`.
1861
+ * This layer supports the route-based compatibility API.
1783
1862
  */
1784
1863
  declare abstract class BaseHttpClient {
1785
1864
  protected options: HttpClientOptions;
@@ -1825,7 +1904,7 @@ declare abstract class BaseHttpClient {
1825
1904
  /**
1826
1905
  * Stream request handler
1827
1906
  *
1828
- * For HTTP mode, uses doFetch + handleStreamResponse to get proper error typing.
1907
+ * HTTP mode uses doFetch + handleStreamResponse for typed error handling.
1829
1908
  * For WebSocket mode, uses Transport's streaming support.
1830
1909
  *
1831
1910
  * @param path - The API path to call
@@ -1853,6 +1932,7 @@ declare class BackupClient extends BaseHttpClient {
1853
1932
  createArchive(dir: string, archivePath: string, sessionId: string, options?: {
1854
1933
  excludes?: string[];
1855
1934
  gitignore?: boolean;
1935
+ compression?: CreateBackupRequest['compression'];
1856
1936
  }): Promise<CreateBackupResponse>;
1857
1937
  /**
1858
1938
  * Tell the container to restore a squashfs archive into a directory.
@@ -1861,6 +1941,7 @@ declare class BackupClient extends BaseHttpClient {
1861
1941
  * @param sessionId - Session context
1862
1942
  */
1863
1943
  restoreArchive(dir: string, archivePath: string, sessionId: string): Promise<RestoreBackupResponse>;
1944
+ uploadParts(request: UploadPartsRequest, sessionId?: string): Promise<UploadPartsResponse>;
1864
1945
  }
1865
1946
  //#endregion
1866
1947
  //#region src/clients/command-client.d.ts
@@ -2489,13 +2570,13 @@ declare class WatchClient extends BaseHttpClient {
2489
2570
  //#endregion
2490
2571
  //#region src/clients/sandbox-client.d.ts
2491
2572
  /**
2492
- * Main sandbox client that composes all domain-specific clients.
2493
- * Provides organized access to all sandbox functionality.
2573
+ * Route-based compatibility sandbox client that composes all domain-specific
2574
+ * HTTP API clients.
2494
2575
  *
2495
- * Supports two transport modes:
2496
- * - HTTP (default): Each request is a separate HTTP call
2497
- * - WebSocket: All requests multiplexed over a single connection,
2498
- * reducing sub-request count inside Workers/Durable Objects
2576
+ * This client supports the route-based HTTP and custom WebSocket transports.
2577
+ * The primary DO-to-container control path is ContainerControlClient under
2578
+ * `container-control/`. This client supports route-based compatibility,
2579
+ * debugging, local development, and fallback behavior.
2499
2580
  */
2500
2581
  declare class SandboxClient {
2501
2582
  readonly backup: BackupClient;
@@ -2521,7 +2602,7 @@ declare class SandboxClient {
2521
2602
  /**
2522
2603
  * Get the current transport mode
2523
2604
  */
2524
- getTransportMode(): TransportMode;
2605
+ getTransportMode(): RouteTransportMode;
2525
2606
  /**
2526
2607
  * Check if WebSocket is connected (only relevant in WebSocket mode)
2527
2608
  */
@@ -2529,9 +2610,9 @@ declare class SandboxClient {
2529
2610
  /**
2530
2611
  * Stream a file directly to the container over a binary RPC channel.
2531
2612
  *
2532
- * Requires the capnweb transport (`useWebSocket: 'rpc'`). Calling this
2533
- * method with the HTTP or WebSocket transports throws an error because those
2534
- * transports do not support binary streaming.
2613
+ * Requires the container-control path (`transport: 'rpc'`). Calling this
2614
+ * method with the HTTP or WebSocket route transports throws an error because
2615
+ * those transports do not support binary streaming.
2535
2616
  */
2536
2617
  writeFileStream(_path: string, _content: ReadableStream<Uint8Array>, _sessionId: string): Promise<{
2537
2618
  success: boolean;
@@ -2552,19 +2633,19 @@ declare class SandboxClient {
2552
2633
  disconnect(): void;
2553
2634
  }
2554
2635
  //#endregion
2555
- //#region src/container-connection.d.ts
2636
+ //#region src/container-control/connection.d.ts
2556
2637
  /** Stub that can issue a WebSocket-upgrade fetch through the DO's Container base class. */
2557
2638
  interface ContainerFetchStub {
2558
2639
  fetch(request: Request): Promise<Response>;
2559
2640
  }
2560
- interface ContainerConnectionOptions {
2641
+ interface ContainerControlConnectionOptions {
2561
2642
  stub: ContainerFetchStub;
2562
2643
  port?: number;
2563
2644
  logger?: Logger;
2564
2645
  }
2565
2646
  //#endregion
2566
- //#region src/clients/rpc-sandbox-client.d.ts
2567
- interface RPCSandboxClientOptions extends ContainerConnectionOptions {
2647
+ //#region src/container-control/client.d.ts
2648
+ interface ContainerControlClientOptions extends ContainerControlConnectionOptions {
2568
2649
  /** Idle timeout before disconnecting the WebSocket (ms). Defaults to 1 000. */
2569
2650
  idleDisconnectMs?: number;
2570
2651
  /** Busy/idle poll interval (ms). Defaults to 1 000. */
@@ -2592,20 +2673,19 @@ interface RPCSandboxClientOptions extends ContainerConnectionOptions {
2592
2673
  onSessionIdle?: () => void;
2593
2674
  }
2594
2675
  /**
2595
- * SandboxClient backed by direct capnweb RPC.
2676
+ * SandboxClient-compatible facade backed by direct capnweb RPC.
2596
2677
  *
2597
- * Drop-in replacement for SandboxClient when the capnweb transport is active.
2598
- * All operations call the container's SandboxRPCAPI directly over capnweb,
2599
- * bypassing the HTTP handler/router layer entirely.
2678
+ * All operations call the container's SandboxAPI control interface directly
2679
+ * over capnweb, bypassing the HTTP handler/router layer entirely.
2600
2680
  *
2601
- * Manages its own WebSocket lifecycle: a fresh `ContainerConnection` is
2681
+ * Manages its own WebSocket lifecycle: a fresh `ContainerControlConnection` is
2602
2682
  * created on demand and torn down after `idleDisconnectMs` of inactivity.
2603
2683
  * Busy/idle detection relies on `RpcSession.getStats()` which tracks all
2604
2684
  * in-flight RPC calls and stream exports — including long-lived streaming
2605
2685
  * RPCs that would be invisible to a simple per-call request counter (see
2606
2686
  * the file-level comment for the full rationale).
2607
2687
  */
2608
- declare class RPCSandboxClient {
2688
+ declare class ContainerControlClient {
2609
2689
  private readonly connOptions;
2610
2690
  private readonly idleDisconnectMs;
2611
2691
  private readonly busyPollIntervalMs;
@@ -2625,11 +2705,10 @@ declare class RPCSandboxClient {
2625
2705
  * connected and the peer went away" (do tear down).
2626
2706
  */
2627
2707
  private wasEverConnected;
2628
- constructor(options: RPCSandboxClientOptions);
2708
+ constructor(options: ContainerControlClientOptions);
2629
2709
  /**
2630
- * Return the current connection, creating a new one if none exists or the
2631
- * previous one was torn down by an idle disconnect. Starts the busy-poll
2632
- * timer the first time a connection is materialized.
2710
+ * Return the current connection, creating one when the client is disconnected.
2711
+ * Starts the busy-poll timer the first time a connection is materialized.
2633
2712
  */
2634
2713
  private getConnection;
2635
2714
  /**
@@ -2666,7 +2745,7 @@ declare class RPCSandboxClient {
2666
2745
  get watch(): SandboxWatchAPI;
2667
2746
  get interpreter(): SandboxInterpreterAPI;
2668
2747
  setRetryTimeoutMs(_ms: number): void;
2669
- getTransportMode(): TransportMode;
2748
+ getTransportMode(): SandboxTransport;
2670
2749
  isWebSocketConnected(): boolean;
2671
2750
  connect(): Promise<void>;
2672
2751
  disconnect(): void;
@@ -2687,13 +2766,13 @@ type SandboxConfiguration = {
2687
2766
  sleepAfter?: string | number;
2688
2767
  keepAlive?: boolean;
2689
2768
  containerTimeouts?: NonNullable<SandboxOptions['containerTimeouts']>;
2690
- transport?: 'http' | 'websocket' | 'rpc';
2769
+ transport?: SandboxTransport;
2691
2770
  };
2692
2771
  declare function getSandbox<T extends Sandbox<any>>(ns: DurableObjectNamespace<T>, id: string, options?: SandboxOptions): T;
2693
2772
  declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
2694
2773
  defaultPort: number;
2695
2774
  sleepAfter: string | number;
2696
- client: SandboxClient | RPCSandboxClient;
2775
+ client: SandboxClient | ContainerControlClient;
2697
2776
  private codeInterpreter;
2698
2777
  private sandboxName;
2699
2778
  private normalizeId;
@@ -2778,11 +2857,15 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
2778
2857
  */
2779
2858
  private computeRetryTimeoutMs;
2780
2859
  /**
2781
- * Create a SandboxClient with current transport settings
2860
+ * Create the route-based compatibility client with current HTTP/WebSocket
2861
+ * transport settings.
2782
2862
  */
2783
2863
  private createSandboxClient;
2784
2864
  /**
2785
- * Create the appropriate client for a given transport protocol.
2865
+ * Create the appropriate client for the configured control path.
2866
+ *
2867
+ * `rpc` currently selects the primary container-control client. `http` and
2868
+ * `websocket` select the route-based compatibility client.
2786
2869
  */
2787
2870
  private createClientForTransport;
2788
2871
  constructor(ctx: DurableObjectState<{}>, env: Env);
@@ -2804,7 +2887,7 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
2804
2887
  * has been persisted: re-applying the same transport is a no-op.
2805
2888
  * Storage is written before the in-memory state and client are updated.
2806
2889
  */
2807
- setTransport(transport: 'http' | 'websocket' | 'rpc'): Promise<void>;
2890
+ setTransport(transport: SandboxTransport): Promise<void>;
2808
2891
  /**
2809
2892
  * Validate a timeout value is within acceptable range
2810
2893
  * Throws error if invalid - used for user-provided values
@@ -3263,6 +3346,7 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
3263
3346
  */
3264
3347
  private requireBackupBucket;
3265
3348
  private normalizeBackupExcludes;
3349
+ private resolveBackupCompression;
3266
3350
  private static readonly PRESIGNED_URL_EXPIRY_SECONDS;
3267
3351
  /**
3268
3352
  * Create a unique, dedicated session for a single backup operation.
@@ -3276,6 +3360,11 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
3276
3360
  * All credential fields plus the R2 binding are required for backup to work.
3277
3361
  */
3278
3362
  private requirePresignedUrlSupport;
3363
+ /**
3364
+ * Generate a presigned GET URL for downloading an object from R2.
3365
+ * The container can curl this URL directly without credentials.
3366
+ */
3367
+ private generatePresignedGetUrl;
3279
3368
  /**
3280
3369
  * Generate a presigned PUT URL for uploading an object to R2.
3281
3370
  * The container can curl PUT to this URL directly without credentials.
@@ -3288,9 +3377,23 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
3288
3377
  */
3289
3378
  private uploadBackupPresigned;
3290
3379
  /**
3291
- * Mount a backup archive from R2 via s3fs so squashfuse can read it lazily.
3380
+ * Generate a presigned PUT URL for a single part in a multipart upload.
3381
+ */
3382
+ private generatePresignedPartUrl;
3383
+ /**
3384
+ * Upload a backup archive to R2 using parallel multipart upload.
3385
+ * Uses the S3-compatible API exclusively for create/complete/abort so that
3386
+ * the uploadId is in the same namespace as the presigned part PUT URLs.
3387
+ */
3388
+ private uploadBackupMultipart;
3389
+ /**
3390
+ * Download a backup archive from R2 via presigned GET URL.
3391
+ * For archives >= BACKUP_DOWNLOAD_PARALLEL_MIN_SIZE, uses BACKUP_DOWNLOAD_PARALLEL_PARTS
3392
+ * concurrent curl processes (each downloading a byte-range) to maximise both
3393
+ * network and disk-write throughput. Parts are written into a pre-sized file
3394
+ * with dd using byte offsets, then atomically moved to the final path.
3292
3395
  */
3293
- private mountBackupR2;
3396
+ private downloadBackupParallel;
3294
3397
  /**
3295
3398
  * Serialize backup operations on this sandbox instance.
3296
3399
  * Concurrent backup/restore calls are queued so the multi-step
@@ -3369,5 +3472,5 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
3369
3472
  private doRestoreBackupLocal;
3370
3473
  }
3371
3474
  //#endregion
3372
- export { BucketProvider as $, DesktopStopResponse as A, RestoreBackupResult as At, ExecuteResponse as B, ExecuteRequest as Bt, ClickOptions as C, ProcessKillResult as Ct, DesktopStartOptions as D, ProcessStartResult as Dt, DesktopClient as E, ProcessOptions as Et, ScreenshotRegion as F, WaitForPortOptions as Ft, HttpClientOptions as G, CreateContextOptions as Gt, BaseApiResponse as H, StartProcessRequest as Ht, ScreenshotResponse as I, WatchOptions as It, SessionRequest as J, RunCodeOptions as Jt, RequestConfig as K, Execution as Kt, ScrollDirection as L, isExecResult as Lt, ScreenSizeResponse as M, SessionOptions as Mt, ScreenshotBytesResponse as N, StreamOptions as Nt, DesktopStartResponse as O, ProcessStatus as Ot, ScreenshotOptions as P, WaitForLogResult as Pt, BucketCredentials as Q, TypeOptions as R, isProcess as Rt, WriteFileRequest as S, ProcessInfoResult as St, Desktop as T, ProcessLogsResult as Tt, ContainerStub as U, PtyOptions as Ut, BackupClient as V, ExposePortRequest as Vt, ErrorResponse as W, CodeContext as Wt, BackupOptions as X, SandboxInterpreterAPI as Y, BaseExecOptions as Z, GitClient as _, PortCloseResult as _t, CreateSessionRequest as a, ExecResult as at, MkdirRequest as b, Process as bt, DeleteSessionResponse as c, FileMetadata as ct, ProcessClient as d, GitCheckoutResult as dt, CheckChangesOptions as et, PortClient as f, ISandbox as ft, GitCheckoutRequest as g, MountBucketOptions as gt, InterpreterClient as h, LogEvent as ht, CommandsResponse as i, ExecOptions as it, KeyInput as j, SandboxOptions as jt, DesktopStatusResponse as k, RemoteMountBucketOptions as kt, PingResponse as l, FileStreamEvent as lt, ExecutionCallbacks as m, LocalMountBucketOptions as mt, getSandbox as n, DirectoryBackup as nt, CreateSessionResponse as o, ExecutionSession as ot, UnexposePortRequest as p, ListFilesOptions as pt, ResponseHandler as q, ExecutionResult as qt, SandboxClient as r, ExecEvent as rt, DeleteSessionRequest as s, FileChunk as st, Sandbox as t, CheckChangesResult as tt, UtilityClient as u, FileWatchSSEEvent as ut, FileClient as v, PortExposeResult as vt, CursorPositionResponse as w, ProcessListResult as wt, ReadFileRequest as x, ProcessCleanupResult as xt, FileOperationRequest as y, PortListResult as yt, CommandClient as z, isProcessStatus as zt };
3373
- //# sourceMappingURL=sandbox-YMrVC62F.d.ts.map
3475
+ export { BackupOptions as $, DesktopStopResponse as A, ProcessStartResult as At, ExecuteResponse as B, WatchOptions as Bt, ClickOptions as C, Process as Ct, DesktopStartOptions as D, ProcessListResult as Dt, DesktopClient as E, ProcessKillResult as Et, ScreenshotRegion as F, SandboxTransport as Ft, HttpClientOptions as G, CodeContext as Gt, BaseApiResponse as H, isProcess as Ht, ScreenshotResponse as I, SessionOptions as It, SessionRequest as J, ExecutionResult as Jt, RequestConfig as K, CreateContextOptions as Kt, ScrollDirection as L, StreamOptions as Lt, ScreenSizeResponse as M, RemoteMountBucketOptions as Mt, ScreenshotBytesResponse as N, RestoreBackupResult as Nt, DesktopStartResponse as O, ProcessLogsResult as Ot, ScreenshotOptions as P, SandboxOptions as Pt, StartProcessRequest as Q, TypeOptions as R, WaitForLogResult as Rt, WriteFileRequest as S, PortListResult as St, Desktop as T, ProcessInfoResult as Tt, ContainerStub as U, isProcessStatus as Ut, BackupClient as V, isExecResult as Vt, ErrorResponse as W, PtyOptions as Wt, ExecuteRequest as X, SandboxInterpreterAPI as Y, RunCodeOptions as Yt, ExposePortRequest as Z, GitClient as _, LocalMountBucketOptions as _t, CreateSessionRequest as a, DirectoryBackup as at, MkdirRequest as b, PortCloseResult as bt, DeleteSessionResponse as c, ExecResult as ct, ProcessClient as d, FileMetadata as dt, BaseExecOptions as et, PortClient as f, FileStreamEvent as ft, GitCheckoutRequest as g, ListFilesOptions as gt, InterpreterClient as h, ISandbox as ht, CommandsResponse as i, CheckChangesResult as it, KeyInput as j, ProcessStatus as jt, DesktopStatusResponse as k, ProcessOptions as kt, PingResponse as l, ExecutionSession as lt, ExecutionCallbacks as m, GitCheckoutResult as mt, getSandbox as n, BucketProvider as nt, CreateSessionResponse as o, ExecEvent as ot, UnexposePortRequest as p, FileWatchSSEEvent as pt, ResponseHandler as q, Execution as qt, SandboxClient as r, CheckChangesOptions as rt, DeleteSessionRequest as s, ExecOptions as st, Sandbox as t, BucketCredentials as tt, UtilityClient as u, FileChunk as ut, FileClient as v, LogEvent as vt, CursorPositionResponse as w, ProcessCleanupResult as wt, ReadFileRequest as x, PortExposeResult as xt, FileOperationRequest as y, MountBucketOptions as yt, CommandClient as z, WaitForPortOptions as zt };
3476
+ //# sourceMappingURL=sandbox-CW4QeITP.d.ts.map