cubepod 0.0.0-stage → 0.4.0
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/README.md +201 -2
- package/package.json +45 -4
- package/src/archive.d.ts +18 -0
- package/src/archive.js +178 -0
- package/src/client.d.ts +515 -0
- package/src/client.js +1501 -0
- package/src/errors.d.ts +31 -0
- package/src/errors.js +137 -0
- package/src/index.d.ts +5 -0
- package/src/index.js +5 -0
- package/src/ndjson.d.ts +4 -0
- package/src/ndjson.js +62 -0
- package/src/sandbox.d.ts +98 -0
- package/src/sandbox.js +246 -0
package/src/errors.d.ts
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
export class CubePodError extends Error {
|
|
2
|
+
constructor(message: string, options?: { cause?: unknown });
|
|
3
|
+
}
|
|
4
|
+
|
|
5
|
+
export interface CubePodAPIErrorOptions {
|
|
6
|
+
statusCode: number;
|
|
7
|
+
code?: string | number;
|
|
8
|
+
sandboxId?: string;
|
|
9
|
+
body?: unknown;
|
|
10
|
+
logPath?: string;
|
|
11
|
+
details?: string;
|
|
12
|
+
step?: string;
|
|
13
|
+
cause?: unknown;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export class CubePodAPIError extends CubePodError {
|
|
17
|
+
readonly statusCode: number;
|
|
18
|
+
readonly code?: string | number;
|
|
19
|
+
readonly sandboxId?: string;
|
|
20
|
+
readonly body?: unknown;
|
|
21
|
+
readonly logPath?: string;
|
|
22
|
+
readonly details?: string;
|
|
23
|
+
readonly step?: string;
|
|
24
|
+
|
|
25
|
+
constructor(message: string, options: CubePodAPIErrorOptions);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export function parseAPIError(
|
|
29
|
+
response: Response,
|
|
30
|
+
context?: { sandboxId?: string },
|
|
31
|
+
): Promise<CubePodAPIError>;
|
package/src/errors.js
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Typed error hierarchy for the CubePod SDK.
|
|
3
|
+
*/
|
|
4
|
+
|
|
5
|
+
export class CubePodError extends Error {
|
|
6
|
+
/**
|
|
7
|
+
* @param {string} message
|
|
8
|
+
* @param {{ cause?: unknown }} [options]
|
|
9
|
+
*/
|
|
10
|
+
constructor(message, options = {}) {
|
|
11
|
+
super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
|
|
12
|
+
this.name = 'CubePodError';
|
|
13
|
+
}
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export class CubePodAPIError extends CubePodError {
|
|
17
|
+
/** @type {number} */
|
|
18
|
+
statusCode;
|
|
19
|
+
/** @type {string | number | undefined} */
|
|
20
|
+
code;
|
|
21
|
+
/** @type {string | undefined} */
|
|
22
|
+
sandboxId;
|
|
23
|
+
/** @type {unknown} */
|
|
24
|
+
body;
|
|
25
|
+
/** @type {string | undefined} */
|
|
26
|
+
logPath;
|
|
27
|
+
/** @type {string | undefined} */
|
|
28
|
+
details;
|
|
29
|
+
/** @type {string | undefined} */
|
|
30
|
+
step;
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* @param {string} message
|
|
34
|
+
* @param {{
|
|
35
|
+
* statusCode: number;
|
|
36
|
+
* code?: string | number;
|
|
37
|
+
* sandboxId?: string;
|
|
38
|
+
* body?: unknown;
|
|
39
|
+
* logPath?: string;
|
|
40
|
+
* details?: string;
|
|
41
|
+
* step?: string;
|
|
42
|
+
* cause?: unknown;
|
|
43
|
+
* }} options
|
|
44
|
+
*/
|
|
45
|
+
constructor(message, options) {
|
|
46
|
+
super(message, { cause: options.cause });
|
|
47
|
+
this.name = 'CubePodAPIError';
|
|
48
|
+
this.statusCode = options.statusCode;
|
|
49
|
+
this.code = options.code;
|
|
50
|
+
this.sandboxId = options.sandboxId;
|
|
51
|
+
this.body = options.body;
|
|
52
|
+
this.logPath = options.logPath;
|
|
53
|
+
this.details = options.details;
|
|
54
|
+
this.step = options.step;
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Parse an error Response into a CubePodAPIError.
|
|
60
|
+
*
|
|
61
|
+
* @param {Response} response
|
|
62
|
+
* @param {{ sandboxId?: string }} [context]
|
|
63
|
+
* @returns {Promise<CubePodAPIError>}
|
|
64
|
+
*/
|
|
65
|
+
export async function parseAPIError(response, context = {}) {
|
|
66
|
+
let rawText = '';
|
|
67
|
+
try {
|
|
68
|
+
rawText = await response.text();
|
|
69
|
+
} catch {
|
|
70
|
+
rawText = '';
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** @type {unknown} */
|
|
74
|
+
let body = rawText;
|
|
75
|
+
/** @type {string | number | undefined} */
|
|
76
|
+
let code;
|
|
77
|
+
/** @type {string | undefined} */
|
|
78
|
+
let sandboxId = context.sandboxId;
|
|
79
|
+
/** @type {string | undefined} */
|
|
80
|
+
let logPath;
|
|
81
|
+
/** @type {string | undefined} */
|
|
82
|
+
let details;
|
|
83
|
+
/** @type {string | undefined} */
|
|
84
|
+
let step;
|
|
85
|
+
let message = rawText.trim() || response.statusText || `HTTP ${response.status}`;
|
|
86
|
+
|
|
87
|
+
if (rawText) {
|
|
88
|
+
try {
|
|
89
|
+
const parsed = JSON.parse(rawText);
|
|
90
|
+
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
|
|
91
|
+
body = parsed;
|
|
92
|
+
if (typeof parsed.code === 'string' || typeof parsed.code === 'number') {
|
|
93
|
+
code = parsed.code;
|
|
94
|
+
} else if (typeof parsed.error === 'string') {
|
|
95
|
+
code = parsed.error;
|
|
96
|
+
}
|
|
97
|
+
if (typeof parsed.sandboxID === 'string') {
|
|
98
|
+
sandboxId = parsed.sandboxID;
|
|
99
|
+
} else if (typeof parsed.sandbox_id === 'string') {
|
|
100
|
+
sandboxId = parsed.sandbox_id;
|
|
101
|
+
}
|
|
102
|
+
if (typeof parsed.logPath === 'string') {
|
|
103
|
+
logPath = parsed.logPath;
|
|
104
|
+
} else if (typeof parsed.log_path === 'string') {
|
|
105
|
+
logPath = parsed.log_path;
|
|
106
|
+
}
|
|
107
|
+
if (typeof parsed.details === 'string') {
|
|
108
|
+
details = parsed.details;
|
|
109
|
+
}
|
|
110
|
+
if (parsed.reason && typeof parsed.reason === 'object') {
|
|
111
|
+
if (typeof parsed.reason.step === 'string') {
|
|
112
|
+
step = parsed.reason.step;
|
|
113
|
+
}
|
|
114
|
+
if (typeof parsed.reason.message === 'string' && parsed.reason.message) {
|
|
115
|
+
message = parsed.reason.message;
|
|
116
|
+
}
|
|
117
|
+
} else if (typeof parsed.message === 'string' && parsed.message) {
|
|
118
|
+
message = parsed.message;
|
|
119
|
+
} else if (typeof parsed.error === 'string' && parsed.error) {
|
|
120
|
+
message = parsed.error;
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
} catch {
|
|
124
|
+
// Keep plain-text response body as message.
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
return new CubePodAPIError(message, {
|
|
129
|
+
statusCode: response.status,
|
|
130
|
+
code,
|
|
131
|
+
sandboxId,
|
|
132
|
+
body,
|
|
133
|
+
logPath,
|
|
134
|
+
details,
|
|
135
|
+
step,
|
|
136
|
+
});
|
|
137
|
+
}
|
package/src/index.d.ts
ADDED
package/src/index.js
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { buildTarBytes, buildTarGzBytes, gzipBytes } from './archive.js';
|
|
2
|
+
export { CubePodClient, normalizeSandboxInfo } from './client.js';
|
|
3
|
+
export { CubePodAPIError, CubePodError, parseAPIError } from './errors.js';
|
|
4
|
+
export { readNdjsonStream } from './ndjson.js';
|
|
5
|
+
export { Sandbox } from './sandbox.js';
|
package/src/ndjson.d.ts
ADDED
package/src/ndjson.js
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* True streaming application/x-ndjson line reader handling arbitrary TCP chunk
|
|
3
|
+
* boundaries and multi-byte UTF-8 sequences.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import { CubePodError } from './errors.js';
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Stream and parse NDJSON objects from a ReadableStream<Uint8Array>.
|
|
10
|
+
*
|
|
11
|
+
* @template T
|
|
12
|
+
* @param {ReadableStream<Uint8Array>} stream
|
|
13
|
+
* @param {(item: T) => void | Promise<void>} onItem
|
|
14
|
+
* @returns {Promise<void>}
|
|
15
|
+
*/
|
|
16
|
+
export async function readNdjsonStream(stream, onItem) {
|
|
17
|
+
const reader = stream.getReader();
|
|
18
|
+
const decoder = new TextDecoder('utf-8');
|
|
19
|
+
let buffer = '';
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* @param {string} rawLine
|
|
23
|
+
*/
|
|
24
|
+
const dispatchLine = async (rawLine) => {
|
|
25
|
+
const trimmed = rawLine.trim();
|
|
26
|
+
if (!trimmed) return;
|
|
27
|
+
/** @type {T} */
|
|
28
|
+
let parsed;
|
|
29
|
+
try {
|
|
30
|
+
parsed = JSON.parse(trimmed);
|
|
31
|
+
} catch (cause) {
|
|
32
|
+
throw new CubePodError(`Invalid NDJSON frame: ${trimmed}`, { cause });
|
|
33
|
+
}
|
|
34
|
+
await onItem(parsed);
|
|
35
|
+
};
|
|
36
|
+
|
|
37
|
+
try {
|
|
38
|
+
while (true) {
|
|
39
|
+
const { value, done } = await reader.read();
|
|
40
|
+
if (done) {
|
|
41
|
+
buffer += decoder.decode();
|
|
42
|
+
break;
|
|
43
|
+
}
|
|
44
|
+
if (value && value.byteLength > 0) {
|
|
45
|
+
buffer += decoder.decode(value, { stream: true });
|
|
46
|
+
let nlIdx = buffer.indexOf('\n');
|
|
47
|
+
while (nlIdx !== -1) {
|
|
48
|
+
const line = buffer.slice(0, nlIdx);
|
|
49
|
+
buffer = buffer.slice(nlIdx + 1);
|
|
50
|
+
await dispatchLine(line);
|
|
51
|
+
nlIdx = buffer.indexOf('\n');
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
if (buffer.trim().length > 0) {
|
|
57
|
+
await dispatchLine(buffer);
|
|
58
|
+
}
|
|
59
|
+
} finally {
|
|
60
|
+
reader.releaseLock();
|
|
61
|
+
}
|
|
62
|
+
}
|
package/src/sandbox.d.ts
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import {
|
|
2
|
+
ArchiveSyncOptions,
|
|
3
|
+
CodeContext,
|
|
4
|
+
CommandLogs,
|
|
5
|
+
CommandResult,
|
|
6
|
+
CreateContextOptions,
|
|
7
|
+
CreateEndpointOptions,
|
|
8
|
+
CreateSandboxOptions,
|
|
9
|
+
CubePodClient,
|
|
10
|
+
CubePodClientOptions,
|
|
11
|
+
DeleteSandboxOptions,
|
|
12
|
+
EndpointHost,
|
|
13
|
+
ExecutionResult,
|
|
14
|
+
FileEntry,
|
|
15
|
+
ForkSandboxOptions,
|
|
16
|
+
GetCommandLogsOptions,
|
|
17
|
+
PanelEndpoint,
|
|
18
|
+
RequestOptions,
|
|
19
|
+
RunCodeOptions,
|
|
20
|
+
RunCommandOptions,
|
|
21
|
+
SandboxInfo,
|
|
22
|
+
SandboxState,
|
|
23
|
+
WriteFileOptions,
|
|
24
|
+
} from './client.js';
|
|
25
|
+
|
|
26
|
+
export interface SandboxClientConfig extends CubePodClientOptions {
|
|
27
|
+
client?: CubePodClient;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export interface SandboxCreateOptions extends CreateSandboxOptions, SandboxClientConfig {}
|
|
31
|
+
|
|
32
|
+
export interface SandboxConnectOptions extends RequestOptions, SandboxClientConfig {}
|
|
33
|
+
|
|
34
|
+
export interface SandboxCommands {
|
|
35
|
+
run(command: string, options?: RunCommandOptions): Promise<CommandResult>;
|
|
36
|
+
getStatus(cmdId: string, options?: RequestOptions): Promise<CommandResult>;
|
|
37
|
+
getLogs(cmdId: string, options?: number | GetCommandLogsOptions): Promise<CommandLogs>;
|
|
38
|
+
kill(cmdId: string, options?: RequestOptions): Promise<{ id: string; killed: boolean }>;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export interface SandboxCode {
|
|
42
|
+
runCode(code: string, options?: RunCodeOptions): Promise<ExecutionResult>;
|
|
43
|
+
createContext(contextOptions?: CreateContextOptions, options?: RequestOptions): Promise<CodeContext>;
|
|
44
|
+
listContexts(options?: RequestOptions): Promise<CodeContext[]>;
|
|
45
|
+
getContext(contextId: string, options?: RequestOptions): Promise<CodeContext>;
|
|
46
|
+
restartContext(contextId: string, options?: RequestOptions): Promise<CodeContext>;
|
|
47
|
+
deleteContext(contextId: string, options?: RequestOptions): Promise<void>;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export interface SandboxFiles {
|
|
51
|
+
write(
|
|
52
|
+
path: string,
|
|
53
|
+
content: string | Uint8Array | ArrayBuffer,
|
|
54
|
+
options?: WriteFileOptions,
|
|
55
|
+
): Promise<{ status?: string; path: string; size: number }>;
|
|
56
|
+
readText(path: string, options?: RequestOptions): Promise<string>;
|
|
57
|
+
readBytes(path: string, options?: RequestOptions): Promise<Uint8Array>;
|
|
58
|
+
remove(path: string, options?: RequestOptions): Promise<{ status?: string; deleted?: string }>;
|
|
59
|
+
list(path?: string, options?: RequestOptions): Promise<FileEntry[]>;
|
|
60
|
+
archiveSync(
|
|
61
|
+
archiveOrFiles: Uint8Array | ArrayBuffer | Record<string, string | Uint8Array | ArrayBuffer>,
|
|
62
|
+
options?: ArchiveSyncOptions,
|
|
63
|
+
): Promise<{ status: string; extracted?: number }>;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
export class Sandbox {
|
|
67
|
+
readonly client: CubePodClient;
|
|
68
|
+
readonly sandboxId: string;
|
|
69
|
+
info: SandboxInfo;
|
|
70
|
+
readonly commands: SandboxCommands;
|
|
71
|
+
readonly code: SandboxCode;
|
|
72
|
+
readonly files: SandboxFiles;
|
|
73
|
+
|
|
74
|
+
constructor(client: CubePodClient, info: SandboxInfo);
|
|
75
|
+
|
|
76
|
+
get templateId(): string;
|
|
77
|
+
get state(): SandboxState;
|
|
78
|
+
|
|
79
|
+
static create(options?: SandboxCreateOptions): Promise<Sandbox>;
|
|
80
|
+
static create(templateId: string, options?: SandboxCreateOptions): Promise<Sandbox>;
|
|
81
|
+
static connect(sandboxId: string, options?: SandboxConnectOptions): Promise<Sandbox>;
|
|
82
|
+
|
|
83
|
+
refresh(options?: RequestOptions): Promise<SandboxInfo>;
|
|
84
|
+
connect(options?: RequestOptions): Promise<SandboxInfo>;
|
|
85
|
+
pause(options?: RequestOptions): Promise<SandboxInfo>;
|
|
86
|
+
setTimeout(timeoutSeconds: number, options?: RequestOptions): Promise<SandboxInfo>;
|
|
87
|
+
acquireLease(leaseSeconds?: number, options?: RequestOptions): Promise<SandboxInfo>;
|
|
88
|
+
resetRootfs(options?: RequestOptions): Promise<SandboxInfo>;
|
|
89
|
+
fork(forkOptions?: ForkSandboxOptions, options?: RequestOptions): Promise<Sandbox>;
|
|
90
|
+
kill(deleteOptions?: DeleteSandboxOptions, options?: RequestOptions): Promise<void>;
|
|
91
|
+
getHost(port: number, options?: RequestOptions): Promise<string>;
|
|
92
|
+
getEndpointHost(port: number, options?: RequestOptions): Promise<EndpointHost>;
|
|
93
|
+
createEndpoint(
|
|
94
|
+
port: number,
|
|
95
|
+
endpointOptions?: CreateEndpointOptions,
|
|
96
|
+
options?: RequestOptions,
|
|
97
|
+
): Promise<PanelEndpoint>;
|
|
98
|
+
}
|
package/src/sandbox.js
ADDED
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
import { CubePodClient } from './client.js';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Resolve a CubePodClient from options, reusing `options.client` when provided.
|
|
5
|
+
*
|
|
6
|
+
* @param {import('./sandbox.d.ts').SandboxClientConfig} [options]
|
|
7
|
+
* @returns {CubePodClient}
|
|
8
|
+
*/
|
|
9
|
+
function resolveClient(options = {}) {
|
|
10
|
+
if (options.client) return options.client;
|
|
11
|
+
return new CubePodClient({
|
|
12
|
+
baseUrl: options.baseUrl,
|
|
13
|
+
apiKey: options.apiKey,
|
|
14
|
+
timeoutMs: options.timeoutMs,
|
|
15
|
+
maxRetries: options.maxRetries,
|
|
16
|
+
retryDelayMs: options.retryDelayMs,
|
|
17
|
+
fetch: options.fetch,
|
|
18
|
+
headers: options.headers,
|
|
19
|
+
});
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Stateful Sandbox handle with scoped `.commands`, `.code`, and `.files` namespaces.
|
|
24
|
+
*/
|
|
25
|
+
export class Sandbox {
|
|
26
|
+
/** @type {CubePodClient} */
|
|
27
|
+
client;
|
|
28
|
+
/** @type {string} */
|
|
29
|
+
sandboxId;
|
|
30
|
+
/** @type {import('./client.d.ts').SandboxInfo} */
|
|
31
|
+
info;
|
|
32
|
+
/** @type {import('./sandbox.d.ts').SandboxCommands} */
|
|
33
|
+
commands;
|
|
34
|
+
/** @type {import('./sandbox.d.ts').SandboxCode} */
|
|
35
|
+
code;
|
|
36
|
+
/** @type {import('./sandbox.d.ts').SandboxFiles} */
|
|
37
|
+
files;
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* @param {CubePodClient} client
|
|
41
|
+
* @param {import('./client.d.ts').SandboxInfo} info
|
|
42
|
+
*/
|
|
43
|
+
constructor(client, info) {
|
|
44
|
+
this.client = client;
|
|
45
|
+
this.sandboxId = info.sandboxId;
|
|
46
|
+
this.info = info;
|
|
47
|
+
|
|
48
|
+
this.commands = {
|
|
49
|
+
run: (command, options) => this.client.runCommand(this.sandboxId, command, options),
|
|
50
|
+
getStatus: (cmdId, options) => this.client.getCommandStatus(this.sandboxId, cmdId, options),
|
|
51
|
+
getLogs: (cmdId, options) => this.client.getCommandLogs(this.sandboxId, cmdId, options),
|
|
52
|
+
kill: (cmdId, options) => this.client.killCommand(this.sandboxId, cmdId, options),
|
|
53
|
+
};
|
|
54
|
+
|
|
55
|
+
this.code = {
|
|
56
|
+
runCode: (code, options) => this.client.runCode(this.sandboxId, code, options),
|
|
57
|
+
createContext: (contextOptions, options) =>
|
|
58
|
+
this.client.createContext(this.sandboxId, contextOptions, options),
|
|
59
|
+
listContexts: (options) => this.client.listContexts(this.sandboxId, options),
|
|
60
|
+
getContext: (contextId, options) =>
|
|
61
|
+
this.client.getContext(this.sandboxId, contextId, options),
|
|
62
|
+
restartContext: (contextId, options) =>
|
|
63
|
+
this.client.restartContext(this.sandboxId, contextId, options),
|
|
64
|
+
deleteContext: (contextId, options) =>
|
|
65
|
+
this.client.deleteContext(this.sandboxId, contextId, options),
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
this.files = {
|
|
69
|
+
write: (path, content, options) =>
|
|
70
|
+
this.client.writeFile(this.sandboxId, path, content, options),
|
|
71
|
+
readText: (path, options) => this.client.readFileText(this.sandboxId, path, options),
|
|
72
|
+
readBytes: (path, options) => this.client.readFileBytes(this.sandboxId, path, options),
|
|
73
|
+
remove: (path, options) => this.client.removeFile(this.sandboxId, path, options),
|
|
74
|
+
list: (path, options) => this.client.listFiles(this.sandboxId, path, options),
|
|
75
|
+
archiveSync: (archiveOrFiles, options) =>
|
|
76
|
+
this.client.archiveSync(this.sandboxId, archiveOrFiles, options),
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** @returns {string} */
|
|
81
|
+
get templateId() {
|
|
82
|
+
return this.info.templateId;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** @returns {import('./client.d.ts').SandboxState} */
|
|
86
|
+
get state() {
|
|
87
|
+
return this.info.state;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* Create a new sandbox and return a connected Sandbox handle.
|
|
92
|
+
*
|
|
93
|
+
* @param {string | import('./sandbox.d.ts').SandboxCreateOptions} [templateOrOptions]
|
|
94
|
+
* @param {import('./sandbox.d.ts').SandboxCreateOptions} [extraOptions]
|
|
95
|
+
* @returns {Promise<Sandbox>}
|
|
96
|
+
*/
|
|
97
|
+
static async create(templateOrOptions, extraOptions) {
|
|
98
|
+
/** @type {import('./sandbox.d.ts').SandboxCreateOptions} */
|
|
99
|
+
const opts =
|
|
100
|
+
typeof templateOrOptions === 'string'
|
|
101
|
+
? { ...(extraOptions ?? {}), templateId: templateOrOptions }
|
|
102
|
+
: { ...(templateOrOptions ?? {}) };
|
|
103
|
+
|
|
104
|
+
const client = resolveClient(opts);
|
|
105
|
+
const info = await client.createSandbox(opts);
|
|
106
|
+
return new Sandbox(client, info);
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Connect to an existing sandbox (auto-resuming if Paused).
|
|
111
|
+
*
|
|
112
|
+
* @param {string} sandboxId
|
|
113
|
+
* @param {import('./sandbox.d.ts').SandboxConnectOptions} [options]
|
|
114
|
+
* @returns {Promise<Sandbox>}
|
|
115
|
+
*/
|
|
116
|
+
static async connect(sandboxId, options = {}) {
|
|
117
|
+
const client = resolveClient(options);
|
|
118
|
+
const info = await client.connectSandbox(sandboxId, { signal: options.signal });
|
|
119
|
+
return new Sandbox(client, info);
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Refresh cached sandbox metadata from the Gateway.
|
|
124
|
+
*
|
|
125
|
+
* @param {import('./client.d.ts').RequestOptions} [options]
|
|
126
|
+
* @returns {Promise<import('./client.d.ts').SandboxInfo>}
|
|
127
|
+
*/
|
|
128
|
+
async refresh(options = {}) {
|
|
129
|
+
this.info = await this.client.getSandbox(this.sandboxId, options);
|
|
130
|
+
return this.info;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Connect / resume this sandbox if currently Paused.
|
|
135
|
+
*
|
|
136
|
+
* @param {import('./client.d.ts').RequestOptions} [options]
|
|
137
|
+
* @returns {Promise<import('./client.d.ts').SandboxInfo>}
|
|
138
|
+
*/
|
|
139
|
+
async connect(options = {}) {
|
|
140
|
+
this.info = await this.client.connectSandbox(this.sandboxId, options);
|
|
141
|
+
return this.info;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* Pause the sandbox, stopping compute while preserving RootFS & Workspace PVCs.
|
|
146
|
+
*
|
|
147
|
+
* @param {import('./client.d.ts').RequestOptions} [options]
|
|
148
|
+
* @returns {Promise<import('./client.d.ts').SandboxInfo>}
|
|
149
|
+
*/
|
|
150
|
+
async pause(options = {}) {
|
|
151
|
+
this.info = await this.client.pauseSandbox(this.sandboxId, options);
|
|
152
|
+
return this.info;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* Set the idle auto-pause timeout in seconds.
|
|
157
|
+
*
|
|
158
|
+
* @param {number} timeoutSeconds
|
|
159
|
+
* @param {import('./client.d.ts').RequestOptions} [options]
|
|
160
|
+
* @returns {Promise<import('./client.d.ts').SandboxInfo>}
|
|
161
|
+
*/
|
|
162
|
+
async setTimeout(timeoutSeconds, options = {}) {
|
|
163
|
+
this.info = await this.client.setSandboxTimeout(this.sandboxId, timeoutSeconds, options);
|
|
164
|
+
return this.info;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* Acquire or renew a lease protecting against automatic idle pause.
|
|
169
|
+
*
|
|
170
|
+
* @param {number} [leaseSeconds=300]
|
|
171
|
+
* @param {import('./client.d.ts').RequestOptions} [options]
|
|
172
|
+
* @returns {Promise<import('./client.d.ts').SandboxInfo>}
|
|
173
|
+
*/
|
|
174
|
+
async acquireLease(leaseSeconds = 300, options = {}) {
|
|
175
|
+
this.info = await this.client.acquireLease(this.sandboxId, leaseSeconds, options);
|
|
176
|
+
return this.info;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Reset RootFS Upper to a clean base image while keeping `/workspace` intact.
|
|
181
|
+
*
|
|
182
|
+
* @param {import('./client.d.ts').RequestOptions} [options]
|
|
183
|
+
* @returns {Promise<import('./client.d.ts').SandboxInfo>}
|
|
184
|
+
*/
|
|
185
|
+
async resetRootfs(options = {}) {
|
|
186
|
+
this.info = await this.client.resetRootfs(this.sandboxId, options);
|
|
187
|
+
return this.info;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* Fork this sandbox via Copy-on-Write block snapshots and return the child Sandbox.
|
|
192
|
+
*
|
|
193
|
+
* @param {import('./client.d.ts').ForkSandboxOptions} [forkOptions]
|
|
194
|
+
* @param {import('./client.d.ts').RequestOptions} [options]
|
|
195
|
+
* @returns {Promise<Sandbox>}
|
|
196
|
+
*/
|
|
197
|
+
async fork(forkOptions = {}, options = {}) {
|
|
198
|
+
const childInfo = await this.client.forkSandbox(this.sandboxId, forkOptions, options);
|
|
199
|
+
return new Sandbox(this.client, childInfo);
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* Kill and delete this sandbox.
|
|
204
|
+
*
|
|
205
|
+
* @param {import('./client.d.ts').DeleteSandboxOptions} [deleteOptions]
|
|
206
|
+
* @param {import('./client.d.ts').RequestOptions} [options]
|
|
207
|
+
* @returns {Promise<void>}
|
|
208
|
+
*/
|
|
209
|
+
async kill(deleteOptions = {}, options = {}) {
|
|
210
|
+
await this.client.deleteSandbox(this.sandboxId, deleteOptions, options);
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/**
|
|
214
|
+
* Get the public ingress host string for a sandbox port (E2B `getHost` compatible).
|
|
215
|
+
*
|
|
216
|
+
* @param {number} port
|
|
217
|
+
* @param {import('./client.d.ts').RequestOptions} [options]
|
|
218
|
+
* @returns {Promise<string>}
|
|
219
|
+
*/
|
|
220
|
+
async getHost(port, options = {}) {
|
|
221
|
+
return this.client.getHost(this.sandboxId, port, options);
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/**
|
|
225
|
+
* Get full ingress host/URL metadata for a sandbox port.
|
|
226
|
+
*
|
|
227
|
+
* @param {number} port
|
|
228
|
+
* @param {import('./client.d.ts').RequestOptions} [options]
|
|
229
|
+
* @returns {Promise<import('./client.d.ts').EndpointHost>}
|
|
230
|
+
*/
|
|
231
|
+
async getEndpointHost(port, options = {}) {
|
|
232
|
+
return this.client.getEndpointHost(this.sandboxId, port, options);
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* Mint an HMAC-SHA256 signed `/panel/{token}/` proxy endpoint for a sandbox port.
|
|
237
|
+
*
|
|
238
|
+
* @param {number} port
|
|
239
|
+
* @param {import('./client.d.ts').CreateEndpointOptions} [endpointOptions]
|
|
240
|
+
* @param {import('./client.d.ts').RequestOptions} [options]
|
|
241
|
+
* @returns {Promise<import('./client.d.ts').PanelEndpoint>}
|
|
242
|
+
*/
|
|
243
|
+
async createEndpoint(port, endpointOptions = {}, options = {}) {
|
|
244
|
+
return this.client.createEndpoint(this.sandboxId, port, endpointOptions, options);
|
|
245
|
+
}
|
|
246
|
+
}
|