@hyperbrowser/sdk 0.93.0 → 1.0.0

package/dist/sandbox/image-build/tar.js

@@ -0,0 +1,378 @@
+"use strict";
+/**
+ * Minimal tar support: a PAX-format writer that mirrors CPython's `tarfile`
+ * output for the normalized entries used in build contexts, and a streaming
+ * reader for `docker image save` archives.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaxTarWriter = exports.createTarEntryHeader = void 0;
+exports.readTarEntries = readTarEntries;
+const BLOCK_SIZE = 512;
+const RECORD_SIZE = BLOCK_SIZE * 20;
+const POSIX_MAGIC = Buffer.from("ustar\x0000", "binary");
+const NUL = Buffer.alloc(1);
+const TYPE_FLAGS = {
+    file: "0",
+    directory: "5",
+    symlink: "2",
+};
+// Tar header validation intentionally includes NUL.
+// eslint-disable-next-line no-control-regex
+const isAscii = (value) => /^[\x00-\x7f]*$/.test(value);
+/** Python `stn`: encode with ASCII "replace" errors, then NUL-pad or truncate. */
+const stringField = (value, length) => {
+    // eslint-disable-next-line no-control-regex
+    const encoded = Buffer.from(value.replace(/[^\x00-\x7f]/g, "?"), "latin1");
+    const field = Buffer.alloc(length);
+    encoded.copy(field, 0, 0, Math.min(encoded.length, length));
+    return field;
+};
+/** Python `itn` for values that fit the octal field. */
+const numberField = (value, digits) => {
+    if (value < 0 || value >= 8 ** (digits - 1)) {
+        throw new RangeError(`tar header value ${value} does not fit in ${digits} digits`);
+    }
+    return Buffer.concat([Buffer.from(value.toString(8).padStart(digits - 1, "0"), "ascii"), NUL]);
+};
+const createHeader = (fields) => {
+    const parts = [
+        stringField(fields.name, 100),
+        numberField((fields.mode ?? 0) & 0o7777, 8),
+        numberField(0, 8),
+        numberField(0, 8),
+        numberField(fields.size, 12),
+        numberField(0, 12),
+        Buffer.from("        ", "ascii"),
+        Buffer.from(fields.type, "ascii"),
+        stringField(fields.linkname ?? "", 100),
+        POSIX_MAGIC,
+        stringField("", 32),
+        stringField("", 32),
+        numberField(0, 8),
+        numberField(0, 8),
+        stringField("", 155),
+    ];
+    const header = Buffer.alloc(BLOCK_SIZE);
+    Buffer.concat(parts).copy(header);
+    let checksum = 0;
+    for (const byte of header) {
+        checksum += byte;
+    }
+    Buffer.from(checksum.toString(8).padStart(6, "0") + "\0 ", "ascii").copy(header, 148);
+    return header;
+};
+const padToBlock = (size) => {
+    const remainder = size % BLOCK_SIZE;
+    return remainder === 0 ? Buffer.alloc(0) : Buffer.alloc(BLOCK_SIZE - remainder);
+};
+const createPaxHeader = (records) => {
+    const encodedRecords = [];
+    for (const [keyword, value] of records) {
+        const key = Buffer.from(keyword, "utf8");
+        const data = Buffer.from(value, "utf8");
+        const base = key.length + data.length + 3;
+        let n = 0;
+        let p = 0;
+        while (true) {
+            n = base + String(p).length;
+            if (n === p) {
+                break;
+            }
+            p = n;
+        }
+        encodedRecords.push(Buffer.from(`${p} `, "ascii"), key, Buffer.from("=", "ascii"), data);
+        encodedRecords.push(Buffer.from("\n", "ascii"));
+    }
+    const payload = Buffer.concat(encodedRecords);
+    return Buffer.concat([
+        createHeader({ name: "././@PaxHeader", size: payload.length, type: "x" }),
+        payload,
+        padToBlock(payload.length),
+    ]);
+};
+const createTarEntryHeader = (info) => {
+    const pax = [];
+    if (!isAscii(info.name) || info.name.length > 100) {
+        pax.push(["path", info.name]);
+    }
+    if (!isAscii(info.linkname) || info.linkname.length > 100) {
+        pax.push(["linkpath", info.linkname]);
+    }
+    let size = info.size;
+    if (size < 0 || size >= 8 ** 11) {
+        pax.push(["size", String(info.size)]);
+        size = 0;
+    }
+    const header = createHeader({
+        name: info.name,
+        mode: info.mode,
+        size,
+        type: TYPE_FLAGS[info.type],
+        linkname: info.linkname,
+    });
+    return pax.length > 0 ? Buffer.concat([createPaxHeader(pax), header]) : header;
+};
+exports.createTarEntryHeader = createTarEntryHeader;
+/** Sequential PAX tar writer; `close` writes the end-of-archive blocks. */
+class PaxTarWriter {
+    constructor(sink) {
+        this.sink = sink;
+        this.written = 0;
+    }
+    async emit(chunk) {
+        if (chunk.length === 0) {
+            return;
+        }
+        this.written += chunk.length;
+        await this.sink(chunk);
+    }
+    async addEntry(info, content) {
+        await this.emit((0, exports.createTarEntryHeader)(info));
+        if (info.type !== "file") {
+            return;
+        }
+        let copied = 0;
+        if (content) {
+            for await (const chunk of content) {
+                copied += chunk.length;
+                if (copied > info.size) {
+                    throw new Error(`tar entry "${info.name}" produced more data than its declared size`);
+                }
+                await this.emit(chunk);
+            }
+        }
+        if (copied !== info.size) {
+            throw new Error(`tar entry "${info.name}" was truncated`);
+        }
+        await this.emit(padToBlock(info.size));
+    }
+    async close() {
+        await this.emit(Buffer.alloc(BLOCK_SIZE * 2));
+        const remainder = this.written % RECORD_SIZE;
+        if (remainder !== 0) {
+            await this.emit(Buffer.alloc(RECORD_SIZE - remainder));
+        }
+    }
+}
+exports.PaxTarWriter = PaxTarWriter;
+class ByteReader {
+    constructor(source) {
+        this.pending = Buffer.alloc(0);
+        this.done = false;
+        const raw = source[Symbol.asyncIterator]();
+        this.iterator = {
+            next: async () => {
+                const result = await raw.next();
+                return result.done
+                    ? { done: true, value: undefined }
+                    : {
+                        done: false,
+                        value: Buffer.isBuffer(result.value) ? result.value : Buffer.from(result.value),
+                    };
+            },
+        };
+    }
+    async fill() {
+        if (this.done) {
+            return false;
+        }
+        const result = await this.iterator.next();
+        if (result.done) {
+            this.done = true;
+            return false;
+        }
+        this.pending = this.pending.length ? Buffer.concat([this.pending, result.value]) : result.value;
+        return true;
+    }
+    /** Read exactly `length` bytes, or return null at a clean end of stream. */
+    async readExact(length) {
+        while (this.pending.length < length) {
+            if (!(await this.fill())) {
+                if (this.pending.length === 0) {
+                    return null;
+                }
+                throw new Error("unexpected end of tar stream");
+            }
+        }
+        const chunk = this.pending.subarray(0, length);
+        this.pending = this.pending.subarray(length);
+        return chunk;
+    }
+    async *readChunks(length) {
+        let remaining = length;
+        while (remaining > 0) {
+            if (this.pending.length === 0 && !(await this.fill())) {
+                throw new Error("unexpected end of tar stream");
+            }
+            const take = Math.min(remaining, this.pending.length);
+            const chunk = this.pending.subarray(0, take);
+            this.pending = this.pending.subarray(take);
+            remaining -= take;
+            yield chunk;
+        }
+    }
+    async skip(length) {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        for await (const _chunk of this.readChunks(length)) {
+            // discard
+        }
+    }
+}
+const parseOctal = (field) => {
+    if (field.length > 0 && field[0] & 0x80) {
+        let value = 0n;
+        for (let index = 0; index < field.length; index += 1) {
+            value = (value << 8n) | BigInt(index === 0 ? field[0] & 0x7f : field[index]);
+        }
+        return Number(value);
+    }
+    const text = field.toString("ascii").replace(/\0.*$/s, "").trim();
+    if (text === "") {
+        return 0;
+    }
+    if (!/^[0-7]+$/.test(text)) {
+        throw new Error("invalid tar header number field");
+    }
+    return parseInt(text, 8);
+};
+const parseString = (field) => {
+    const end = field.indexOf(0);
+    return (end === -1 ? field : field.subarray(0, end)).toString("utf8");
+};
+const parsePaxRecords = (payload) => {
+    const records = new Map();
+    let offset = 0;
+    while (offset < payload.length) {
+        const space = payload.indexOf(0x20, offset);
+        if (space === -1) {
+            throw new Error("invalid PAX header record");
+        }
+        const length = parseInt(payload.subarray(offset, space).toString("ascii"), 10);
+        if (!Number.isInteger(length) || length <= 0 || offset + length > payload.length) {
+            throw new Error("invalid PAX header record");
+        }
+        const record = payload.subarray(space + 1, offset + length - 1).toString("utf8");
+        const separator = record.indexOf("=");
+        if (separator === -1) {
+            throw new Error("invalid PAX header record");
+        }
+        records.set(record.slice(0, separator), record.slice(separator + 1));
+        offset += length;
+    }
+    return records;
+};
+/**
+ * Iterate over tar entries from a stream. Callers must fully consume an
+ * entry's content before advancing; unread content is skipped.
+ */
+async function* readTarEntries(source) {
+    const reader = new ByteReader(source);
+    const globalPax = new Map();
+    let paxOverrides = null;
+    let gnuLongName = null;
+    let gnuLongLink = null;
+    while (true) {
+        const header = await reader.readExact(BLOCK_SIZE);
+        if (header === null || header.every((byte) => byte === 0)) {
+            return;
+        }
+        const typeflag = header.subarray(156, 157).toString("ascii");
+        const size = parseOctal(header.subarray(124, 136));
+        if (!Number.isSafeInteger(size) || size < 0)
+            throw new Error("invalid tar entry size");
+        if (["x", "g", "L", "K"].includes(typeflag) && size > 16 * 1024 * 1024)
+            throw new Error("tar metadata exceeds the size limit");
+        const padded = size + (BLOCK_SIZE - (size % BLOCK_SIZE || BLOCK_SIZE));
+        if (typeflag === "x" || typeflag === "g") {
+            const payload = await reader.readExact(padded);
+            if (payload === null) {
+                throw new Error("unexpected end of tar stream");
+            }
+            if (typeflag === "x") {
+                paxOverrides = parsePaxRecords(payload.subarray(0, size));
+            }
+            else {
+                for (const [key, value] of parsePaxRecords(payload.subarray(0, size))) {
+                    if (value)
+                        globalPax.set(key, value);
+                    else
+                        globalPax.delete(key);
+                }
+            }
+            continue;
+        }
+        if (typeflag === "L" || typeflag === "K") {
+            const payload = await reader.readExact(padded);
+            if (payload === null) {
+                throw new Error("unexpected end of tar stream");
+            }
+            const value = parseString(payload.subarray(0, size));
+            if (typeflag === "L") {
+                gnuLongName = value;
+            }
+            else {
+                gnuLongLink = value;
+            }
+            continue;
+        }
+        let name = parseString(header.subarray(0, 100));
+        const magic = header.subarray(257, 263).toString("binary");
+        const prefix = parseString(header.subarray(345, 500));
+        if (magic.startsWith("ustar") && prefix && typeflag !== "L") {
+            name = `${prefix}/${name}`;
+        }
+        if (gnuLongName !== null) {
+            name = gnuLongName;
+        }
+        let linkname = parseString(header.subarray(157, 257));
+        if (gnuLongLink !== null) {
+            linkname = gnuLongLink;
+        }
+        const mode = parseOctal(header.subarray(100, 108)) & 0o7777;
+        let entrySize = size;
+        paxOverrides = new Map([...globalPax, ...(paxOverrides ?? [])]);
+        if (paxOverrides) {
+            const path = paxOverrides.get("path");
+            if (path !== undefined) {
+                name = path;
+            }
+            const linkpath = paxOverrides.get("linkpath");
+            if (linkpath !== undefined) {
+                linkname = linkpath;
+            }
+            const paxSize = paxOverrides.get("size");
+            if (paxSize !== undefined) {
+                entrySize = Number(paxSize);
+                if (!Number.isSafeInteger(entrySize) || entrySize < 0) {
+                    throw new Error("invalid PAX size record");
+                }
+            }
+        }
+        paxOverrides = null;
+        gnuLongName = null;
+        gnuLongLink = null;
+        let remaining = entrySize;
+        const content = async function* () {
+            const total = remaining;
+            remaining = 0;
+            yield* reader.readChunks(total);
+        };
+        yield {
+            name,
+            size: entrySize,
+            typeflag,
+            mode,
+            linkname,
+            isFile: typeflag === "0" || typeflag === "\0" || typeflag === "7",
+            content,
+        };
+        if (remaining > 0) {
+            await reader.skip(remaining);
+            remaining = 0;
+        }
+        const padding = entrySize % BLOCK_SIZE === 0 ? 0 : BLOCK_SIZE - (entrySize % BLOCK_SIZE);
+        if (padding > 0) {
+            await reader.skip(padding);
+        }
+    }
+}

package/dist/sandbox/image-build/upload.d.ts

@@ -0,0 +1,10 @@
+import { SandboxImageBuildUpload } from "../../types/sandbox";
+import { DockerImageBuildArtifact } from "./artifacts";
+export declare const uploadImageBuildArtifact: (upload: SandboxImageBuildUpload, artifactPath: string, options?: {
+    timeout?: number | null;
+}) => Promise<void>;
+/** Upload only the artifacts the server requested, verifying each request. */
+export declare const uploadMissingImageBuildArtifacts: (uploads: SandboxImageBuildUpload[] | undefined, artifacts: Record<string, DockerImageBuildArtifact>, options: {
+    label: string;
+    timeout?: number | null;
+}) => Promise<void>;

package/dist/sandbox/image-build/upload.js

@@ -0,0 +1,143 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadMissingImageBuildArtifacts = exports.uploadImageBuildArtifact = void 0;
+const node_fetch_1 = __importDefault(require("node-fetch"));
+const fs_1 = require("fs");
+const stream_1 = require("stream");
+const common_1 = require("./common");
+class UploadStatusError extends Error {
+    constructor(statusCode, body) {
+        super(`image artifact upload failed: ${statusCode}: ${body}`.trimEnd());
+        this.statusCode = statusCode;
+        this.name = "UploadStatusError";
+    }
+}
+const uploadOnce = async (upload, artifactPath, method, timeoutSeconds) => {
+    const size = (0, fs_1.statSync)(artifactPath).size;
+    const headers = { ...(upload.headers || {}) };
+    if (!Object.keys(headers).some((key) => key.toLowerCase() === "content-length")) {
+        headers["content-length"] = String(size);
+    }
+    const controller = new AbortController();
+    let timer;
+    const resetTimer = () => {
+        if (timeoutSeconds === null || timeoutSeconds === undefined) {
+            return;
+        }
+        if (timer) {
+            clearTimeout(timer);
+        }
+        timer = setTimeout(() => controller.abort(), timeoutSeconds * 1000);
+    };
+    const source = (0, fs_1.createReadStream)(artifactPath);
+    const body = new stream_1.PassThrough();
+    source.on("data", () => resetTimer());
+    source.on("error", (error) => body.destroy(error));
+    source.pipe(body);
+    resetTimer();
+    try {
+        const response = await (0, node_fetch_1.default)(upload.url, {
+            method,
+            headers,
+            body: size === 0 ? undefined : body,
+            signal: controller.signal,
+        });
+        resetTimer();
+        const text = await response.text();
+        if (response.ok) {
+            return;
+        }
+        throw new UploadStatusError(response.status, text.trim());
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new Error(`image artifact upload timed out after ${timeoutSeconds}s of inactivity`);
+        }
+        throw error;
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+        source.destroy();
+    }
+};
+const uploadImageBuildArtifact = async (upload, artifactPath, options = {}) => {
+    const artifactSize = (0, fs_1.statSync)(artifactPath).size;
+    if (upload.maxUploadBytes > 0 && artifactSize > upload.maxUploadBytes) {
+        throw new Error(`image artifact exceeds the server upload limit (${artifactSize} > ${upload.maxUploadBytes})`);
+    }
+    const method = (upload.method || "PUT").trim().toUpperCase();
+    const attempts = method === "PUT" ? 3 : 1;
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            await uploadOnce(upload, artifactPath, method, options.timeout);
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            if (error instanceof UploadStatusError) {
+                if (error.statusCode !== 408 && error.statusCode !== 429 && error.statusCode < 500) {
+                    throw error;
+                }
+            }
+        }
+        if (attempt < attempts) {
+            await (0, common_1.sleep)(attempt * 0.25);
+        }
+    }
+    throw lastError;
+};
+exports.uploadImageBuildArtifact = uploadImageBuildArtifact;
+/** Upload only the artifacts the server requested, verifying each request. */
+const uploadMissingImageBuildArtifacts = async (uploads, artifacts, options) => {
+    const requested = [];
+    const seen = new Set();
+    for (const upload of uploads ?? []) {
+        const digest = (upload.sha256 || "").trim().toLowerCase();
+        const artifact = artifacts[digest];
+        if (!digest || artifact === undefined) {
+            throw new Error(`server requested unknown ${options.label} "${upload.sha256}"`);
+        }
+        if (seen.has(digest)) {
+            throw new Error(`server requested duplicate ${options.label} ${digest}`);
+        }
+        seen.add(digest);
+        const method = (upload.method || "PUT").trim().toUpperCase();
+        if (method !== "PUT") {
+            throw new Error(`server requested unsupported ${options.label} upload method "${upload.method}"`);
+        }
+        if (upload.maxUploadBytes > 0 && artifact.sizeBytes > upload.maxUploadBytes) {
+            throw new Error(`${options.label} ${digest} exceeds the server upload limit ` +
+                `(${artifact.sizeBytes} > ${upload.maxUploadBytes})`);
+        }
+        requested.push([upload, artifact, digest]);
+    }
+    if (requested.length === 0) {
+        return;
+    }
+    let next = 0;
+    let failed = false;
+    const worker = async () => {
+        while (!failed && next < requested.length) {
+            const [upload, artifact, digest] = requested[next];
+            next += 1;
+            try {
+                await (0, exports.uploadImageBuildArtifact)(upload, artifact.path, { timeout: options.timeout });
+            }
+            catch (error) {
+                failed = true;
+                throw new Error(`upload ${options.label} ${digest}: ${error instanceof Error ? error.message : error}`);
+            }
+        }
+    };
+    const results = await Promise.allSettled(Array.from({ length: Math.min(4, requested.length) }, () => worker()));
+    const failure = results.find((result) => result.status === "rejected");
+    if (failure?.status === "rejected")
+        throw failure.reason;
+};
+exports.uploadMissingImageBuildArtifacts = uploadMissingImageBuildArtifacts;

package/dist/sandbox/index.d.ts

@@ -1,4 +1,5 @@
 export { RuntimeTransport } from "./base";
 export { SandboxProcessesApi, SandboxProcessHandle } from "./process";
-export { SandboxFilesApi, SandboxWatchDirHandle } from "./files";
+export { SandboxFilesApi, SandboxFileWatchHandle, SandboxWatchDirHandle } from "./files";
 export { SandboxTerminalApi, SandboxTerminalConnection, SandboxTerminalHandle } from "./terminal";
+export { SandboxHandle } from "../services/sandboxes";

package/dist/sandbox/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SandboxTerminalHandle = exports.SandboxTerminalConnection = exports.SandboxTerminalApi = exports.SandboxWatchDirHandle = exports.SandboxFilesApi = exports.SandboxProcessHandle = exports.SandboxProcessesApi = exports.RuntimeTransport = void 0;
+exports.SandboxHandle = exports.SandboxTerminalHandle = exports.SandboxTerminalConnection = exports.SandboxTerminalApi = exports.SandboxWatchDirHandle = exports.SandboxFileWatchHandle = exports.SandboxFilesApi = exports.SandboxProcessHandle = exports.SandboxProcessesApi = exports.RuntimeTransport = void 0;
 var base_1 = require("./base");
 Object.defineProperty(exports, "RuntimeTransport", { enumerable: true, get: function () { return base_1.RuntimeTransport; } });
 var process_1 = require("./process");
@@ -8,8 +8,11 @@ Object.defineProperty(exports, "SandboxProcessesApi", { enumerable: true, get: f
 Object.defineProperty(exports, "SandboxProcessHandle", { enumerable: true, get: function () { return process_1.SandboxProcessHandle; } });
 var files_1 = require("./files");
 Object.defineProperty(exports, "SandboxFilesApi", { enumerable: true, get: function () { return files_1.SandboxFilesApi; } });
+Object.defineProperty(exports, "SandboxFileWatchHandle", { enumerable: true, get: function () { return files_1.SandboxFileWatchHandle; } });
 Object.defineProperty(exports, "SandboxWatchDirHandle", { enumerable: true, get: function () { return files_1.SandboxWatchDirHandle; } });
 var terminal_1 = require("./terminal");
 Object.defineProperty(exports, "SandboxTerminalApi", { enumerable: true, get: function () { return terminal_1.SandboxTerminalApi; } });
 Object.defineProperty(exports, "SandboxTerminalConnection", { enumerable: true, get: function () { return terminal_1.SandboxTerminalConnection; } });
 Object.defineProperty(exports, "SandboxTerminalHandle", { enumerable: true, get: function () { return terminal_1.SandboxTerminalHandle; } });
+var sandboxes_1 = require("../services/sandboxes");
+Object.defineProperty(exports, "SandboxHandle", { enumerable: true, get: function () { return sandboxes_1.SandboxHandle; } });

package/dist/sandbox/process-output.d.ts

@@ -0,0 +1,36 @@
+/** Collection and validation of the receiver's command event stream. */
+import { HyperbrowserError } from "../error";
+import { SandboxProcessOutputEvent, SandboxProcessResult } from "../types/sandbox";
+import { RuntimeSSEEvent } from "./base";
+export declare const DEFAULT_MAX_PROCESS_OUTPUT_BYTES: number;
+export interface RawProcessResult extends Partial<SandboxProcessResult> {
+    id: string;
+    status: SandboxProcessResult["status"];
+    exit_code?: number | null;
+    stdout: string;
+    stderr: string;
+    started_at: number;
+    completed_at?: number | null;
+    error?: string | null;
+    output_truncated?: boolean;
+    last_seq?: number | null;
+}
+export declare const normalizeProcessResult: (result: RawProcessResult) => SandboxProcessResult;
+export declare class ProcessOutput {
+    readonly processId: string;
+    readonly maxBytes: number;
+    size: number;
+    seq: number;
+    readonly events: SandboxProcessOutputEvent[];
+    result: SandboxProcessResult | null;
+    error: HyperbrowserError | null;
+    private readonly chunks;
+    private readonly decoders;
+    constructor(processId: string, maxBytes: number);
+    failure(message: string, code?: string): HyperbrowserError;
+    consume(event: RuntimeSSEEvent): void;
+    private decodePayload;
+    private consumeOutput;
+    private consumeDone;
+}
+export declare const validateOutputLimit: (value: unknown) => void;