@boxrouter/sdk 0.0.1-alpha.0 → 0.12.190

package/dist/sandboxes.js

@@ -0,0 +1,507 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SandboxFiles = exports.ProcessHandle = exports.SandboxProcesses = exports.SandboxPreviews = exports.SandboxHandle = exports.SandboxResources = void 0;
+exports.mutationOptions = mutationOptions;
+exports.decodeBase64 = decodeBase64;
+const command_check_gen_1 = require("./command-check.gen");
+const command_input_gen_1 = require("./command-input.gen");
+const api_error_1 = require("./api-error");
+const terminal_1 = require("./terminal");
+const launch_1 = require("./launch");
+const transfer_1 = require("./transfer");
+const creation_gen_1 = require("./creation.gen");
+const sandbox_handle_gen_1 = require("./sandbox-handle.gen");
+const data_origin_1 = require("./data-origin");
+const workflow_policy_gen_1 = require("./workflow-policy.gen");
+function mutationOptions({ signal, idempotencyKey }) {
+    return {
+        signal,
+        headers: idempotencyKey === undefined ? undefined : { 'Idempotency-Key': idempotencyKey },
+    };
+}
+function decodeBase64(value) {
+    const decoded = atob(value);
+    return Uint8Array.from(decoded, character => character.charCodeAt(0));
+}
+/** Provider-neutral sandbox operations. */
+class SandboxResources {
+    api;
+    constructor(api) {
+        this.api = api;
+    }
+    async agents(options = {}) {
+        return this.api.agents.list({ signal: options.signal });
+    }
+    async create(config, options = {}) {
+        const sandbox = await this.api.sandboxes.create({ body: (0, creation_gen_1.creationBody)(config), ...mutationOptions(options) });
+        return new SandboxHandle(this.api, sandbox);
+    }
+    /** Explain which routes creation would use for the same config, without creating anything. */
+    async match(config, options = {}) {
+        return this.api.sandboxes.match({ body: (0, creation_gen_1.matchBody)(config), signal: options.signal });
+    }
+    /** Read a sandbox's live state from Cloud and return its handle. */
+    async get(id, options = {}) {
+        const sandbox = await this.api.sandboxes.get({ path: { sandbox_id: id }, signal: options.signal });
+        return new SandboxHandle(this.api, sandbox);
+    }
+    /** One page of the caller's sandboxes; the query filters and pages as the list operation defines. */
+    async list(query, options = {}) {
+        return this.api.sandboxes.list({ query, signal: options.signal });
+    }
+    /** Open a PTY shell by sandbox ID, or attach with terminalId; the shell keeps running afterwards. */
+    openTerminal(id, options = {}) {
+        return (0, terminal_1.openTerminal)(this.api, id, options);
+    }
+    async launch(agentOrOptions = {}, maybeOptions = {}) {
+        const [agent, options] = typeof agentOrOptions === 'string'
+            ? [agentOrOptions, maybeOptions] : [undefined, agentOrOptions];
+        const { launch, terminalCommand } = await (0, launch_1.launchAgent)(this.api, agent, options);
+        let sandbox;
+        try {
+            sandbox = await this.api.sandboxes.get({ path: { sandbox_id: launch.sandbox_id }, signal: options.signal });
+        }
+        catch (error) {
+            // The launch succeeded: say which sandbox it made so the caller can read or destroy it.
+            if (error instanceof Error)
+                error.message += `\nSandbox ID: ${launch.sandbox_id}`;
+            throw error;
+        }
+        return new SandboxHandle(this.api, sandbox, { launch, terminalCommand });
+    }
+}
+exports.SandboxResources = SandboxResources;
+/**
+ * A bound sandbox. Its properties are the Sandbox fields (`state`, `lifetime`, `route`, ...) as
+ * of the last response: `get` returns a handle, `refresh` reads again, and `destroy`, `pause`,
+ * `resume` and `extend` update it. Every handle has every method: a sandbox created without the
+ * requirement a method needs answers with an `APIError` whose code is `not_named`.
+ */
+class SandboxHandle {
+    #sandbox;
+    #terminalObservers = new Set();
+    #terminalCommand;
+    /** The launch result when `sandboxes.launch` returned this handle (with `interactive` resolved), otherwise undefined. */
+    launch;
+    files;
+    processes;
+    previews;
+    api;
+    static {
+        (0, sandbox_handle_gen_1.defineSandboxFields)(SandboxHandle, handle => handle.#sandbox);
+    }
+    constructor(api, sandbox, launched) {
+        this.api = api;
+        this.#sandbox = sandbox;
+        this.launch = launched?.launch;
+        this.#terminalCommand = launched?.terminalCommand;
+        const limits = sandbox.limits;
+        this.files = new SandboxFiles(api, sandbox.id, limits?.inline_transfer_max_bytes);
+        this.processes = new SandboxProcesses(api, sandbox.id);
+        this.previews = new SandboxPreviews(api, sandbox.id);
+    }
+    #registerTerminalObserver(close) {
+        this.#terminalObservers.add(close);
+        return () => this.#terminalObservers.delete(close);
+    }
+    async [Symbol.asyncDispose]() {
+        await this.destroy();
+    }
+    /** Read the sandbox again from Cloud and update this handle's properties. */
+    async refresh(options = {}) {
+        this.#sandbox = await this.api.sandboxes.get({ path: { sandbox_id: this.#sandbox.id }, signal: options.signal });
+        return this;
+    }
+    /**
+     * Open a PTY shell in this sandbox, or attach with terminalId. After `sandboxes.launch`, a new shell starts
+     * the launch's command (written first, with a 3600 s timeout unless you give one).
+     */
+    async openTerminal(options = {}) {
+        const command = options.terminalId === undefined ? this.#terminalCommand : undefined;
+        const terminal = await (0, terminal_1.openTerminal)(this.api, this.id, {
+            ...options, timeoutSeconds: options.timeoutSeconds ?? (command === undefined ? undefined : 3600),
+        }, close => this.#registerTerminalObserver(close));
+        if (command !== undefined) {
+            await terminal.write(new TextEncoder().encode(`${command}\n`), { signal: options.signal });
+        }
+        return terminal;
+    }
+    async exec(command, { check, ...config } = {}, options = {}) {
+        const body = { ...config, command };
+        (0, command_input_gen_1.validateCommand)(body);
+        const result = await this.api.commands.run({
+            path: { sandbox_id: this.id }, body, ...mutationOptions(options),
+        });
+        if (config.output !== 'bytes')
+            return (0, command_check_gen_1.checkedCommand)(result, check);
+        if (!('stdout_base64' in result) || !('stderr_base64' in result)) {
+            throw new TypeError('Unexpected BoxRouter response: expected byte command output');
+        }
+        const { stdout_base64, stderr_base64, ...metadata } = result;
+        return (0, command_check_gen_1.checkedCommand)({ ...metadata, stdout: decodeBase64(stdout_base64), stderr: decodeBase64(stderr_base64) }, check);
+    }
+    async saveVolume(...[options = {}]) {
+        const volumeId = this.volume?.id;
+        if (!volumeId)
+            throw new TypeError('Sandbox does not identify an attached BoxRouter Volume');
+        const { signal, idempotencyKey, ...fields } = options;
+        return this.api.volumes.save({ path: { volume_id: volumeId }, body: (0, creation_gen_1.volumeSaveBody)({ ...fields, sandboxId: this.id }),
+            ...mutationOptions({ signal, idempotencyKey }) });
+    }
+    /**
+     * Request destruction and update this handle from the sandbox Cloud returns: `destroyed`, or
+     * `destroying` with an `operation_id` while Cloud finishes the destroy without the caller.
+     */
+    async destroy(options = {}) {
+        const { discardUnsaved, ...mutation } = options;
+        const failures = [];
+        try {
+            (0, terminal_1.closeObservers)(this.#terminalObservers);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            this.#sandbox = await this.api.sandboxes.destroy({ path: { sandbox_id: this.id },
+                query: { discard_unsaved: discardUnsaved }, ...mutationOptions(mutation) });
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        if (failures.length)
+            throw (0, terminal_1.combineCleanupErrors)(failures, 'Sandbox cleanup failed');
+        return this.#sandbox;
+    }
+    /** Pause the sandbox; the handle's `state` and `lifetime` follow the response. */
+    async pause(options = {}) {
+        const paused = await this.api.sandboxes.pause({ path: { sandbox_id: this.id }, ...mutationOptions(options) });
+        this.#sandbox = { ...this.#sandbox, state: paused.state, lifetime: paused.lifetime };
+        return paused;
+    }
+    /** Resume the sandbox; undefined means it was already running (204), and nothing changes. */
+    async resume(options = {}) {
+        const resumed = await this.api.sandboxes.resume({ path: { sandbox_id: this.id }, ...mutationOptions(options) });
+        if (resumed === undefined)
+            return undefined;
+        this.#sandbox = { ...this.#sandbox, state: resumed.state, lifetime: resumed.lifetime };
+        return resumed;
+    }
+    /** Set the sandbox's new total running-time budget in seconds (not an increment). */
+    async extend(body, options = {}) {
+        const lifetime = await this.api.sandboxes.extend({ path: { sandbox_id: this.id }, body, ...mutationOptions(options) });
+        this.#sandbox = { ...this.#sandbox, lifetime };
+        return lifetime;
+    }
+}
+exports.SandboxHandle = SandboxHandle;
+/** Previews of one sandbox. */
+class SandboxPreviews {
+    api;
+    id;
+    constructor(api, id) {
+        this.api = api;
+        this.id = id;
+    }
+    /** Open a preview of `port`, which the sandbox's previews requirement must name. */
+    async open(port, config = {}, options = {}) {
+        return this.api.previews.open({ path: { sandbox_id: this.id }, body: { ...config, port }, ...mutationOptions(options) });
+    }
+}
+exports.SandboxPreviews = SandboxPreviews;
+const WAIT_POLL_MS = workflow_policy_gen_1.PROCESS_WAIT_POLL_INTERVAL_SECONDS * 1000;
+/** What a command result carries that a process does not: the same value for every process. */
+const FIXED_RESULT = JSON.parse(workflow_policy_gen_1.PROCESS_WAIT_FIXED_RESULT_JSON);
+function joined(pages) {
+    const bytes = new Uint8Array(pages.reduce((total, page) => total + page.length, 0));
+    let at = 0;
+    for (const page of pages) {
+        bytes.set(page, at);
+        at += page.length;
+    }
+    return bytes;
+}
+/** Node's longest timer delay. */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/** Background commands bound to one sandbox. */
+class SandboxProcesses {
+    api;
+    id;
+    constructor(api, id) {
+        this.api = api;
+        this.id = id;
+    }
+    async start(command, config = {}, options = {}) {
+        const body = { ...config, command };
+        (0, command_input_gen_1.validateProcess)(body);
+        const { id } = await this.api.processes.start({
+            path: { sandbox_id: this.id }, body, ...mutationOptions(options),
+        });
+        return new ProcessHandle(this.api, this.id, id);
+    }
+    /** A handle for a started process. */
+    fromId(processId) {
+        return new ProcessHandle(this.api, this.id, processId);
+    }
+}
+exports.SandboxProcesses = SandboxProcesses;
+function offset(name, value) {
+    const bytes = Number(value);
+    if (!Number.isSafeInteger(bytes) || bytes < 0)
+        throw new TypeError(`${name} must be a non-negative integer byte offset`);
+    return bytes;
+}
+/** A started command, addressed by its durable ID. Nothing here cancels it implicitly. */
+class ProcessHandle {
+    api;
+    #path;
+    constructor(api, sandboxId, processId) {
+        this.api = api;
+        this.#path = { sandbox_id: sandboxId, process_id: processId };
+    }
+    get id() { return this.#path.process_id; }
+    /**
+     * Output from the given byte offsets; continue from next_stdout and next_stderr.
+     * exit_code is set once the process ended and both streams were read to their ends.
+     */
+    async read(options = {}) {
+        return this.api.processes.read({
+            path: this.#path,
+            query: { stdout: offset('stdout', options.stdout ?? 0), stderr: offset('stderr', options.stderr ?? 0) },
+            signal: options.signal,
+        });
+    }
+    async wait(options = {}) {
+        if (options.output !== undefined && options.output !== 'text' && options.output !== 'bytes') {
+            throw new TypeError("output must be 'text' or 'bytes'");
+        }
+        const deadline = options.timeoutSeconds === undefined ? Infinity : Date.now() + options.timeoutSeconds * 1000;
+        const readBefore = async (stdout, stderr) => {
+            const expired = () => new DOMException(`Process ${this.id} did not exit within ${options.timeoutSeconds} seconds`, 'TimeoutError');
+            const left = deadline - Date.now();
+            if (left <= 0)
+                throw expired();
+            // Node fires timers longer than its maximum delay at once, so those reads rely on the checks.
+            const timer = left <= MAX_TIMER_MS ? AbortSignal.timeout(Math.ceil(left)) : undefined;
+            const signals = [options.signal, timer].filter(signal => signal !== undefined);
+            try {
+                const output = await this.read({ stdout, stderr, signal: signals.length > 1 ? AbortSignal.any(signals) : signals[0] });
+                if (Date.now() >= deadline)
+                    throw expired();
+                return output;
+            }
+            catch (error) {
+                if (timer?.aborted && !options.signal?.aborted)
+                    throw expired();
+                throw error;
+            }
+        };
+        let output = await readBefore(options.stdout ?? 0, options.stderr ?? 0);
+        const stdout = [decodeBase64(output.stdout_base64)];
+        const stderr = [decodeBase64(output.stderr_base64)];
+        while (output.exit_code === null) {
+            await new Promise(resolve => setTimeout(resolve, Math.max(0, Math.min(WAIT_POLL_MS, deadline - Date.now()))));
+            output = await readBefore(output.next_stdout, output.next_stderr);
+            stdout.push(decodeBase64(output.stdout_base64));
+            stderr.push(decodeBase64(output.stderr_base64));
+        }
+        const exit = { exit_code: output.exit_code, ...FIXED_RESULT };
+        if (options.output === 'bytes')
+            return { stdout: joined(stdout), stderr: joined(stderr), ...exit };
+        // Decoded once, after the pages are joined, so a character split between pages survives.
+        const text = new TextDecoder();
+        return { stdout: text.decode(joined(stdout)), stderr: text.decode(joined(stderr)), ...exit };
+    }
+    /** Appends text to stdin; the process must have started with stdin: true. */
+    async writeStdin(data, options = {}) {
+        await this.api.processes.writeStdin({ path: this.#path, body: { data }, ...mutationOptions(options) });
+    }
+    async closeStdin(options = {}) {
+        await this.api.processes.closeStdin({ path: this.#path, signal: options.signal });
+    }
+    /** Requests termination; wait() or read() confirms the exit. */
+    async cancel(options = {}) {
+        await this.api.processes.cancel({ path: this.#path, ...mutationOptions(options) });
+    }
+    /** Deletes the retained output of a finished process. */
+    async remove(options = {}) {
+        await this.api.processes.remove({ path: this.#path, ...mutationOptions(options) });
+    }
+}
+exports.ProcessHandle = ProcessHandle;
+// Mirrors the `file_transfer_bytes` default in the OpenAPI capabilities limits: the largest file
+// `readFile` and `writeFile` carry in one request.
+const SMALL_FILE_LIMIT = 1_048_576;
+function fileOutputLimit(error) {
+    // `output_limit` is the earlier name some routes still return for the same refusal.
+    return error instanceof api_error_1.APIError && error.status === 413 && (error.code === 'resource_limit' || error.code === 'output_limit');
+}
+// The three upload calls require an Idempotency-Key. Each gets its own key derived from one base key:
+// the caller's, or a fresh UUID when the caller gave none.
+function operationOptions(base, signal, operation) {
+    const suffix = `:${operation}`;
+    return { signal, headers: { 'Idempotency-Key': `${base.slice(0, 128 - suffix.length)}${suffix}` } };
+}
+class SandboxFiles {
+    api;
+    id;
+    inlineTransferMaxBytes;
+    constructor(api, id, inlineTransferMaxBytes) {
+        this.api = api;
+        this.id = id;
+        this.inlineTransferMaxBytes = inlineTransferMaxBytes;
+    }
+    /** The route's advertised inline size, capped at the inline read's own bound. */
+    inlineBelow() {
+        return this.inlineTransferMaxBytes === undefined
+            ? undefined
+            : Math.min(this.inlineTransferMaxBytes, 5 * 1024 * 1024);
+    }
+    async list(path, options = {}) {
+        return this.api.files.list({
+            path: { sandbox_id: this.id }, query: { path }, signal: options.signal,
+        });
+    }
+    async exists(path, options = {}) {
+        return this.api.files.exists({
+            path: { sandbox_id: this.id }, query: { path }, signal: options.signal,
+        });
+    }
+    async mkdir(path, options = {}) {
+        await this.api.files.mkdir({
+            path: { sandbox_id: this.id }, body: { path, parents: options.parents },
+            ...mutationOptions(options),
+        });
+    }
+    async remove(path, options = {}) {
+        await this.api.files.remove({
+            path: { sandbox_id: this.id }, body: { path, recursive: options.recursive },
+            ...mutationOptions(options),
+        });
+    }
+    async read(path, options = {}) {
+        const inline = this.inlineBelow();
+        if (inline !== undefined) {
+            // The route advertises one inline request: the body or a transfer link.
+            const answer = await this.api.files.createDownload({
+                path: { sandbox_id: this.id },
+                body: { path, inline_below: inline },
+                signal: options.signal,
+            });
+            if (answer.content !== undefined)
+                return decodeBase64(answer.content);
+            const stream = await this.download(path, undefined, options);
+            return new Uint8Array(await new Response(stream).arrayBuffer());
+        }
+        try {
+            const bytes = await this.api.files.read({
+                path: { sandbox_id: this.id }, query: { path }, parseAs: 'blob', signal: options.signal,
+                ...(0, data_origin_1.dataOriginOptions)(this.api, true),
+            });
+            return new Uint8Array(await bytes.arrayBuffer());
+        }
+        catch (error) {
+            if (!fileOutputLimit(error))
+                throw error;
+        }
+        // Over the small-file limit: the same bytes through the download flow, into memory.
+        const stream = await this.download(path, undefined, options);
+        return new Uint8Array(await new Response(stream).arrayBuffer());
+    }
+    async write(path, content, options = {}) {
+        const bytes = typeof content === 'string' ? new TextEncoder().encode(content) : content;
+        if ((bytes instanceof Blob ? bytes.size : bytes.byteLength) > SMALL_FILE_LIMIT) {
+            await this.upload(bytes, path, options);
+            return;
+        }
+        await this.api.files.write({
+            path: { sandbox_id: this.id }, query: { path },
+            body: bytes instanceof Blob ? bytes : new Blob([bytes]),
+            ...(0, data_origin_1.dataOriginOptions)(this.api, (bytes instanceof Blob ? bytes.size : bytes.byteLength) >= data_origin_1.LARGE_WRITE_BYTES),
+            ...mutationOptions(options),
+        });
+    }
+    /**
+     * Upload a local file path, Blob, bytes or stream to `remotePath`. A stream needs `size`. The request
+     * carries the exact length, so a stream is first spooled to a temporary file (never into memory).
+     * `progress` is called as each part finishes. An upload that fails before completion is sent is aborted;
+     * one that fails after is left as it is, its outcome unknown. Bytes already written may remain.
+     */
+    async upload(source, remotePath, options = {}) {
+        const opened = await (0, transfer_1.openSource)({ source, size: options.size }, options.signal);
+        const baseKey = options.idempotencyKey ?? globalThis.crypto.randomUUID();
+        try {
+            const session = await this.api.files.createUpload({
+                path: { sandbox_id: this.id }, body: { path: remotePath, size: opened.size },
+                ...operationOptions(baseKey, options.signal, 'create'),
+            });
+            let completing = false;
+            try {
+                const parts = await (0, transfer_1.sendParts)(opened, session.parts, {
+                    concurrency: options.concurrency ?? 4, replayParts: false, label: 'Sandbox',
+                    progress: options.progress, signal: options.signal,
+                });
+                completing = true;
+                // The completion key is fixed up front, so every retry of an unknown outcome reuses it.
+                const complete = operationOptions(baseKey, options.signal, 'complete');
+                await (0, transfer_1.retryCompletion)(() => this.api.files.completeUpload({
+                    path: { sandbox_id: this.id, upload_id: session.id }, body: { parts }, ...complete,
+                }), options.signal);
+            }
+            catch (error) {
+                // Once completion was sent the upload may be finished: abort is for uploads that never were.
+                if (!completing) {
+                    try {
+                        await this.api.files.abortUpload({
+                            path: { sandbox_id: this.id, upload_id: session.id },
+                            ...operationOptions(baseKey, undefined, 'abort'),
+                        });
+                    }
+                    catch {
+                        // Preserve the failure that caused cleanup.
+                    }
+                }
+                throw error;
+            }
+        }
+        finally {
+            await opened.close();
+        }
+    }
+    async download(remotePath, localPath, options = {}) {
+        const inline = this.inlineBelow();
+        const answer = await this.api.files.createDownload({
+            path: { sandbox_id: this.id },
+            body: inline === undefined ? { path: remotePath } : { path: remotePath, inline_below: inline },
+            signal: options.signal,
+        });
+        if (answer.content !== undefined) {
+            // The body came inline; keep the same atomic replace as a streamed download.
+            const bytes = decodeBase64(answer.content);
+            if (localPath === undefined) {
+                return new ReadableStream({
+                    start: (controller) => {
+                        controller.enqueue(bytes);
+                        controller.close();
+                    },
+                });
+            }
+            const [fs, paths, crypto] = await Promise.all([
+                import('node:fs/promises'), import('node:path'), import('node:crypto'),
+            ]);
+            const temporary = `${localPath}.part-${crypto.randomBytes(6).toString('hex')}`;
+            await fs.mkdir(paths.dirname(localPath), { recursive: true });
+            const existing = await fs.stat(localPath).catch(() => undefined);
+            await fs.writeFile(temporary, bytes, { mode: existing ? existing.mode & 0o7777 : 0o666 });
+            await fs.rename(temporary, localPath);
+            return;
+        }
+        if (answer.url === undefined)
+            throw new transfer_1.TransferError('Sandbox download answer carried no link');
+        const link = { ...answer, url: answer.url };
+        const transfer = { size: link.size == null ? undefined : Number(link.size), label: 'Sandbox', progress: options.progress, signal: options.signal };
+        if (localPath === undefined)
+            return (0, transfer_1.downloadStream)(link, transfer);
+        await (0, transfer_1.downloadToFile)(link, localPath, transfer);
+    }
+}
+exports.SandboxFiles = SandboxFiles;