@boxrouter/sdk 0.0.0-stage → 0.12.190

package/dist/terminal.js

@@ -0,0 +1,266 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Terminal = exports.TerminalError = void 0;
+exports.closeObservers = closeObservers;
+exports.combineCleanupErrors = combineCleanupErrors;
+exports.openTerminal = openTerminal;
+const workflow_policy_gen_1 = require("./workflow-policy.gen");
+const sandboxes_1 = require("./sandboxes");
+class TerminalError extends Error {
+    event;
+    code;
+    outcome;
+    retry;
+    constructor(event) {
+        super(event.error.message);
+        this.event = event;
+        this.name = 'TerminalError';
+        this.code = event.error.code;
+        this.outcome = event.error.outcome;
+        this.retry = event.error.retry;
+    }
+}
+exports.TerminalError = TerminalError;
+function closeObservers(observers) {
+    const failures = [];
+    for (const close of [...observers]) {
+        try {
+            close();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+    }
+    if (failures.length)
+        throw combineCleanupErrors(failures, 'Terminal observers failed to close');
+}
+function combineCleanupErrors(errors, message) {
+    return errors.length === 1 ? errors[0] : new AggregateError(errors, message);
+}
+function size(rows, cols) {
+    if ([rows, cols].some(n => !Number.isInteger(n) || n < workflow_policy_gen_1.TERMINAL_SIZE_MINIMUM || n > workflow_policy_gen_1.TERMINAL_SIZE_MAXIMUM)) {
+        throw new RangeError(`Terminal rows and cols must be integers between ${workflow_policy_gen_1.TERMINAL_SIZE_MINIMUM} and ${workflow_policy_gen_1.TERMINAL_SIZE_MAXIMUM}`);
+    }
+}
+function base64(data) {
+    const chunks = [];
+    for (let offset = 0; offset < data.length; offset += 32768) {
+        chunks.push(String.fromCharCode(...data.subarray(offset, offset + 32768)));
+    }
+    return btoa(chunks.join(''));
+}
+/**
+ * One PTY shell on any provider. Closing this handle detaches local observers only; the shell runs
+ * until it exits, is killed or reaches its timeout. Attach again with its id.
+ */
+class Terminal {
+    state;
+    #api;
+    #path;
+    #observers = new Set();
+    #registerObserver;
+    #lastEventId = null;
+    #exitCode = null;
+    #confirmedExit = false;
+    constructor(api, state, registerObserver) {
+        this.state = state;
+        this.#api = api;
+        this.#path = { sandbox_id: state.sandbox_id, terminal_id: state.id };
+        this.#registerObserver = registerObserver;
+    }
+    get id() { return this.#path.terminal_id; }
+    get sandboxId() { return this.#path.sandbox_id; }
+    get lastEventId() { return this.#lastEventId; }
+    get exitCode() { return this.#exitCode; }
+    /** Detach this handle's HTTP observers only; the remote shell keeps running. */
+    close() {
+        closeObservers(this.#observers);
+    }
+    /** Raw typed events; an early end throws. */
+    async events(options = {}) {
+        if (options.lastEventId !== undefined) {
+            this.#confirmedExit = false;
+            this.#lastEventId = options.lastEventId;
+        }
+        const lastEventId = options.lastEventId === undefined ? this.#lastEventId ?? undefined : options.lastEventId;
+        let closed = false;
+        let sourceClosed = false;
+        let source;
+        let unregister = () => { };
+        const closeSource = () => {
+            if (source === undefined || sourceClosed)
+                return;
+            sourceClosed = true;
+            source.close();
+        };
+        const close = () => {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                closeSource();
+            }
+            finally {
+                this.#observers.delete(close);
+                unregister();
+            }
+        };
+        this.#observers.add(close);
+        try {
+            unregister = this.#registerObserver?.(close) ?? (() => { });
+            if (closed)
+                unregister();
+            source = await this.#api.terminals.events({ path: this.#path, signal: options.signal,
+                headers: lastEventId === undefined ? undefined : { [workflow_policy_gen_1.TERMINAL_EVENT_ID_HEADER]: lastEventId } });
+            if (closed)
+                throw new Error('Terminal observer was closed while opening');
+        }
+        catch (error) {
+            const cleanupErrors = [];
+            try {
+                closeSource();
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+            try {
+                close();
+            }
+            catch (cleanupError) {
+                cleanupErrors.push(cleanupError);
+            }
+            if (cleanupErrors.length) {
+                throw combineCleanupErrors([error, ...cleanupErrors], 'Terminal events open and observer cleanup failed');
+            }
+            throw error;
+        }
+        const openedSource = source;
+        if (openedSource === undefined)
+            throw new Error('Terminal event stream did not open');
+        const terminal = this;
+        async function* data() {
+            let failure;
+            let failed = false;
+            try {
+                for await (const envelope of openedSource.stream) {
+                    const event = envelope.data;
+                    const id = envelope[workflow_policy_gen_1.TERMINAL_EVENT_ID_FIELD];
+                    if (id !== undefined)
+                        terminal.#lastEventId = id;
+                    if (event.type === workflow_policy_gen_1.TERMINAL_EXIT_EVENT_TYPE) {
+                        terminal.#confirmedExit = true;
+                        terminal.#exitCode = event.exit_code === null || event.exit_code === undefined
+                            ? null : Number(event.exit_code);
+                    }
+                    if (event.type !== workflow_policy_gen_1.TERMINAL_OUTPUT_EVENT_TYPE) {
+                        yield event;
+                        continue;
+                    }
+                    const { data_base64, ...fields } = event;
+                    yield { ...fields, data: (0, sandboxes_1.decodeBase64)(data_base64) };
+                }
+            }
+            catch (error) {
+                failure = error;
+                failed = true;
+                throw error;
+            }
+            finally {
+                try {
+                    close();
+                }
+                catch (cleanupError) {
+                    if (failed)
+                        throw combineCleanupErrors([failure, cleanupError], 'Terminal stream and observer cleanup failed');
+                    throw cleanupError;
+                }
+            }
+        }
+        return { stream: data(), close };
+    }
+    /** Yield exact output chunks, then stop at exit; errors and incomplete streams raise. */
+    async *output(options = {}) {
+        if (options.lastEventId === undefined && this.#confirmedExit)
+            return;
+        const events = await this.events(options);
+        const iterator = events.stream[Symbol.asyncIterator]();
+        let failure;
+        let failed = false;
+        try {
+            while (true) {
+                const next = await iterator.next();
+                if (next.done)
+                    return;
+                const event = next.value;
+                if (event.type === workflow_policy_gen_1.TERMINAL_OUTPUT_EVENT_TYPE)
+                    yield event.data;
+                else if (event.type === workflow_policy_gen_1.TERMINAL_ERROR_EVENT_TYPE)
+                    throw new TerminalError(event);
+                else
+                    return;
+            }
+        }
+        catch (error) {
+            failure = error;
+            failed = true;
+            throw error;
+        }
+        finally {
+            const cleanupErrors = [];
+            try {
+                await iterator.return?.(undefined);
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+            try {
+                events.close();
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+            if (cleanupErrors.length) {
+                throw failed
+                    ? combineCleanupErrors([failure, ...cleanupErrors], 'Terminal output and observer cleanup failed')
+                    : combineCleanupErrors(cleanupErrors, 'Terminal observers failed to close');
+            }
+        }
+    }
+    /** Await writes sequentially. Never replay an uncertain write. */
+    async write(data, options = {}) {
+        if (!(data instanceof Uint8Array) || data.byteLength > workflow_policy_gen_1.TERMINAL_INPUT_BYTES) {
+            throw new RangeError(workflow_policy_gen_1.TERMINAL_INPUT_ERROR);
+        }
+        await this.#api.terminals.write({ path: this.#path, body: { data_base64: base64(data) }, ...(0, sandboxes_1.mutationOptions)(options) });
+    }
+    /** Change the window size; the foreground program receives SIGWINCH. */
+    async resize(rows, cols, options = {}) {
+        size(rows, cols);
+        await this.#api.terminals.resize({ path: this.#path, body: { rows, columns: cols }, ...(0, sandboxes_1.mutationOptions)(options) });
+    }
+    /** End the shell; its exit event follows on the stream. */
+    async kill(options = {}) {
+        await this.#api.terminals.kill({ path: this.#path, ...(0, sandboxes_1.mutationOptions)(options) });
+    }
+}
+exports.Terminal = Terminal;
+/** Open a PTY shell by sandbox ID, or attach to terminalId; observer ownership stays local. */
+async function openTerminal(api, sandboxId, options = {}, registerObserver) {
+    const { rows = workflow_policy_gen_1.TERMINAL_ROWS, cols = workflow_policy_gen_1.TERMINAL_COLS, terminalId, signal } = options;
+    size(rows, cols);
+    if (terminalId !== undefined && (typeof terminalId !== 'string' || !terminalId)) {
+        throw new TypeError('Terminal terminalId must be a nonempty string');
+    }
+    let state;
+    if (options.terminalId === undefined) {
+        state = await api.terminals.open({ path: { sandbox_id: sandboxId },
+            body: { columns: cols, rows, timeout_seconds: options.timeoutSeconds }, ...(0, sandboxes_1.mutationOptions)(options) });
+    }
+    else {
+        state = await api.terminals.get({ path: { sandbox_id: sandboxId, terminal_id: terminalId }, signal });
+    }
+    if (state.sandbox_id !== sandboxId)
+        throw new TypeError('The terminal is unconfirmed');
+    const terminal = new Terminal(api, state, registerObserver);
+    return terminal;
+}

package/dist/transfer.d.ts

@@ -0,0 +1,75 @@
+export interface TransferPart {
+    number: number | bigint;
+    size: number | bigint;
+    url: string;
+    method?: string | null;
+    headers?: Record<string, string> | null;
+    form_field?: string | null;
+}
+export interface TransferLink {
+    url: string;
+    method?: string | null;
+    headers?: Record<string, string> | null;
+}
+/** `bytesTotal` is undefined while the size of a download is unknown. */
+export type TransferProgress = (bytesDone: number, bytesTotal?: number) => void;
+export interface UploadSourceInput {
+    /** A local file path (Node), a Blob, bytes, or a stream. A stream needs `size`. */
+    source: string | Blob | Uint8Array | ReadableStream<Uint8Array>;
+    size?: number;
+}
+/** An opened upload source: `slice` returns a lazy body of exactly `end - start` bytes. */
+export interface OpenedSource {
+    readonly size: number;
+    slice(start: number, end: number): Blob | Uint8Array;
+    close(): Promise<void>;
+}
+export interface SendPartsOptions {
+    concurrency: number;
+    /** Send a part again after a network error or 5xx, even if bytes were sent. See the file comment. */
+    replayParts: boolean;
+    /** Prefix of error messages, for example `Volume`. */
+    label?: string;
+    progress?: TransferProgress;
+    signal?: AbortSignal;
+}
+export interface PartResult {
+    number: number;
+    etag?: string;
+}
+export declare class TransferError extends Error {
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+/** Per socket operation: a 5 GiB part is fine while it moves, a connection that stalls for 300 s fails. */
+export declare const TRANSFER_TIMEOUTS: {
+    readonly connectMs: 10000;
+    readonly headersMs: 300000;
+    readonly bodyMs: 300000;
+};
+/** Open an upload source and learn its size without reading it into memory. A stream is copied to disk
+ * while `signal` is live: aborting it cancels the pending read and removes the temporary data. */
+export declare function openSource({ source, size }: UploadSourceInput, signal?: AbortSignal): Promise<OpenedSource>;
+/**
+ * Send every part with bounded parallelism and return each part's ETag when the response had one.
+ * The first failure stops the other parts and is raised; aborting the upload session is the caller's.
+ */
+export declare function sendParts(source: OpenedSource, parts: TransferPart[], options: SendPartsOptions): Promise<PartResult[]>;
+/**
+ * Run a completion call, retrying while the answer is unknown (503 or no response). Every retry
+ * carries the idempotency key the first send used (`call` gets it, undefined on the first attempt), so a
+ * completion whose answer was lost is recovered rather than repeated under a new key.
+ */
+export declare function retryCompletion<T>(call: (idempotencyKey: string | undefined) => Promise<T>, signal?: AbortSignal): Promise<T>;
+export interface DownloadOptions {
+    /** The size the API reported; the body must match it exactly. Absent when the API does not know it:
+     * the response's Content-Length is then the expected length, and with neither the body is read to its end. */
+    size?: number | null;
+    label?: string;
+    progress?: TransferProgress;
+    signal?: AbortSignal;
+}
+/** Stream a download. The stream errors if the body does not match `size`. */
+export declare function downloadStream(link: TransferLink, options?: DownloadOptions): Promise<ReadableStream<Uint8Array>>;
+/** Download to `destination` through `<destination>.part-<random>`, renaming only after the full length is on disk. */
+export declare function downloadToFile(link: TransferLink, destination: string, options?: DownloadOptions): Promise<void>;