@hyperbrowser/sdk 0.93.0 → 1.0.1

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

@@ -0,0 +1,472 @@
+"use strict";
+/** Local Docker image inspection and layer-manifest packaging for prebuilt imports. */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageDockerImageManifest = exports.prepareDockerImageManifestSource = exports.dockerImageDigest = exports.runDockerCommand = exports.DockerCommandError = void 0;
+const stream_1 = require("stream");
+const promises_1 = require("stream/promises");
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const events_1 = require("events");
+const os_1 = require("os");
+const path = __importStar(require("path"));
+const util_1 = require("util");
+const artifacts_1 = require("./artifacts");
+const common_1 = require("./common");
+const context_1 = require("./context");
+const image_init_1 = require("./image-init");
+const tar_1 = require("./tar");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+const MAX_DOCKER_SAVE_ENTRIES = 4096;
+const MAX_DOCKER_SAVE_ARCHIVE_BYTES = 5 * 1024 * 1024 * 1024;
+const MAX_DOCKER_SAVE_METADATA_BYTES = 16 * 1024 * 1024;
+const MAX_DOCKER_IMAGE_LAYERS = 512;
+class DockerCommandError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DockerCommandError";
+    }
+}
+exports.DockerCommandError = DockerCommandError;
+const describeCommandFailure = (args, error) => {
+    if (error.code === "ENOENT") {
+        return new DockerCommandError("docker CLI is required for local Docker image operations");
+    }
+    const stderr = String(error.stderr ?? "").trim();
+    const command = ["docker", ...args].join(" ");
+    if (stderr) {
+        return new DockerCommandError(`${command}: ${stderr}`);
+    }
+    return new DockerCommandError(`${command} failed with code ${String(error.code ?? "unknown")}`);
+};
+const runDockerCommand = async (args) => {
+    try {
+        const { stdout } = await execFileAsync("docker", args, {
+            maxBuffer: MAX_DOCKER_SAVE_METADATA_BYTES,
+            encoding: "utf8",
+        });
+        return stdout;
+    }
+    catch (error) {
+        throw describeCommandFailure(args, error);
+    }
+};
+exports.runDockerCommand = runDockerCommand;
+const normalizeSha256Digest = (value) => {
+    const digest = String(value ?? "")
+        .trim()
+        .toLowerCase();
+    if (!digest.startsWith("sha256:") || !common_1.SHA256_HEX_PATTERN.test(digest.slice(7))) {
+        throw new Error("docker inspect returned an invalid linux/amd64 image digest");
+    }
+    return digest;
+};
+const unsupportedDockerImagePlatformError = (dockerImage, actualPlatform, expectedPlatform) => new Error([
+    "docker image platform is not supported for Hyperbrowser image builds: " +
+        `${dockerImage} is ${actualPlatform} (expected ${expectedPlatform}).`,
+    `Please rebuild the image for ${expectedPlatform} and try again:`,
+    "  cd <docker-build-context-root>",
+    `  docker buildx build --platform ${expectedPlatform} -t ${dockerImage} ` +
+        "-f <path/to/Dockerfile> --load .",
+].join("\n"));
+const inspectDockerImage = async (dockerImage, platform) => {
+    const output = (await (0, exports.runDockerCommand)([
+        "image",
+        "inspect",
+        `--platform=${platform}`,
+        "--format",
+        "{{json .}}",
+        dockerImage,
+    ])).trim();
+    let inspection;
+    try {
+        inspection = JSON.parse(output);
+    }
+    catch {
+        throw new Error("decode Docker image inspection");
+    }
+    if (!(0, common_1.isRecord)(inspection)) {
+        throw new Error("docker inspect returned an invalid image inspection");
+    }
+    const actualPlatform = `${String(inspection.Os ?? "")}/${String(inspection.Architecture ?? "")}`.toLowerCase();
+    if (actualPlatform !== platform.trim().toLowerCase()) {
+        throw unsupportedDockerImagePlatformError(dockerImage, actualPlatform, platform);
+    }
+    return inspection;
+};
+const inspectDockerContainerConfig = async (containerId) => {
+    const output = (await (0, exports.runDockerCommand)(["container", "inspect", "--format", "{{json .Config}}", containerId])).trim();
+    if (!output || output === "null") {
+        throw new Error("docker inspect returned empty container config");
+    }
+    try {
+        return (0, common_1.requireRecord)(JSON.parse(output), "Docker container config");
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new Error("decode Docker container config");
+        }
+        throw error;
+    }
+};
+const removeDockerContainer = async (containerId) => {
+    try {
+        await (0, exports.runDockerCommand)(["rm", "-f", containerId]);
+    }
+    catch (error) {
+        if (!(error instanceof DockerCommandError)) {
+            throw error;
+        }
+    }
+};
+/** Inspect platform identity with Docker API 1.49+, without temporary resources. */
+const dockerImageDigest = async (dockerImage, options = {}) => {
+    const platform = options.platform ?? artifacts_1.IMAGE_BUILD_SOURCE_PLATFORM;
+    let inspection;
+    try {
+        inspection = await inspectDockerImage(dockerImage, platform);
+    }
+    catch (error) {
+        if (error instanceof DockerCommandError) {
+            const message = error.message;
+            if (message.includes('"--platform" requires API version') ||
+                message.includes("unknown flag: --platform")) {
+                throw new Error("Local Docker image imports require a Docker CLI and Engine supporting API 1.49 " +
+                    "or newer (Docker 28.1+). Upgrade Docker or remove an older DOCKER_API_VERSION override.");
+            }
+        }
+        throw error;
+    }
+    return normalizeSha256Digest(inspection.Id);
+};
+exports.dockerImageDigest = dockerImageDigest;
+const manifestSource = (imageDigest, config, cleanup) => ({
+    imageDigest,
+    config,
+    imageConfigUser: String(config.User ?? "").trim(),
+    imageInit: (0, image_init_1.deriveAutoImageInit)(config),
+    cleanup,
+});
+const prepareDockerImageManifestSource = async (dockerImage, options = {}) => {
+    const platform = options.platform ?? artifacts_1.IMAGE_BUILD_SOURCE_PLATFORM;
+    try {
+        const inspection = await inspectDockerImage(dockerImage, platform);
+        return manifestSource(normalizeSha256Digest(inspection.Id), (0, common_1.requireRecord)(inspection.Config, "Docker image config"), async () => undefined);
+    }
+    catch (error) {
+        if (!(error instanceof DockerCommandError)) {
+            throw error;
+        }
+    }
+    const containerId = (await (0, exports.runDockerCommand)(["create", `--platform=${platform}`, dockerImage])).trim();
+    if (!containerId) {
+        throw new Error("docker create returned empty container ID");
+    }
+    try {
+        const config = await inspectDockerContainerConfig(containerId);
+        let digest;
+        try {
+            digest = await (0, exports.runDockerCommand)([
+                "image",
+                "inspect",
+                `--platform=${platform}`,
+                "--format",
+                "{{.Id}}",
+                dockerImage,
+            ]);
+        }
+        catch (error) {
+            if (!(error instanceof DockerCommandError)) {
+                throw error;
+            }
+            digest = await (0, exports.runDockerCommand)([
+                "container",
+                "inspect",
+                "--format",
+                "{{.Image}}",
+                containerId,
+            ]);
+        }
+        return manifestSource(normalizeSha256Digest(digest), config, () => removeDockerContainer(containerId));
+    }
+    catch (error) {
+        await removeDockerContainer(containerId);
+        throw error;
+    }
+};
+exports.prepareDockerImageManifestSource = prepareDockerImageManifestSource;
+const normalizeDockerSaveEntryName = (raw) => {
+    if (!raw ||
+        raw.includes("\\") ||
+        raw.includes("\x00") ||
+        raw.includes("\r") ||
+        raw.includes("\n") ||
+        raw.startsWith("/")) {
+        throw new Error("docker image save contains an unsafe entry path");
+    }
+    const normalized = (0, common_1.posixNormpath)(raw);
+    if (normalized === "." ||
+        normalized === ".." ||
+        normalized.startsWith("../") ||
+        normalized !== raw) {
+        throw new Error("docker image save contains an unsafe entry path");
+    }
+    return normalized;
+};
+const storeStreamedEntry = async (source, destination, expectedSize, name) => {
+    const hasher = (0, crypto_1.createHash)("sha256");
+    const output = (0, fs_1.createWriteStream)(destination, { flags: "wx" });
+    let written = 0;
+    async function* chunks() {
+        for await (const chunk of source) {
+            hasher.update(chunk);
+            written += chunk.length;
+            yield chunk;
+        }
+    }
+    await (0, promises_1.pipeline)(stream_1.Readable.from(chunks(), { objectMode: false }), output);
+    if (written !== expectedSize) {
+        throw new Error(`docker image save entry "${name}" has truncated content`);
+    }
+    return { path: destination, sha256Hex: hasher.digest("hex"), sizeBytes: written };
+};
+const parseJsonObject = (data, label) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(data));
+    }
+    catch {
+        throw new Error(`${label} is not valid JSON`);
+    }
+    return (0, common_1.requireRecord)(parsed, label);
+};
+const resolveDockerSaveManifest = (entries) => {
+    const manifestEntry = entries.get("manifest.json");
+    if (manifestEntry === undefined ||
+        manifestEntry.sizeBytes <= 0 ||
+        manifestEntry.sizeBytes > MAX_DOCKER_SAVE_METADATA_BYTES) {
+        throw new Error("docker image save manifest.json is missing or too large");
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse((0, fs_1.readFileSync)(manifestEntry.path, "utf8"));
+    }
+    catch {
+        throw new Error("docker image save manifest.json is invalid");
+    }
+    if (!Array.isArray(manifest) || manifest.length !== 1) {
+        throw new Error("docker image save must contain exactly one manifest entry");
+    }
+    const item = (0, common_1.requireRecord)(manifest[0], "Docker save manifest entry");
+    const configName = normalizeDockerSaveEntryName(String(item.Config ?? ""));
+    const configEntry = entries.get(configName);
+    if (configEntry === undefined ||
+        configEntry.sizeBytes <= 0 ||
+        configEntry.sizeBytes > MAX_DOCKER_SAVE_METADATA_BYTES) {
+        throw new Error("docker image save config is missing or too large");
+    }
+    const rawLayers = item.Layers;
+    if (!Array.isArray(rawLayers) || rawLayers.length > MAX_DOCKER_IMAGE_LAYERS) {
+        throw new Error("docker image save has too many layers");
+    }
+    const layers = [];
+    for (const rawLayer of rawLayers) {
+        const layerName = normalizeDockerSaveEntryName(String(rawLayer));
+        const layer = entries.get(layerName);
+        if (layer === undefined || layer.sizeBytes <= 0) {
+            throw new Error(`docker image save layer "${layerName}" is missing`);
+        }
+        layers.push(layer);
+    }
+    return [configEntry, layers];
+};
+const resolveOciImageDescriptor = (entries, imageDigest, config, layers) => {
+    const digestHex = imageDigest.slice("sha256:".length);
+    const entry = entries.get(`blobs/sha256/${digestHex}`);
+    if (entry === undefined ||
+        entry.sha256Hex !== digestHex ||
+        entry.sizeBytes <= 0 ||
+        entry.sizeBytes > MAX_DOCKER_SAVE_METADATA_BYTES) {
+        throw new Error("docker image save is missing its inspected OCI image manifest");
+    }
+    const data = (0, fs_1.readFileSync)(entry.path);
+    const descriptor = parseJsonObject(data, "OCI image manifest");
+    if (descriptor.schemaVersion !== 2) {
+        throw new Error("inspected Docker image descriptor is not a valid OCI image manifest");
+    }
+    const descriptorConfig = (0, common_1.requireRecord)(descriptor.config, "OCI config");
+    if (descriptorConfig.digest !== `sha256:${config.sha256}` ||
+        descriptorConfig.size !== config.sizeBytes) {
+        throw new Error("OCI image manifest config does not match Docker save config");
+    }
+    const descriptorLayers = descriptor.layers;
+    if (!Array.isArray(descriptorLayers) || descriptorLayers.length !== layers.length) {
+        throw new Error("OCI image manifest layer count does not match Docker save manifest");
+    }
+    descriptorLayers.forEach((rawLayer, index) => {
+        const item = (0, common_1.requireRecord)(rawLayer, `OCI layer ${index}`);
+        const layer = layers[index];
+        if (item.digest !== `sha256:${layer.sha256}` || item.size !== layer.sizeBytes) {
+            throw new Error(`OCI image manifest layer ${index} does not match Docker save manifest`);
+        }
+    });
+    return {
+        sha256: entry.sha256Hex,
+        sizeBytes: entry.sizeBytes,
+        dataBase64: data.toString("base64"),
+    };
+};
+const terminateProcess = async (child) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return;
+    }
+    child.kill("SIGTERM");
+    const timer = setTimeout(() => child.kill("SIGKILL"), 5000);
+    await (0, events_1.once)(child, "close");
+    clearTimeout(timer);
+};
+/** Stream `docker image save` into verified layer artifacts plus a manifest. */
+const packageDockerImageManifest = async (dockerImage, imageDigest, config, options = {}) => {
+    const platform = options.platform ?? artifacts_1.IMAGE_BUILD_SOURCE_PLATFORM;
+    const normalizedDigest = normalizeSha256Digest(imageDigest);
+    const workspace = (0, fs_1.mkdtempSync)(path.join(options.tempDir ?? (0, os_1.tmpdir)(), "hb-docker-image-layers-"));
+    let child = null;
+    try {
+        const args = ["image", "save", `--platform=${platform}`, dockerImage];
+        child = (0, child_process_1.spawn)("docker", args, { stdio: ["ignore", "pipe", "pipe"] });
+        const process = child;
+        const stdout = process.stdout;
+        if (!stdout || !process.stderr) {
+            throw new Error("docker image save did not provide stdout");
+        }
+        let stderr = "";
+        process.stderr.setEncoding("utf8");
+        process.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        const exit = new Promise((resolve, reject) => {
+            process.on("error", (error) => reject(describeCommandFailure(args, error)));
+            process.on("close", (code) => resolve(code));
+        });
+        exit.catch(() => undefined);
+        const entries = new Map();
+        let totalBytes = 0;
+        let index = 0;
+        const consume = async () => {
+            for await (const member of (0, tar_1.readTarEntries)(stdout)) {
+                if (index >= MAX_DOCKER_SAVE_ENTRIES) {
+                    throw new Error(`docker image save contains more than ${MAX_DOCKER_SAVE_ENTRIES} entries`);
+                }
+                const entryIndex = index;
+                index += 1;
+                if (!member.isFile) {
+                    continue;
+                }
+                const name = normalizeDockerSaveEntryName(member.name);
+                if (entries.has(name)) {
+                    throw new Error(`docker image save contains duplicate entry "${name}"`);
+                }
+                totalBytes += member.size;
+                if (member.size < 0 || totalBytes > MAX_DOCKER_SAVE_ARCHIVE_BYTES) {
+                    throw new Error("docker image save archive exceeds the size limit");
+                }
+                const destination = path.join(workspace, `entry-${String(entryIndex).padStart(4, "0")}`);
+                entries.set(name, await storeStreamedEntry(member.content(), destination, member.size, name));
+            }
+        };
+        try {
+            await consume();
+        }
+        catch (error) {
+            await terminateProcess(process);
+            throw error;
+        }
+        const returnCode = await exit;
+        if (returnCode !== 0) {
+            const message = stderr.trim();
+            throw new Error(message
+                ? `docker image save ${dockerImage} failed: ${message}`
+                : `docker image save ${dockerImage} failed with code ${returnCode}`);
+        }
+        child = null;
+        const [configEntry, layerEntries] = resolveDockerSaveManifest(entries);
+        const configBytes = (0, fs_1.readFileSync)(configEntry.path);
+        parseJsonObject(configBytes, "Docker image config");
+        const configDescriptor = {
+            sha256: configEntry.sha256Hex,
+            sizeBytes: configEntry.sizeBytes,
+            dataBase64: configBytes.toString("base64"),
+        };
+        const layerDescriptors = [];
+        const layers = {};
+        for (const layer of layerEntries) {
+            layerDescriptors.push({ sha256: layer.sha256Hex, sizeBytes: layer.sizeBytes });
+            const existing = layers[layer.sha256Hex];
+            if (existing !== undefined && existing.sizeBytes !== layer.sizeBytes) {
+                throw new Error(`Docker layer ${layer.sha256Hex} has conflicting sizes`);
+            }
+            if (existing === undefined) {
+                layers[layer.sha256Hex] = {
+                    path: layer.path,
+                    sha256Hex: layer.sha256Hex,
+                    sizeBytes: layer.sizeBytes,
+                    inputFormat: artifacts_1.DOCKER_IMAGE_MANIFEST_INPUT_FORMAT,
+                    sourcePlatform: platform,
+                    imageConfigUser: "",
+                };
+            }
+        }
+        const imageDescriptor = normalizedDigest !== `sha256:${configDescriptor.sha256}`
+            ? resolveOciImageDescriptor(entries, normalizedDigest, configDescriptor, layerDescriptors)
+            : undefined;
+        const manifest = {
+            version: 1,
+            imageDigest: normalizedDigest,
+            ...(imageDescriptor ? { descriptor: imageDescriptor } : {}),
+            config: configDescriptor,
+            layers: layerDescriptors,
+        };
+        const artifact = (0, context_1.writeManifestArtifact)(workspace, "docker-image-manifest.json", (0, context_1.canonicalManifestJson)(manifest), artifacts_1.DOCKER_IMAGE_MANIFEST_INPUT_FORMAT, {
+            imageConfigUser: String(config.User ?? "").trim(),
+            imageInit: (0, image_init_1.deriveAutoImageInit)(config),
+        });
+        return {
+            artifact,
+            manifest,
+            layers,
+            workspace,
+            cleanup: () => (0, artifacts_1.removeWorkspace)(workspace),
+        };
+    }
+    catch (error) {
+        if (child !== null) {
+            await terminateProcess(child);
+        }
+        (0, artifacts_1.removeWorkspace)(workspace);
+        throw error;
+    }
+};
+exports.packageDockerImageManifest = packageDockerImageManifest;

package/dist/sandbox/image-build/dockerfile-analysis.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Conservative Dockerfile analysis for remote build context selection.
+ *
+ * This module intentionally does not try to execute or fully reproduce the
+ * BuildKit Dockerfile frontend. It recognizes the context-consuming syntax the
+ * SDK can analyze safely and requests a full context for anything ambiguous.
+ * That keeps sparse uploads an optimization rather than a correctness
+ * requirement.
+ */
+export type DockerfileSourceAnalysis = {
+    groups: string[][];
+    fallbackReason: string;
+};
+/** POSIX `shlex.split` word splitting. */
+export declare const shlexSplit: (value: string) => string[];
+/** Return local source groups or a reason to upload the full context. */
+export declare const analyzeDockerfileSources: (data: Buffer) => DockerfileSourceAnalysis;