@hyperbrowser/sdk 0.93.0 → 1.0.0

package/dist/sandbox/process-output.js

@@ -0,0 +1,117 @@
+"use strict";
+/** Collection and validation of the receiver's command event stream. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateOutputLimit = exports.ProcessOutput = exports.normalizeProcessResult = exports.DEFAULT_MAX_PROCESS_OUTPUT_BYTES = void 0;
+const string_decoder_1 = require("string_decoder");
+const error_1 = require("../error");
+exports.DEFAULT_MAX_PROCESS_OUTPUT_BYTES = 64 * 1024 * 1024;
+const BASE64_PATTERN = /^[A-Za-z0-9+/]*={0,2}$/;
+const normalizeProcessResult = (result) => ({
+    id: result.id,
+    status: result.status,
+    exitCode: result.exit_code !== undefined ? result.exit_code : result.exitCode,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    startedAt: result.started_at ?? result.startedAt,
+    completedAt: result.completed_at !== undefined ? result.completed_at : result.completedAt,
+    error: result.error,
+    outputTruncated: result.output_truncated,
+    lastSeq: result.last_seq,
+});
+exports.normalizeProcessResult = normalizeProcessResult;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+class ProcessOutput {
+    constructor(processId, maxBytes) {
+        this.processId = processId;
+        this.maxBytes = maxBytes;
+        this.size = 0;
+        this.seq = 0;
+        this.events = [];
+        this.result = null;
+        this.error = null;
+        this.chunks = { stdout: [], stderr: [] };
+        this.decoders = {
+            stdout: new string_decoder_1.StringDecoder("utf8"),
+            stderr: new string_decoder_1.StringDecoder("utf8"),
+            system: new string_decoder_1.StringDecoder("utf8"),
+        };
+    }
+    failure(message, code = "incomplete_output") {
+        return new error_1.HyperbrowserError(message, {
+            code,
+            service: "runtime",
+            retryable: false,
+            details: { process_id: this.processId, last_seq: this.seq },
+        });
+    }
+    consume(event) {
+        if (event.event === "output") {
+            this.consumeOutput(event.data);
+            return;
+        }
+        if (event.event === "done") {
+            this.consumeDone(event.data);
+            return;
+        }
+        if (event.event === "error") {
+            const data = isRecord(event.data) ? event.data : {};
+            throw this.failure(String(data.error ?? "Command stream failed"), typeof data.code === "string" ? data.code : "incomplete_output");
+        }
+    }
+    decodePayload(data) {
+        if (data.encoding === "base64") {
+            const text = data.data;
+            if (text.length % 4 !== 0 || !BASE64_PATTERN.test(text)) {
+                throw this.failure("Command output contains invalid base64 data");
+            }
+            return Buffer.from(text, "base64");
+        }
+        return Buffer.from(data.data, "utf8");
+    }
+    consumeOutput(payload) {
+        if (!isRecord(payload)) {
+            throw this.failure("Command output event is malformed");
+        }
+        const data = payload;
+        if (data.seq !== this.seq + 1) {
+            throw this.failure("Command output contains a sequence gap");
+        }
+        const stream = data.stream;
+        if (!Object.prototype.hasOwnProperty.call(this.decoders, stream)) {
+            throw this.failure("Unknown command output stream");
+        }
+        const raw = this.decodePayload(data);
+        this.size += raw.length;
+        if (this.size > this.maxBytes) {
+            throw this.failure("Command output exceeds maxOutputBytes; increase the collection limit or disconnect a detached process", "output_limit_exceeded");
+        }
+        this.seq = data.seq;
+        const text = this.decoders[stream].write(raw);
+        this.chunks[stream === "stdout" ? "stdout" : "stderr"].push(text);
+        this.events.push({ type: stream, seq: this.seq, data: text, timestamp: data.timestamp });
+    }
+    consumeDone(payload) {
+        if (!isRecord(payload)) {
+            throw this.failure("Command completion event is malformed");
+        }
+        const data = payload;
+        if (data.last_seq !== this.seq || data.output_truncated) {
+            throw this.failure("Receiver reported incomplete command output");
+        }
+        for (const stream of Object.keys(this.decoders)) {
+            this.chunks[stream === "stdout" ? "stdout" : "stderr"].push(this.decoders[stream].end());
+        }
+        this.result = (0, exports.normalizeProcessResult)({
+            ...data,
+            stdout: this.chunks.stdout.join(""),
+            stderr: this.chunks.stderr.join(""),
+        });
+    }
+}
+exports.ProcessOutput = ProcessOutput;
+const validateOutputLimit = (value) => {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+        throw new error_1.HyperbrowserError("maxOutputBytes must be a positive integer");
+    }
+};
+exports.validateOutputLimit = validateOutputLimit;

package/dist/sandbox/process.d.ts

@@ -1,25 +1,49 @@
-import { RuntimeTransport } from "./base";
+import { RuntimeSSEStream, RuntimeTransport } from "./base";
 import { SandboxExecParams, SandboxExecOptions, SandboxProcessListParams, SandboxProcessListResponse, SandboxProcessResult, SandboxProcessSignal, SandboxProcessStdinParams, SandboxProcessStreamEvent, SandboxProcessSummary, SandboxProcessWaitParams } from "../types/sandbox";
 export declare class SandboxProcessHandle {
     private readonly transport;
     private summary;
+    private output;
+    private collector;
+    private closeStream;
+    private readonly changed;
     constructor(transport: RuntimeTransport, summary: SandboxProcessSummary);
+    /** @internal Collect output from the start-stream that created this process. */
+    attachCollector(stream: RuntimeSSEStream, maxOutputBytes: number): void;
+    private collect;
+    private collectedResult;
+    /** Stop collecting output; the detached command continues running. */
+    disconnect(): void;
     get id(): string;
     get status(): SandboxProcessSummary["status"];
     toJSON(): SandboxProcessSummary;
     refresh(): Promise<SandboxProcessHandle>;
+    /**
+     * Wait for completion. Processes started by this client resolve from the
+     * collected stream; a local timeout rejects without stopping collection.
+     */
     wait(params?: SandboxProcessWaitParams): Promise<SandboxProcessResult>;
     signal(signal: SandboxProcessSignal): Promise<void>;
     kill(params?: SandboxProcessWaitParams): Promise<SandboxProcessResult>;
     writeStdin(input: string | Uint8Array | SandboxProcessStdinParams): Promise<void>;
+    /**
+     * Replay and follow output. Processes started by this client stream from the
+     * collected events; other handles attach to the receiver's stream endpoint.
+     */
     stream(fromSeq?: number): AsyncGenerator<SandboxProcessStreamEvent>;
     result(): Promise<SandboxProcessResult>;
 }
 export declare class SandboxProcessesApi {
     private readonly transport;
     constructor(transport: RuntimeTransport);
+    /** Run a command to completion, collecting its full output from process start. */
     exec(command: string, options?: SandboxExecOptions): Promise<SandboxProcessResult>;
     exec(input: SandboxExecParams): Promise<SandboxProcessResult>;
+    /**
+     * Start a process and collect its output in the background from the same
+     * streamed request, so output is complete even beyond the receiver's replay
+     * limit. Call `disconnect()` to stop collecting without killing the process.
+     */
     start(command: string, options?: SandboxExecOptions): Promise<SandboxProcessHandle>;
     start(input: SandboxExecParams): Promise<SandboxProcessHandle>;
     get(processId: string): Promise<SandboxProcessHandle>;

package/dist/sandbox/process.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SandboxProcessesApi = exports.SandboxProcessHandle = void 0;
+const error_1 = require("../error");
+const process_output_1 = require("./process-output");
 const DEFAULT_PROCESS_KILL_WAIT_MS = 5000;
 const SHELL_SAFE_TOKEN_PATTERN = /^[A-Za-z0-9_@%+=:,./-]+$/;
 const normalizeProcessSummary = (process) => ({
@@ -10,19 +12,9 @@ const normalizeProcessSummary = (process) => ({
     args: process.args,
     cwd: process.cwd,
     pid: process.pid,
-    exitCode: process.exit_code,
-    startedAt: process.started_at,
-    completedAt: process.completed_at,
-});
-const normalizeProcessResult = (result) => ({
-    id: result.id,
-    status: result.status,
-    exitCode: result.exit_code,
-    stdout: result.stdout,
-    stderr: result.stderr,
-    startedAt: result.started_at,
-    completedAt: result.completed_at,
-    error: result.error,
+    exitCode: process.exit_code !== undefined ? process.exit_code : process.exitCode,
+    startedAt: process.started_at ?? process.startedAt,
+    completedAt: process.completed_at !== undefined ? process.completed_at : process.completedAt,
 });
 const normalizeResultToSummary = (result) => ({
     id: result.id,
@@ -46,7 +38,7 @@ const normalizeStreamEvent = (event) => {
     if (event.event === "done") {
         return {
             type: "exit",
-            result: normalizeProcessResult(event.data),
+            result: (0, process_output_1.normalizeProcessResult)(event.data),
         };
     }
     return null;
@@ -69,6 +61,44 @@ const normalizeLegacyProcessParams = (input) => ({
     args: undefined,
     useShell: undefined,
 });
+class ChangeSignal {
+    constructor() {
+        this.waiters = [];
+    }
+    notify() {
+        const waiters = this.waiters;
+        this.waiters = [];
+        waiters.forEach((resolve) => resolve());
+    }
+    /** Resolve true on the next notification, or false once `timeoutMs` elapses. */
+    wait(timeoutMs) {
+        return new Promise((resolve) => {
+            let timer;
+            const onChange = () => {
+                if (timer) {
+                    clearTimeout(timer);
+                }
+                resolve(true);
+            };
+            this.waiters.push(onChange);
+            if (timeoutMs !== undefined) {
+                timer = setTimeout(() => {
+                    this.waiters = this.waiters.filter((waiter) => waiter !== onChange);
+                    resolve(false);
+                }, timeoutMs);
+            }
+        });
+    }
+}
+const localWaitTimeoutMs = (params) => {
+    if (params.timeoutSec !== undefined && params.timeoutSec > 0) {
+        return params.timeoutSec * 1000;
+    }
+    if (params.timeoutMs !== undefined && params.timeoutMs > 0) {
+        return params.timeoutMs;
+    }
+    return undefined;
+};
 const buildProcessPayload = (input) => ({
     command: input.command,
     cwd: input.cwd,
@@ -106,6 +136,79 @@ class SandboxProcessHandle {
     constructor(transport, summary) {
         this.transport = transport;
         this.summary = summary;
+        this.output = null;
+        this.collector = null;
+        this.closeStream = null;
+        this.changed = new ChangeSignal();
+    }
+    /** @internal Collect output from the start-stream that created this process. */
+    attachCollector(stream, maxOutputBytes) {
+        this.output = new process_output_1.ProcessOutput(this.id, maxOutputBytes);
+        this.closeStream = stream.close;
+        this.collector = this.collect(stream.events);
+    }
+    async collect(events) {
+        const output = this.output;
+        try {
+            for await (const event of events) {
+                if (output.error !== null) {
+                    return;
+                }
+                output.consume(event);
+                this.changed.notify();
+                if (output.result !== null) {
+                    return;
+                }
+            }
+            output.error = output.failure("Command stream ended before its completion event");
+        }
+        catch (error) {
+            if (output.error === null) {
+                output.error =
+                    error instanceof error_1.HyperbrowserError
+                        ? error
+                        : output.failure(error instanceof Error ? error.message : String(error));
+            }
+        }
+        finally {
+            try {
+                await events.return(undefined);
+            }
+            catch (error) {
+                if (output.result === null && output.error === null) {
+                    output.error = output.failure(error instanceof Error ? error.message : String(error));
+                }
+            }
+            this.closeStream?.();
+            this.changed.notify();
+        }
+    }
+    collectedResult() {
+        const output = this.output;
+        if (output.error !== null) {
+            throw output.error;
+        }
+        if (output.result === null) {
+            throw output.failure("Command stream ended before its completion event");
+        }
+        const result = output.result;
+        this.summary = {
+            ...this.summary,
+            status: result.status,
+            exitCode: result.exitCode,
+            completedAt: result.completedAt,
+        };
+        return result;
+    }
+    /** Stop collecting output; the detached command continues running. */
+    disconnect() {
+        if (this.output !== null) {
+            if (this.output.result === null && this.output.error === null) {
+                this.output.error = this.output.failure("Command output collection disconnected");
+            }
+            this.changed.notify();
+            this.closeStream?.();
+        }
     }
     get id() {
         return this.summary.id;
@@ -121,7 +224,28 @@ class SandboxProcessHandle {
         this.summary = normalizeProcessSummary(response.process);
         return this;
     }
+    /**
+     * Wait for completion. Processes started by this client resolve from the
+     * collected stream; a local timeout rejects without stopping collection.
+     */
     async wait(params = {}) {
+        if (this.output !== null && this.collector !== null) {
+            const output = this.output;
+            const timeoutMs = localWaitTimeoutMs(params);
+            const deadline = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
+            while (output.result === null && output.error === null) {
+                const remaining = deadline === undefined ? undefined : deadline - Date.now();
+                const ready = remaining !== undefined && remaining <= 0 ? false : await this.changed.wait(remaining);
+                if (!ready) {
+                    throw new error_1.HyperbrowserError("Timed out waiting for command output", {
+                        code: "wait_timeout",
+                        service: "runtime",
+                        retryable: false,
+                    });
+                }
+            }
+            return this.collectedResult();
+        }
         const response = await this.transport.requestJSON(`/sandbox/processes/${this.id}/wait`, {
             method: "POST",
             body: JSON.stringify({
@@ -132,7 +256,10 @@ class SandboxProcessHandle {
                 "content-type": "application/json",
             },
         });
-        const result = normalizeProcessResult(response.result);
+        const result = (0, process_output_1.normalizeProcessResult)(response.result);
+        if (result.outputTruncated) {
+            throw new process_output_1.ProcessOutput(this.id, 0).failure("Retained process output is incomplete; collect output from process start");
+        }
         this.summary = {
             ...this.summary,
             ...normalizeResultToSummary(result),
@@ -186,7 +313,33 @@ class SandboxProcessHandle {
             },
         });
     }
+    /**
+     * Replay and follow output. Processes started by this client stream from the
+     * collected events; other handles attach to the receiver's stream endpoint.
+     */
     async *stream(fromSeq) {
+        if (this.output !== null) {
+            const output = this.output;
+            let index = 0;
+            for (;;) {
+                const events = output.events.slice(index);
+                index += events.length;
+                const done = output.result !== null || output.error !== null;
+                if (events.length === 0 && !done) {
+                    await this.changed.wait();
+                    continue;
+                }
+                for (const event of events) {
+                    if (fromSeq === undefined || event.seq >= fromSeq) {
+                        yield event;
+                    }
+                }
+                if (done) {
+                    yield { type: "exit", result: this.collectedResult() };
+                    return;
+                }
+            }
+        }
         const params = fromSeq && fromSeq > 0
             ? {
                 from_seq: fromSeq,
@@ -209,26 +362,41 @@ class SandboxProcessesApi {
         this.transport = transport;
     }
     async exec(input, options) {
-        const params = normalizeExecParams(input, options);
-        const response = await this.transport.requestJSON("/sandbox/exec", {
-            method: "POST",
-            body: JSON.stringify(buildProcessPayload(params)),
-            headers: {
-                "content-type": "application/json",
-            },
-        });
-        return normalizeProcessResult(response.result);
+        const handle = typeof input === "string" ? await this.start(input, options) : await this.start(input);
+        try {
+            return await handle.wait();
+        }
+        finally {
+            handle.disconnect();
+        }
     }
     async start(input, options) {
         const params = normalizeExecParams(input, options);
-        const response = await this.transport.requestJSON("/sandbox/processes", {
+        const maxOutputBytes = params.maxOutputBytes ?? process_output_1.DEFAULT_MAX_PROCESS_OUTPUT_BYTES;
+        (0, process_output_1.validateOutputLimit)(maxOutputBytes);
+        const stream = await this.transport.openSSE("/sandbox/processes", undefined, {
             method: "POST",
             body: JSON.stringify(buildProcessPayload(params)),
-            headers: {
-                "content-type": "application/json",
-            },
+            signal: params.signal,
         });
-        return new SandboxProcessHandle(this.transport, normalizeProcessSummary(response.process));
+        let handle;
+        try {
+            const started = await stream.events.next();
+            if (started.done || started.value.event !== "started") {
+                throw new error_1.HyperbrowserError("Expected process start event", {
+                    service: "runtime",
+                    retryable: false,
+                });
+            }
+            handle = new SandboxProcessHandle(this.transport, normalizeProcessSummary(started.value.data));
+        }
+        catch (error) {
+            stream.close();
+            await stream.events.return(undefined).catch(() => undefined);
+            throw error;
+        }
+        handle.attachCollector(stream, maxOutputBytes);
+        return handle;
     }
     async get(processId) {
         const response = await this.transport.requestJSON(`/sandbox/processes/${processId}`);

package/dist/sandbox/terminal.js

@@ -54,10 +54,12 @@ class SandboxTerminalConnection {
                     });
                     return;
                 }
-                this.eventsQueue.push({
-                    type: "exit",
-                    status: normalizeTerminalStatus(parsed.status),
-                });
+                if (parsed.type === "exit") {
+                    this.eventsQueue.push({
+                        type: "exit",
+                        status: normalizeTerminalStatus(parsed.status),
+                    });
+                }
             }
             catch (error) {
                 this.eventsQueue.fail(error);
@@ -195,7 +197,9 @@ class SandboxTerminalHandle {
             headers.Host = target.hostHeader;
         }
         const ws = await (0, ws_2.openRuntimeWebSocket)(target, headers);
-        return new SandboxTerminalConnection(ws);
+        const connection = new SandboxTerminalConnection(ws);
+        ws.resume?.();
+        return connection;
     }
 }
 exports.SandboxTerminalHandle = SandboxTerminalHandle;

package/dist/sandbox/ws.d.ts

@@ -15,4 +15,7 @@ export interface RuntimeTransportTarget {
 }
 export declare const resolveRuntimeTransportTarget: (baseUrl: string, path: string, runtimeProxyOverride?: string) => RuntimeTransportTarget;
 export declare const toWebSocketUrl: (baseUrl: string, path: string, runtimeProxyOverride?: string) => RuntimeTransportTarget;
-export declare const openRuntimeWebSocket: (target: RuntimeTransportTarget, headers: Record<string, string>) => Promise<WebSocket>;
+export declare const openRuntimeWebSocket: (target: RuntimeTransportTarget, headers: Record<string, string>, options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}) => Promise<WebSocket>;

package/dist/sandbox/ws.js

@@ -5,7 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.openRuntimeWebSocket = exports.toWebSocketUrl = exports.resolveRuntimeTransportTarget = exports.AsyncEventQueue = void 0;
 const ws_1 = __importDefault(require("ws"));
-const client_1 = require("../client");
+const error_1 = require("../error");
 const runtime_path_1 = require("./runtime-path");
 class AsyncEventQueue {
     constructor() {
@@ -157,11 +157,11 @@ const readIncomingMessageBody = (response) => new Promise((resolve, reject) => {
     response.on("error", reject);
 });
 const normalizeWebSocketError = (error) => {
-    if (error instanceof client_1.HyperbrowserError) {
+    if (error instanceof error_1.HyperbrowserError) {
         return error;
     }
     const networkError = error;
-    return new client_1.HyperbrowserError(error instanceof Error ? error.message : "Unknown runtime websocket error", {
+    return new error_1.HyperbrowserError(error instanceof Error ? error.message : "Unknown runtime websocket error", {
         retryable: Boolean(networkError?.code && RETRYABLE_NETWORK_CODES.has(networkError.code)),
         service: "runtime",
         cause: error,
@@ -184,7 +184,7 @@ const buildHandshakeError = async (response) => {
             message = rawText;
         }
     }
-    return new client_1.HyperbrowserError(message, {
+    return new error_1.HyperbrowserError(message, {
         statusCode: response.statusCode,
         code,
         requestId: (typeof response.headers["x-request-id"] === "string"
@@ -198,25 +198,51 @@ const buildHandshakeError = async (response) => {
         details,
     });
 };
-const openRuntimeWebSocket = async (target, headers) => new Promise((resolve, reject) => {
+const openRuntimeWebSocket = async (target, headers, options = {}) => new Promise((resolve, reject) => {
     let settled = false;
+    let response;
+    if (options.signal?.aborted) {
+        reject(new error_1.HyperbrowserError("Runtime websocket request canceled", {
+            code: "request_aborted", service: "runtime", retryable: false,
+        }));
+        return;
+    }
     const socket = new ws_1.default(target.url, { headers });
+    const cleanup = () => {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", abort);
+    };
     const rejectOnce = (error) => {
         if (settled) {
             return;
         }
         settled = true;
+        cleanup();
+        response?.destroy();
+        socket.terminate();
         reject(normalizeWebSocketError(error));
     };
+    const abort = () => rejectOnce(new error_1.HyperbrowserError("Runtime websocket request canceled", {
+        code: "request_aborted", service: "runtime", retryable: false,
+    }));
+    const timer = setTimeout(() => rejectOnce(new error_1.HyperbrowserError("Runtime websocket handshake timed out", {
+        code: "request_timeout", service: "runtime", retryable: true,
+    })), options.timeoutMs ?? 30000);
+    timer.unref?.();
+    options.signal?.addEventListener("abort", abort, { once: true });
     socket.once("open", () => {
         if (settled) {
             return;
         }
         settled = true;
+        cleanup();
+        // Frames can arrive with the upgrade response, before an awaiting caller resumes.
+        socket.pause();
         resolve(socket);
     });
-    socket.once("unexpected-response", (_request, response) => {
-        void buildHandshakeError(response).then(rejectOnce).catch(rejectOnce);
+    socket.once("unexpected-response", (_request, incoming) => {
+        response = incoming;
+        void buildHandshakeError(incoming).then(rejectOnce).catch(rejectOnce);
     });
     socket.once("error", rejectOnce);
 });

package/dist/services/base.d.ts

@@ -4,5 +4,7 @@ export declare class BaseService {
     protected readonly baseUrl: string;
     protected readonly timeout: number;
     constructor(apiKey: string, baseUrl: string, timeout?: number);
+    /** Transient GET failures (429/502/503/504, network errors) retry up to three attempts. */
     protected request<T>(path: string, init?: RequestInit, params?: Record<string, string | number | string[] | undefined>, fullUrl?: boolean): Promise<T>;
+    private requestOnce;
 }