@cloudflare/sandbox 0.9.1 → 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.
- package/dist/bridge/index.js +2 -2
- package/dist/{contexts-D6kt6WyG.d.ts → contexts-D_shbnJs.d.ts} +32 -2
- package/dist/contexts-D_shbnJs.d.ts.map +1 -0
- package/dist/errors-CBi-O-pF.js +227 -0
- package/dist/errors-CBi-O-pF.js.map +1 -0
- package/dist/index.d.ts +25 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -3
- package/dist/openai/index.d.ts +1 -1
- package/dist/opencode/index.d.ts +2 -2
- package/dist/opencode/index.d.ts.map +1 -1
- package/dist/opencode/index.js +1 -1
- package/dist/{sandbox-PAYx1CcU.js → sandbox-BAuU-2a0.js} +553 -118
- package/dist/sandbox-BAuU-2a0.js.map +1 -0
- package/dist/{sandbox-Bb3n0SeC.d.ts → sandbox-CW4QeITP.d.ts} +221 -117
- package/dist/sandbox-CW4QeITP.d.ts.map +1 -0
- package/package.json +1 -1
- package/dist/contexts-D6kt6WyG.d.ts.map +0 -1
- package/dist/errors-LE3HHcRb.js +0 -169
- package/dist/errors-LE3HHcRb.js.map +0 -1
- package/dist/sandbox-Bb3n0SeC.d.ts.map +0 -1
- package/dist/sandbox-PAYx1CcU.js.map +0 -1
|
@@ -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
|
|
825
|
+
* Transport/control path for communication between the Sandbox DO and the
|
|
826
|
+
* container runtime.
|
|
883
827
|
*
|
|
884
|
-
* - `"http"` (default):
|
|
885
|
-
* - `"websocket"`:
|
|
886
|
-
*
|
|
887
|
-
* - `"
|
|
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?:
|
|
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
|
-
*
|
|
1665
|
-
* WebSocket mode multiplexes
|
|
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?:
|
|
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
|
|
1804
|
+
* Transport modes supported by the route-based compatibility layer.
|
|
1727
1805
|
*/
|
|
1728
|
-
type
|
|
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
|
-
*
|
|
1812
|
+
* Route transport interface.
|
|
1735
1813
|
*
|
|
1736
|
-
* Provides a unified abstraction over HTTP and
|
|
1737
|
-
* Both transports support fetch-compatible
|
|
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():
|
|
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
|
|
1853
|
+
* Abstract base class for route-based HTTP/WebSocket compatibility clients.
|
|
1775
1854
|
*
|
|
1776
|
-
*
|
|
1777
|
-
* - HTTP and WebSocket modes transparently
|
|
1778
|
-
* - Automatic retry for 503 errors
|
|
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
|
-
*
|
|
1782
|
-
*
|
|
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
|
-
*
|
|
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
|
-
*
|
|
2493
|
-
*
|
|
2573
|
+
* Route-based compatibility sandbox client that composes all domain-specific
|
|
2574
|
+
* HTTP API clients.
|
|
2494
2575
|
*
|
|
2495
|
-
*
|
|
2496
|
-
*
|
|
2497
|
-
* -
|
|
2498
|
-
*
|
|
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():
|
|
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
|
|
2533
|
-
* method with the HTTP or WebSocket transports throws an error because
|
|
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
|
|
2641
|
+
interface ContainerControlConnectionOptions {
|
|
2561
2642
|
stub: ContainerFetchStub;
|
|
2562
2643
|
port?: number;
|
|
2563
2644
|
logger?: Logger;
|
|
2564
2645
|
}
|
|
2565
2646
|
//#endregion
|
|
2566
|
-
//#region src/
|
|
2567
|
-
interface
|
|
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
|
-
*
|
|
2598
|
-
*
|
|
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 `
|
|
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
|
|
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:
|
|
2708
|
+
constructor(options: ContainerControlClientOptions);
|
|
2629
2709
|
/**
|
|
2630
|
-
* Return the current connection, creating
|
|
2631
|
-
*
|
|
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():
|
|
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?:
|
|
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 |
|
|
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
|
|
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
|
|
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:
|
|
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
|
|
@@ -3262,6 +3345,8 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
|
|
|
3262
3345
|
* Returns the R2 bucket or throws if backup is not configured.
|
|
3263
3346
|
*/
|
|
3264
3347
|
private requireBackupBucket;
|
|
3348
|
+
private normalizeBackupExcludes;
|
|
3349
|
+
private resolveBackupCompression;
|
|
3265
3350
|
private static readonly PRESIGNED_URL_EXPIRY_SECONDS;
|
|
3266
3351
|
/**
|
|
3267
3352
|
* Create a unique, dedicated session for a single backup operation.
|
|
@@ -3275,6 +3360,11 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
|
|
|
3275
3360
|
* All credential fields plus the R2 binding are required for backup to work.
|
|
3276
3361
|
*/
|
|
3277
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;
|
|
3278
3368
|
/**
|
|
3279
3369
|
* Generate a presigned PUT URL for uploading an object to R2.
|
|
3280
3370
|
* The container can curl PUT to this URL directly without credentials.
|
|
@@ -3287,9 +3377,23 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
|
|
|
3287
3377
|
*/
|
|
3288
3378
|
private uploadBackupPresigned;
|
|
3289
3379
|
/**
|
|
3290
|
-
*
|
|
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.
|
|
3291
3395
|
*/
|
|
3292
|
-
private
|
|
3396
|
+
private downloadBackupParallel;
|
|
3293
3397
|
/**
|
|
3294
3398
|
* Serialize backup operations on this sandbox instance.
|
|
3295
3399
|
* Concurrent backup/restore calls are queued so the multi-step
|
|
@@ -3368,5 +3472,5 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
|
|
|
3368
3472
|
private doRestoreBackupLocal;
|
|
3369
3473
|
}
|
|
3370
3474
|
//#endregion
|
|
3371
|
-
export {
|
|
3372
|
-
//# sourceMappingURL=sandbox-
|
|
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
|