@hyperbrowser/sdk 0.93.0 → 1.0.0

package/dist/sandbox/base.js

@@ -3,69 +3,184 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RuntimeTransport = void 0;
+exports.RuntimeTransport = exports.PROCESS_STREAM_IDLE_TIMEOUT_MS = void 0;
+const stream_1 = require("stream");
+const string_decoder_1 = require("string_decoder");
 const node_fetch_1 = __importDefault(require("node-fetch"));
-const client_1 = require("../client");
+const error_1 = require("../error");
+const retry_1 = require("../retry");
 const ws_1 = require("./ws");
-const RETRYABLE_STATUS_CODES = new Set([429, 502, 503, 504]);
-const RETRYABLE_NETWORK_CODES = new Set([
-    "ECONNRESET",
-    "ECONNREFUSED",
-    "EAI_AGAIN",
-    "ETIMEDOUT",
-    "ESOCKETTIMEDOUT",
-]);
+// The receiver sends process SSE keepalives every 15 seconds.
+exports.PROCESS_STREAM_IDLE_TIMEOUT_MS = 60000;
 const getRequestId = (response) => {
     return response.headers.get("x-request-id") || response.headers.get("request-id") || undefined;
 };
-const isRetryableNetworkError = (error) => {
-    if (!(error instanceof Error)) {
-        return false;
-    }
-    const networkError = error;
-    return (networkError.name === "AbortError" ||
-        networkError.type === "request-timeout" ||
-        (networkError.code ? RETRYABLE_NETWORK_CODES.has(networkError.code) : false));
-};
+const isEventStream = (response) => (response.headers.get("content-type") || "").includes("text/event-stream");
 class RuntimeTransport {
+    closeResponse(response) {
+        this.responseCleanup.get(response)?.();
+    }
+    failure(error, path, init, response) {
+        if (error instanceof error_1.HyperbrowserError) {
+            return new error_1.HyperbrowserError(error.message.replace(/^\[Hyperbrowser\]: /, ""), {
+                statusCode: error.statusCode ?? response?.status,
+                code: error.code,
+                requestId: error.requestId ?? (response ? getRequestId(response) : undefined),
+                service: error.service ?? "runtime",
+                retryable: error.retryable,
+                details: error.details,
+                cause: error.cause ?? error,
+                method: error.method ?? init?.method ?? "GET",
+                path: error.path ?? (0, error_1.errorRequestPath)(path),
+            });
+        }
+        const canceled = init?.signal?.aborted;
+        return new error_1.HyperbrowserError((0, error_1.networkErrorMessage)(error, "Runtime request failed"), {
+            code: canceled ? "request_aborted" : undefined,
+            statusCode: response?.status,
+            requestId: response ? getRequestId(response) : undefined,
+            service: "runtime",
+            retryable: !canceled && (0, retry_1.isRetryableNetworkError)(error),
+            method: init?.method ?? "GET",
+            path: (0, error_1.errorRequestPath)(path),
+            cause: error,
+        });
+    }
     constructor(resolveConnection, timeout = 30000, runtimeProxyOverride) {
         this.resolveConnection = resolveConnection;
         this.timeout = timeout;
         this.runtimeProxyOverride = runtimeProxyOverride;
+        this.responseCleanup = new WeakMap();
     }
     async requestJSON(path, init, params) {
         const response = await this.fetchWithAuth(path, init, params);
-        if (response.headers.get("content-length") === "0") {
-            return {};
-        }
         try {
-            return (await response.json());
-        }
-        catch {
-            throw new client_1.HyperbrowserError("Failed to parse JSON response", {
-                statusCode: response.status,
-                requestId: getRequestId(response),
-                retryable: false,
-                service: "runtime",
-            });
+            const text = await response.text();
+            if (!text)
+                return {};
+            try {
+                return JSON.parse(text);
+            }
+            catch (cause) {
+                throw new error_1.HyperbrowserError("Failed to parse JSON response", {
+                    statusCode: response.status,
+                    requestId: getRequestId(response),
+                    service: "runtime",
+                    cause,
+                    method: init?.method ?? "GET",
+                    path: (0, error_1.errorRequestPath)(path),
+                });
+            }
+        }
+        catch (error) {
+            throw this.failure(error, path, init, response);
+        }
+        finally {
+            this.closeResponse(response);
         }
     }
     async requestBuffer(path, init, params) {
         const response = await this.fetchWithAuth(path, init, params);
-        return response.buffer();
+        try {
+            return await response.buffer();
+        }
+        catch (error) {
+            throw this.failure(error, path, init, response);
+        }
+        finally {
+            this.closeResponse(response);
+        }
+    }
+    /** Pull-based binary transfer. Breaking iteration closes the HTTP connection. */
+    async *streamBytes(path, init, params) {
+        const response = await this.fetchWithAuth(path, init, params, true, true);
+        try {
+            if (!response.body)
+                return;
+            const iterator = response.body[Symbol.asyncIterator]();
+            for (;;) {
+                const next = await this.readChunk(iterator, this.timeout);
+                if (next.done)
+                    return;
+                yield Buffer.from(next.value);
+            }
+        }
+        catch (error) {
+            throw this.failure(error, path, init, response);
+        }
+        finally {
+            this.closeResponse(response);
+        }
+    }
+    readChunk(iterator, timeout) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new error_1.HyperbrowserError(`Runtime stream idle for ${timeout}ms without data or keepalives`, { code: "stream_idle_timeout", service: "runtime", retryable: true })), timeout);
+            iterator.next().then((value) => {
+                clearTimeout(timer);
+                resolve(value);
+            }, (error) => {
+                clearTimeout(timer);
+                reject(error);
+            });
+        });
     }
     async *streamSSE(path, params) {
-        const response = await this.fetchWithAuth(path, {
-            method: "GET",
-            headers: {
-                Accept: "text/event-stream",
-            },
-        }, params);
+        const stream = await this.openSSE(path, params);
+        try {
+            yield* stream.events;
+        }
+        finally {
+            stream.close();
+        }
+    }
+    /**
+     * Open a server-sent event stream. POST streams carry a JSON body and
+     * require an event-stream response, since the request may have side effects
+     * that must not be retried blindly.
+     */
+    async openSSE(path, params, init = {}) {
+        const method = init.method ?? "GET";
+        const headers = {
+            Accept: "text/event-stream",
+            ...(init.body !== undefined ? { "content-type": "application/json" } : {}),
+            ...(init.headers ?? {}),
+        };
+        const response = await this.fetchWithAuth(path, { method, headers, body: init.body, signal: init.signal }, params, true, true);
+        if (method === "POST" && !isEventStream(response)) {
+            this.closeResponse(response);
+            throw new error_1.HyperbrowserError("Receiver does not support streaming command start; update the receiver. " +
+                "The command may have started; do not retry it automatically.", { code: "streaming_not_supported", service: "runtime", retryable: false,
+                method, path: (0, error_1.errorRequestPath)(path), requestId: getRequestId(response), statusCode: response.status });
+        }
         const body = response.body;
+        const idleTimeoutMs = init.idleTimeoutMs ?? exports.PROCESS_STREAM_IDLE_TIMEOUT_MS;
+        let closed = false;
+        const close = () => {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            this.closeResponse(response);
+        };
+        const parsed = this.parseSSE(body, idleTimeoutMs, () => closed, close, init.signal);
+        const failure = (error) => this.failure(error, path, { method, signal: init.signal }, response);
+        const events = (async function* () {
+            try {
+                yield* parsed;
+            }
+            catch (error) {
+                throw failure(error);
+            }
+        })();
+        return { events, close };
+    }
+    async *parseSSE(body, idleTimeoutMs, isClosed, close, signal) {
         if (!body) {
             return;
         }
         let buffer = "";
+        let skipLineFeed = false;
+        const decoder = new string_decoder_1.StringDecoder("utf8");
         let eventName = "message";
         let eventId;
         let dataLines = [];
@@ -93,88 +208,165 @@ class RuntimeTransport {
             dataLines = [];
             return event;
         };
-        for await (const chunk of body) {
-            buffer += Buffer.from(chunk).toString("utf8");
-            while (true) {
-                const newlineIndex = buffer.indexOf("\n");
-                if (newlineIndex === -1) {
+        const readLine = (line) => {
+            if (line === "")
+                return flushEvent();
+            if (line.startsWith(":"))
+                return null;
+            const separator = line.indexOf(":");
+            const field = separator === -1 ? line : line.slice(0, separator);
+            // Match the Python transport's field-value space normalization.
+            const value = separator === -1 ? "" : line.slice(separator + 1).replace(/^ +/, "");
+            switch (field) {
+                case "event":
+                    eventName = value || "message";
                     break;
+                case "data":
+                    dataLines.push(value);
+                    break;
+                case "id":
+                    eventId = value;
+                    break;
+            }
+            return null;
+        };
+        const iterator = body[Symbol.asyncIterator]();
+        try {
+            for (;;) {
+                let next;
+                try {
+                    next = await this.readChunk(iterator, idleTimeoutMs);
                 }
-                let line = buffer.slice(0, newlineIndex);
-                buffer = buffer.slice(newlineIndex + 1);
-                if (line.endsWith("\r")) {
-                    line = line.slice(0, -1);
-                }
-                if (line === "") {
-                    const event = flushEvent();
-                    if (event) {
-                        yield event;
+                catch (error) {
+                    if (signal?.aborted)
+                        throw new error_1.HyperbrowserError("Command collection canceled", {
+                            code: "request_aborted",
+                            service: "runtime",
+                            cause: error,
+                        });
+                    if (isClosed()) {
+                        return;
                     }
-                    continue;
+                    if (error instanceof error_1.HyperbrowserError) {
+                        throw error;
+                    }
+                    throw new error_1.HyperbrowserError(error instanceof Error ? error.message : "Runtime stream failed", { service: "runtime", retryable: (0, retry_1.isRetryableNetworkError)(error), cause: error });
                 }
-                if (line.startsWith(":")) {
-                    continue;
+                if (next.done) {
+                    break;
                 }
-                const separator = line.indexOf(":");
-                const field = separator === -1 ? line : line.slice(0, separator);
-                const value = separator === -1 ? "" : line.slice(separator + 1).replace(/^ /, "");
-                switch (field) {
-                    case "event":
-                        eventName = value || "message";
-                        break;
-                    case "data":
-                        dataLines.push(value);
-                        break;
-                    case "id":
-                        eventId = value;
-                        break;
-                    default:
+                buffer += decoder.write(Buffer.from(next.value));
+                while (true) {
+                    if (skipLineFeed) {
+                        if (!buffer)
+                            break;
+                        if (buffer.startsWith("\n"))
+                            buffer = buffer.slice(1);
+                        skipLineFeed = false;
+                    }
+                    const newlineIndex = buffer.search(/[\r\n]/);
+                    if (newlineIndex === -1) {
                         break;
+                    }
+                    const line = buffer.slice(0, newlineIndex);
+                    // Deliver bare CR immediately; absorb a following LF even across chunks.
+                    skipLineFeed = buffer[newlineIndex] === "\r";
+                    buffer = buffer.slice(newlineIndex + 1);
+                    const event = readLine(line);
+                    if (event)
+                        yield event;
                 }
             }
+            buffer += decoder.end();
+            if (buffer)
+                readLine(buffer);
+            const trailing = flushEvent();
+            if (trailing) {
+                yield trailing;
+            }
         }
-        const trailing = flushEvent();
-        if (trailing) {
-            yield trailing;
+        finally {
+            close();
         }
     }
-    async fetchWithAuth(path, init, params, allowRefresh = true) {
+    async fetchWithAuth(path, init, params, allowRefresh = true, streaming = false) {
         const connection = await this.resolveConnection(false);
-        const response = await this.fetchForConnection(connection, path, init, params);
+        const response = await this.fetchForConnection(connection, path, init, params, streaming);
         if (response.status === 401 && allowRefresh) {
+            this.closeResponse(response);
+            if (init?.body instanceof stream_1.Readable) {
+                throw new error_1.HyperbrowserError("Runtime authentication expired during a streaming upload; obtain a new stream before retrying", {
+                    statusCode: 401,
+                    code: "stream_not_replayable",
+                    service: "runtime",
+                    retryable: false,
+                    method: init?.method ?? "GET",
+                    path: (0, error_1.errorRequestPath)(path),
+                    requestId: getRequestId(response),
+                });
+            }
             const refreshed = await this.resolveConnection(true);
-            const retryResponse = await this.fetchForConnection(refreshed, path, init, params);
-            return this.assertResponse(retryResponse);
+            const retryResponse = await this.fetchForConnection(refreshed, path, init, params, streaming);
+            return this.assertResponse(retryResponse, path, init);
         }
-        return this.assertResponse(response);
+        return this.assertResponse(response, path, init);
     }
-    async fetchForConnection(connection, path, init, params) {
+    async fetchForConnection(connection, path, init, params, streaming = false) {
         const target = (0, ws_1.resolveRuntimeTransportTarget)(connection.baseUrl, this.buildRequestPath(path, params), this.runtimeProxyOverride);
         const headers = this.buildHeaders(connection, init?.headers, target.hostHeader);
         const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        let timer = setTimeout(() => controller.abort(), this.timeout);
+        const upload = init?.body instanceof stream_1.Readable ? init.body : undefined;
+        const uploadProgress = () => {
+            clearTimeout(timer);
+            timer = setTimeout(() => controller.abort(), this.timeout);
+        };
+        upload?.on("data", uploadProgress);
+        const callerSignal = init?.signal;
+        const abortFromCaller = () => controller.abort();
+        if (callerSignal?.aborted)
+            controller.abort();
+        else
+            callerSignal?.addEventListener("abort", abortFromCaller, { once: true });
+        const detach = () => {
+            clearTimeout(timer);
+            timer = undefined;
+            callerSignal?.removeEventListener("abort", abortFromCaller);
+            upload?.removeListener("data", uploadProgress);
+        };
         try {
-            return await (0, node_fetch_1.default)(target.url, {
-                ...init,
-                headers,
-                signal: controller.signal,
-            });
-        }
-        catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
-                throw error;
+            const response = await (0, node_fetch_1.default)(target.url, { ...init, headers, signal: controller.signal });
+            clearTimeout(timer);
+            upload?.removeListener("data", uploadProgress);
+            // Header and body budgets are separate. Streams use a read-idle budget.
+            timer =
+                streaming && response.ok ? undefined : setTimeout(() => controller.abort(), this.timeout);
+            const body = response.body;
+            let disposed = false;
+            const close = () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                detach();
+                if (!body?.readableEnded)
+                    controller.abort();
+                body?.destroy();
+            };
+            this.responseCleanup.set(response, close);
+            if (body) {
+                body.once("end", detach);
+                body.once("close", close);
             }
-            throw new client_1.HyperbrowserError(error instanceof Error ? error.message : "Unknown runtime request error", {
-                retryable: isRetryableNetworkError(error),
-                service: "runtime",
-                cause: error,
-            });
+            else
+                close();
+            return response;
         }
-        finally {
-            clearTimeout(timeoutId);
+        catch (error) {
+            detach();
+            throw this.failure(error, path, init);
         }
     }
-    async assertResponse(response) {
+    async assertResponse(response, path, init) {
         if (response.ok) {
             return response;
         }
@@ -196,16 +388,23 @@ class RuntimeTransport {
                 }
             }
         }
-        catch {
+        catch (error) {
+            if (init?.signal?.aborted)
+                throw this.failure(error, path, init, response);
             // Keep the fallback message.
         }
-        throw new client_1.HyperbrowserError(message, {
+        finally {
+            this.closeResponse(response);
+        }
+        throw new error_1.HyperbrowserError(message, {
             statusCode: response.status,
             code,
             requestId: getRequestId(response),
-            retryable: RETRYABLE_STATUS_CODES.has(response.status),
+            retryable: retry_1.RETRYABLE_STATUS_CODES.has(response.status),
             service: "runtime",
             details,
+            method: init?.method ?? "GET",
+            path: (0, error_1.errorRequestPath)(path),
         });
     }
     buildHeaders(connection, rawHeaders, hostHeader) {

package/dist/sandbox/files.d.ts

@@ -1,40 +1,26 @@
 import { Blob, Buffer } from "buffer";
 import { ReadableStream } from "node:stream/web";
 import { RuntimeTransport } from "./base";
-import { SandboxFileChmodParams, SandboxFileChownParams, SandboxFileCopyParams, SandboxFileInfo, SandboxFileListOptions, SandboxFileMakeDirOptions, SandboxFileReadOptions, SandboxFileSystemEvent, SandboxFileTransferResult, SandboxFileWriteData, SandboxFileWriteEntry, SandboxFileWriteInfo, SandboxFileBytesWriteOptions, SandboxFileTextWriteOptions, SandboxPresignFileParams, SandboxPresignedUrl, SandboxWatchDirOptions } from "../types/sandbox";
-interface RawFileWatchEvent {
-    seq: number;
-    path: string;
-    op: string;
-    timestamp: number;
-}
-interface RawFileWatchStatus {
-    id: string;
-    path: string;
-    recursive: boolean;
-    active: boolean;
-    error?: string;
-    createdAt: number;
-    stoppedAt?: number;
-    oldestSeq?: number;
-    lastSeq?: number;
-    eventCount?: number;
-}
+import { SandboxFileUploadStream, SandboxFileUploadStreamOptions, SandboxFileDownloadStreamOptions, SandboxFileMoveParams, SandboxFileRenameOptions, SandboxFileWatchParams, SandboxFileWatchStatus, SandboxFileWatchEventsParams, SandboxFileWatchStreamEvent, SandboxFileChmodParams, SandboxFileChownParams, SandboxFileCopyParams, SandboxFileInfo, SandboxFileListOptions, SandboxFileMakeDirOptions, SandboxFileReadOptions, SandboxFileSystemEvent, SandboxFileTransferResult, SandboxFileWriteData, SandboxFileWriteEntry, SandboxFileWriteInfo, SandboxFileBytesWriteOptions, SandboxFileTextWriteOptions, SandboxPresignFileParams, SandboxPresignedUrl, SandboxWatchDirOptions } from "../types/sandbox";
 interface RuntimeConnectionInfo {
     sandboxId: string;
     baseUrl: string;
     token: string;
 }
-declare class RuntimeFileWatchHandle {
+export declare class SandboxFileWatchHandle {
     private readonly transport;
     private readonly getConnectionInfo;
-    private readonly status;
+    private status;
     private readonly runtimeProxyOverride?;
-    constructor(transport: RuntimeTransport, getConnectionInfo: () => Promise<RuntimeConnectionInfo>, status: RawFileWatchStatus, runtimeProxyOverride?: string | undefined);
+    private readonly connections;
+    constructor(transport: RuntimeTransport, getConnectionInfo: () => Promise<RuntimeConnectionInfo>, status: SandboxFileWatchStatus, runtimeProxyOverride?: string | undefined);
     get id(): string;
     get path(): string;
+    get current(): SandboxFileWatchStatus;
+    toJSON(): SandboxFileWatchStatus;
+    refresh(includeEvents?: boolean): Promise<this>;
     stop(): Promise<void>;
-    events(cursor?: number): AsyncGenerator<RawFileWatchEvent>;
+    events(options?: SandboxFileWatchEventsParams): AsyncGenerator<SandboxFileWatchStreamEvent>;
 }
 export declare class SandboxWatchDirHandle {
     private readonly watch;
@@ -43,7 +29,8 @@ export declare class SandboxWatchDirHandle {
     private timeout?;
     private stopRequested;
     private exitNotified;
-    constructor(watch: RuntimeFileWatchHandle, onEvent: (event: SandboxFileSystemEvent) => void | Promise<void>, onExit?: ((error?: Error) => void | Promise<void>) | undefined, timeoutMs?: number);
+    private invokingCallback;
+    constructor(watch: SandboxFileWatchHandle, onEvent: (event: SandboxFileSystemEvent) => void | Promise<void>, onExit?: ((error?: Error) => void | Promise<void>) | undefined, timeoutMs?: number);
     stop(): Promise<void>;
     private run;
 }
@@ -78,7 +65,7 @@ export declare class SandboxFilesApi {
     upload(path: string, data: Buffer | Uint8Array | string): Promise<SandboxFileTransferResult>;
     download(path: string): Promise<Buffer>;
     makeDir(path: string, options?: SandboxFileMakeDirOptions): Promise<boolean>;
-    rename(oldPath: string, newPath: string): Promise<SandboxFileInfo>;
+    rename(oldPath: string, newPath: string, options?: SandboxFileRenameOptions): Promise<SandboxFileInfo>;
     remove(path: string, options?: {
         recursive?: boolean;
     }): Promise<void>;
@@ -86,6 +73,18 @@ export declare class SandboxFilesApi {
     chmod(params: SandboxFileChmodParams): Promise<void>;
     chown(params: SandboxFileChownParams): Promise<void>;
     watchDir(path: string, onEvent: (event: SandboxFileSystemEvent) => void | Promise<void>, options?: SandboxWatchDirOptions): Promise<SandboxWatchDirHandle>;
+    watch(path: string, options?: SandboxFileWatchParams): Promise<SandboxFileWatchHandle>;
+    getWatch(id: string, includeEvents?: boolean): Promise<SandboxFileWatchHandle>;
+    stat(path: string): Promise<SandboxFileInfo>;
+    mkdir(path: string, options?: SandboxFileMakeDirOptions): Promise<boolean>;
+    move(params: SandboxFileMoveParams): Promise<SandboxFileInfo>;
+    delete(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Upload without buffering; the source is closed on completion, rejection or cancellation. */
+    uploadStream(path: string, source: SandboxFileUploadStream, options?: SandboxFileUploadStreamOptions): Promise<SandboxFileTransferResult>;
+    /** Pull-based download; consume with for-await or Readable.from(). */
+    downloadStream(path: string, options?: SandboxFileDownloadStreamOptions): AsyncGenerator<Buffer>;
     uploadUrl(path: string, options?: Omit<SandboxPresignFileParams, "path">): Promise<SandboxPresignedUrl>;
     downloadUrl(path: string, options?: Omit<SandboxPresignFileParams, "path">): Promise<SandboxPresignedUrl>;
     private readWire;