@blaxel/core 0.2.67-preview.88 → 0.2.67-preview.90

package/dist/esm/common/settings.js

@@ -3,8 +3,8 @@ import { authentication } from "../authentication/index.js";
 import { env } from "../common/env.js";
 import { fs, os, path } from "../common/node.js";
 // Build info - these placeholders are replaced at build time by build:replace-imports
-const BUILD_VERSION = "0.2.67-preview.88";
-const BUILD_COMMIT = "5357b4855456af1c4f172b8489f4f5c520c79a24";
+const BUILD_VERSION = "0.2.67-preview.90";
+const BUILD_COMMIT = "0b5a3b81059ce9031873088b36eed87a0c589f65";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 // Cache for config.yaml tracking value
 let configTrackingValue = null;

package/dist/esm/image/image.browser.js

@@ -0,0 +1,80 @@
+export const SANDBOX_API_IMAGE = "ghcr.io/blaxel-ai/sandbox";
+export const SANDBOX_API_PATH = "/usr/local/bin/sandbox-api";
+function throwBrowserError() {
+    throw new Error("ImageInstance is only available in Node.js environments. " +
+        "Image building requires file system operations that are not supported in browsers.");
+}
+/**
+ * A fluent builder for creating sandbox images programmatically.
+ *
+ * NOTE: This class is only available in Node.js environments.
+ * In browser environments, all methods will throw an error.
+ */
+export class ImageInstance {
+    _context;
+    constructor(_context) {
+        this._context = _context;
+        throwBrowserError();
+    }
+    static fromRegistry(_tag) {
+        throwBrowserError();
+    }
+    workdir(_path) {
+        throwBrowserError();
+    }
+    runCommands(..._commands) {
+        throwBrowserError();
+    }
+    env(_variables) {
+        throwBrowserError();
+    }
+    copy(_source, _destination) {
+        throwBrowserError();
+    }
+    addLocalFile(_sourcePath, _destination, _contextName) {
+        throwBrowserError();
+    }
+    addLocalDir(_sourcePath, _destination, _contextName) {
+        throwBrowserError();
+    }
+    expose(..._ports) {
+        throwBrowserError();
+    }
+    entrypoint(..._args) {
+        throwBrowserError();
+    }
+    user(_user) {
+        throwBrowserError();
+    }
+    label(_labels) {
+        throwBrowserError();
+    }
+    arg(_name, _defaultValue) {
+        throwBrowserError();
+    }
+    get dockerfile() {
+        throw new Error("ImageInstance is only available in Node.js environments. " +
+            "Image building requires file system operations that are not supported in browsers.");
+    }
+    get hash() {
+        throw new Error("ImageInstance is only available in Node.js environments. " +
+            "Image building requires file system operations that are not supported in browsers.");
+    }
+    get baseImage() {
+        throw new Error("ImageInstance is only available in Node.js environments. " +
+            "Image building requires file system operations that are not supported in browsers.");
+    }
+    write(_outputPath, _name) {
+        throwBrowserError();
+    }
+    writeTemp() {
+        throwBrowserError();
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async build(_options) {
+        throwBrowserError();
+    }
+    buildSync(_options) {
+        throwBrowserError();
+    }
+}

package/dist/esm/image/image.js

@@ -0,0 +1,560 @@
+import { DockerfileParser } from "dockerfile-ast";
+import { crypto, fs, os, path } from "../common/node.js";
+import { settings } from "../common/settings.js";
+import archiver from "archiver";
+function ensureNodeEnvironment() {
+    if (!fs || !os || !path || !crypto) {
+        throw new Error("Image is only available in Node.js environments. File system operations are not supported in browsers.");
+    }
+}
+export const SANDBOX_API_IMAGE = "ghcr.io/blaxel-ai/sandbox";
+export const SANDBOX_API_PATH = "/usr/local/bin/sandbox-api";
+function generateDockerfile(context) {
+    // Build the raw Dockerfile content
+    const lines = [`FROM ${context.baseImage}`];
+    lines.push(...context.instructions);
+    const rawContent = lines.join("\n") + "\n";
+    // Parse using dockerfile-ast to validate syntax
+    const dockerfile = DockerfileParser.parse(rawContent);
+    // Check for any parsing errors by validating instruction count matches
+    const instructions = dockerfile.getInstructions();
+    if (instructions.length !== lines.length) {
+        throw new Error("Invalid Dockerfile syntax: instruction count mismatch after parsing");
+    }
+    // Return raw content to preserve escaping in JSON-format instructions (ENTRYPOINT, CMD)
+    // The AST reconstruction via toString() doesn't properly preserve escape sequences
+    return rawContent;
+}
+function computeHash(context) {
+    ensureNodeEnvironment();
+    let content = generateDockerfile(context);
+    for (const localFile of context.localFiles) {
+        if (!fs.existsSync(localFile.sourcePath)) {
+            throw new Error(`Local file not found: ${localFile.sourcePath}. Cannot compute hash for missing files.`);
+        }
+        const stat = fs.statSync(localFile.sourcePath);
+        content += `\n${localFile.contextName}:${stat.mtimeMs}`;
+    }
+    return crypto.createHash("sha256").update(content).digest("hex").substring(0, 12);
+}
+function cloneContext(context) {
+    return {
+        baseImage: context.baseImage,
+        instructions: [...context.instructions],
+        localFiles: [...context.localFiles],
+        hasEntrypoint: context.hasEntrypoint,
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * A fluent builder for creating sandbox images programmatically.
+ *
+ * Similar to Modal's Image class, allows chaining operations to build
+ * a custom image from a base image.
+ *
+ * @example
+ * ```typescript
+ * const image = ImageInstance.fromRegistry("python:3.11-slim")
+ *   .runCommands("apt-get update && apt-get install -y git curl")
+ *   .workdir("/app")
+ *   .runCommands("pip install --upgrade pip")
+ *   .env({ PYTHONUNBUFFERED: "1" });
+ *
+ * await image.build({
+ *   name: "my-sandbox",
+ *   memory: 4096,
+ *   timeout: 900000,
+ *   onStatusChange: console.log,
+ *   sandboxVersion: "latest",
+ * });
+ * ```
+ */
+export class ImageInstance {
+    _context;
+    constructor(context) {
+        this._context = context;
+    }
+    /**
+     * Create an image from a Docker registry image.
+     *
+     * @param tag - The image tag (e.g., "python:3.11-slim", "ubuntu:22.04")
+     * @returns A new Image instance
+     */
+    static fromRegistry(tag) {
+        const context = {
+            baseImage: tag,
+            instructions: [],
+            localFiles: [],
+            hasEntrypoint: false,
+        };
+        return new ImageInstance(context);
+    }
+    /**
+     * Set the working directory for subsequent instructions.
+     *
+     * @param path - The working directory path inside the container
+     * @returns A new Image instance with the working directory set
+     */
+    workdir(path) {
+        const newContext = cloneContext(this._context);
+        newContext.instructions.push(`WORKDIR ${path}`);
+        return new ImageInstance(newContext);
+    }
+    /**
+     * Run shell commands in the image.
+     *
+     * @param commands - One or more shell commands to run
+     * @returns A new Image instance with the commands added
+     */
+    runCommands(...commands) {
+        const newContext = cloneContext(this._context);
+        for (const cmd of commands) {
+            newContext.instructions.push(`RUN ${cmd}`);
+        }
+        return new ImageInstance(newContext);
+    }
+    /**
+     * Set environment variables.
+     *
+     * @param variables - Environment variables as an object
+     * @returns A new Image instance with the environment variables set
+     */
+    env(variables) {
+        const keys = Object.keys(variables);
+        if (keys.length === 0) {
+            return this;
+        }
+        const newContext = cloneContext(this._context);
+        for (const [key, value] of Object.entries(variables)) {
+            newContext.instructions.push(`ENV ${key}="${value}"`);
+        }
+        return new ImageInstance(newContext);
+    }
+    /**
+     * Copy files or directories from the build context to the image.
+     *
+     * @param source - Source path (relative to build context)
+     * @param destination - Destination path in the image
+     * @returns A new Image instance with the copy instruction
+     */
+    copy(source, destination) {
+        const newContext = cloneContext(this._context);
+        newContext.instructions.push(`COPY ${source} ${destination}`);
+        return new ImageInstance(newContext);
+    }
+    /**
+     * Add a local file to the build context and copy it to the image.
+     *
+     * @param sourcePath - Path to the local file
+     * @param destination - Destination path in the image
+     * @param contextName - Optional name for the file in the build context
+     * @returns A new Image instance with the file added
+     */
+    addLocalFile(sourcePath, destination, contextName) {
+        ensureNodeEnvironment();
+        const source = path.resolve(sourcePath);
+        const name = contextName ?? path.basename(source);
+        const newContext = cloneContext(this._context);
+        newContext.localFiles.push({
+            sourcePath: source,
+            destinationPath: destination,
+            contextName: name,
+        });
+        newContext.instructions.push(`COPY ${name} ${destination}`);
+        return new ImageInstance(newContext);
+    }
+    /**
+     * Add a local directory to the build context and copy it to the image.
+     *
+     * @param sourcePath - Path to the local directory
+     * @param destination - Destination path in the image
+     * @param contextName - Optional name for the directory in the build context
+     * @returns A new Image instance with the directory added
+     */
+    addLocalDir(sourcePath, destination, contextName) {
+        ensureNodeEnvironment();
+        const source = path.resolve(sourcePath);
+        const name = contextName ?? path.basename(source);
+        const newContext = cloneContext(this._context);
+        newContext.localFiles.push({
+            sourcePath: source,
+            destinationPath: destination,
+            contextName: name,
+        });
+        newContext.instructions.push(`COPY ${name} ${destination}`);
+        return new ImageInstance(newContext);
+    }
+    /**
+     * Expose ports.
+     *
+     * @param ports - Port numbers to expose
+     * @returns A new Image instance with the ports exposed
+     */
+    expose(...ports) {
+        if (ports.length === 0) {
+            return this;
+        }
+        const newContext = cloneContext(this._context);
+        for (const port of ports) {
+            newContext.instructions.push(`EXPOSE ${port}`);
+        }
+        return new ImageInstance(newContext);
+    }
+    /**
+     * Set the entrypoint for the image.
+     *
+     * @param args - Entrypoint command and arguments
+     * @returns A new Image instance with the entrypoint set
+     */
+    entrypoint(...args) {
+        if (args.length === 0) {
+            return this;
+        }
+        // Format as JSON array for exec form, using JSON.stringify to properly escape quotes and special characters
+        const argsJson = args.map((arg) => JSON.stringify(arg)).join(", ");
+        const newContext = cloneContext(this._context);
+        newContext.instructions.push(`ENTRYPOINT [${argsJson}]`);
+        newContext.hasEntrypoint = true;
+        return new ImageInstance(newContext);
+    }
+    /**
+     * Set the user for subsequent instructions.
+     *
+     * @param user - Username or UID
+     * @returns A new Image instance with the user set
+     */
+    user(user) {
+        const newContext = cloneContext(this._context);
+        newContext.instructions.push(`USER ${user}`);
+        return new ImageInstance(newContext);
+    }
+    /**
+     * Add labels to the image.
+     *
+     * @param labels - Labels as an object
+     * @returns A new Image instance with the labels added
+     */
+    label(labels) {
+        const keys = Object.keys(labels);
+        if (keys.length === 0) {
+            return this;
+        }
+        const newContext = cloneContext(this._context);
+        for (const [key, value] of Object.entries(labels)) {
+            newContext.instructions.push(`LABEL ${key}="${value}"`);
+        }
+        return new ImageInstance(newContext);
+    }
+    /**
+     * Define a build argument.
+     *
+     * @param name - Argument name
+     * @param defaultValue - Optional default value
+     * @returns A new Image instance with the argument defined
+     */
+    arg(name, defaultValue) {
+        const newContext = cloneContext(this._context);
+        if (defaultValue !== undefined) {
+            newContext.instructions.push(`ARG ${name}=${defaultValue}`);
+        }
+        else {
+            newContext.instructions.push(`ARG ${name}`);
+        }
+        return new ImageInstance(newContext);
+    }
+    /**
+     * Get the generated Dockerfile content.
+     */
+    get dockerfile() {
+        return generateDockerfile(this._context);
+    }
+    /**
+     * Get a hash of the image configuration.
+     */
+    get hash() {
+        return computeHash(this._context);
+    }
+    /**
+     * Get the base image tag.
+     */
+    get baseImage() {
+        return this._context.baseImage;
+    }
+    _hasSandboxApi() {
+        const dockerfile = generateDockerfile(this._context);
+        return dockerfile.includes("sandbox-api") || dockerfile.includes("blaxel-ai/sandbox");
+    }
+    _prepareForSandbox(sandboxVersion = "latest") {
+        const newContext = cloneContext(this._context);
+        // Add sandbox-api if not already present
+        if (!this._hasSandboxApi()) {
+            const sandboxImage = `${SANDBOX_API_IMAGE}:${sandboxVersion}`;
+            const copyInstruction = `COPY --from=${sandboxImage} /sandbox-api ${SANDBOX_API_PATH}`;
+            newContext.instructions.push(copyInstruction);
+        }
+        // Add default entrypoint if not set by user
+        if (!newContext.hasEntrypoint) {
+            newContext.instructions.push(`ENTRYPOINT ["${SANDBOX_API_PATH}"]`);
+            newContext.hasEntrypoint = true;
+        }
+        return new ImageInstance(newContext);
+    }
+    /**
+     * Write the image to a deployable folder structure.
+     *
+     * @param outputPath - Path to the output directory
+     * @param name - Optional name for the generated folder (defaults to hash-based name)
+     * @returns Path to the generated folder
+     */
+    write(outputPath, name) {
+        ensureNodeEnvironment();
+        const outputDir = path.resolve(outputPath);
+        // Create folder name based on hash if not provided
+        if (!name) {
+            name = `image-${this.hash}`;
+        }
+        const buildDir = path.join(outputDir, name);
+        fs.mkdirSync(buildDir, { recursive: true });
+        // Generate Dockerfile
+        const dockerfilePath = path.join(buildDir, "Dockerfile");
+        fs.writeFileSync(dockerfilePath, generateDockerfile(this._context));
+        // Copy local files to build context
+        for (const localFile of this._context.localFiles) {
+            if (!fs.existsSync(localFile.sourcePath)) {
+                throw new Error(`Local file not found: ${localFile.sourcePath}`);
+            }
+            const dest = path.join(buildDir, localFile.contextName);
+            const stat = fs.statSync(localFile.sourcePath);
+            if (stat.isDirectory()) {
+                if (fs.existsSync(dest)) {
+                    fs.rmSync(dest, { recursive: true });
+                }
+                fs.cpSync(localFile.sourcePath, dest, { recursive: true });
+            }
+            else {
+                fs.cpSync(localFile.sourcePath, dest);
+            }
+        }
+        // Generate a manifest file with metadata
+        const manifest = {
+            base_image: this._context.baseImage,
+            hash: this.hash,
+            instructions_count: this._context.instructions.length,
+            local_files_count: this._context.localFiles.length,
+        };
+        const manifestPath = path.join(buildDir, "manifest.json");
+        fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+        return buildDir;
+    }
+    /**
+     * Write the image to a deployable folder in a temporary directory.
+     *
+     * @returns Path to the generated folder
+     */
+    writeTemp() {
+        ensureNodeEnvironment();
+        const tempDir = path.join(os.tmpdir(), `blaxel-image-${Date.now()}`);
+        fs.mkdirSync(tempDir, { recursive: true });
+        return this.write(tempDir);
+    }
+    async _createZip(buildDir) {
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            const archive = archiver("zip", {
+                zlib: { level: 9 },
+            });
+            archive.on("data", (chunk) => {
+                chunks.push(chunk);
+            });
+            archive.on("end", () => {
+                const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+                const result = new Uint8Array(totalLength);
+                let offset = 0;
+                for (const chunk of chunks) {
+                    result.set(chunk, offset);
+                    offset += chunk.length;
+                }
+                resolve(result);
+            });
+            archive.on("error", reject);
+            // Add all files from the build directory
+            archive.directory(buildDir, false);
+            void archive.finalize();
+        });
+    }
+    _createSandboxPayload(name, memory = 4096) {
+        const labels = {
+            "x-blaxel-auto-generated": "true",
+        };
+        const metadata = {
+            name,
+            labels,
+        };
+        const runtime = {
+            memory,
+        };
+        const spec = {
+            runtime,
+        };
+        return {
+            metadata,
+            spec,
+        };
+    }
+    async _createSandboxWithUpload(sandbox) {
+        const name = sandbox.metadata?.name || "";
+        const body = sandbox;
+        await settings.authenticate();
+        const headers = {
+            "Content-Type": "application/json",
+            ...settings.headers,
+        };
+        // Try PUT first (update), fall back to POST (create)
+        let response = await fetch(`${settings.baseUrl}/sandboxes/${name}?upload=true`, {
+            method: "PUT",
+            headers,
+            body: JSON.stringify(body),
+        });
+        // If 404, try create
+        if (response.status === 404) {
+            response = await fetch(`${settings.baseUrl}/sandboxes?upload=true`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+            });
+        }
+        const uploadUrl = response.headers.get("x-blaxel-upload-url");
+        return { response, uploadUrl };
+    }
+    async _uploadZip(uploadUrl, zipContent) {
+        const response = await fetch(uploadUrl, {
+            method: "PUT",
+            headers: {
+                "Content-Type": "application/zip",
+            },
+            body: zipContent,
+        });
+        if (response.status >= 400) {
+            const text = await response.text();
+            throw new Error(`Upload failed with status ${response.status}: ${text}`);
+        }
+    }
+    async _getSandboxStatus(name) {
+        await settings.authenticate();
+        const response = await fetch(`${settings.baseUrl}/sandboxes/${name}`, {
+            method: "GET",
+            headers: settings.headers,
+        });
+        if (response.status === 200) {
+            const data = (await response.json());
+            return data.status || null;
+        }
+        return null;
+    }
+    async _waitForDeployment(name, timeout = 900000, // 15 minutes in ms
+    pollInterval = 3000, onStatusChange) {
+        const startTime = Date.now();
+        let lastStatus = null;
+        const terminalStates = new Set(["DEPLOYED", "FAILED", "TERMINATED"]);
+        let buildStarted = false;
+        while (Date.now() - startTime < timeout) {
+            const status = await this._getSandboxStatus(name);
+            if (status && status !== lastStatus) {
+                lastStatus = status;
+                if (onStatusChange) {
+                    onStatusChange(status);
+                }
+            }
+            // Track if the build has started (status changed from DEPLOYED)
+            if (status && status !== "DEPLOYED") {
+                buildStarted = true;
+            }
+            // Only consider DEPLOYED as terminal if the build has started
+            // This handles re-builds where status starts as DEPLOYED
+            if (status && terminalStates.has(status)) {
+                if (status === "FAILED") {
+                    throw new Error(`Deployment failed for sandbox '${name}'`);
+                }
+                if (status === "TERMINATED") {
+                    throw new Error(`Sandbox '${name}' was terminated`);
+                }
+                if (status === "DEPLOYED" && buildStarted) {
+                    return status;
+                }
+            }
+            await sleep(pollInterval);
+        }
+        throw new Error(`Deployment timed out after ${timeout / 1000} seconds`);
+    }
+    /**
+     * Build and deploy the image as a sandbox.
+     *
+     * This method:
+     * 1. Prepares the image for sandbox deployment (adds sandbox-api)
+     * 2. Builds the image folder
+     * 3. Creates a zip of the folder
+     * 4. Creates/updates the sandbox resource
+     * 5. Uploads the zip to Blaxel
+     * 6. Waits for deployment to complete
+     *
+     * @param options - Build options
+     * @returns The deployed Sandbox object
+     */
+    async build(options) {
+        const { name, memory = 4096, timeout = 900000, onStatusChange, sandboxVersion = "latest" } = options;
+        // Prepare image for sandbox deployment (add sandbox-api and entrypoint)
+        const preparedImage = this._prepareForSandbox(sandboxVersion);
+        // Write the image folder
+        const buildDir = preparedImage.writeTemp();
+        try {
+            // Create zip
+            const zipContent = await this._createZip(buildDir);
+            // Create sandbox payload
+            const sandboxPayload = this._createSandboxPayload(name, memory);
+            // Create/update sandbox and get upload URL
+            const { response, uploadUrl } = await this._createSandboxWithUpload(sandboxPayload);
+            if (response.status >= 400) {
+                const text = await response.text();
+                throw new Error(`Failed to create sandbox: ${response.status} - ${text}`);
+            }
+            if (!uploadUrl) {
+                throw new Error("No upload URL returned from API");
+            }
+            // Upload the zip
+            await this._uploadZip(uploadUrl, zipContent);
+            // Wait for deployment to complete
+            await this._waitForDeployment(name, timeout, 3000, onStatusChange);
+            // Get the final sandbox state
+            await settings.authenticate();
+            const finalResponse = await fetch(`${settings.baseUrl}/sandboxes/${name}`, {
+                method: "GET",
+                headers: settings.headers,
+            });
+            if (finalResponse.status === 200) {
+                const sandbox = (await finalResponse.json());
+                return sandbox;
+            }
+            throw new Error(`Failed to get sandbox '${name}' after deployment`);
+        }
+        finally {
+            // Cleanup temp directory
+            const parentDir = path.resolve(buildDir, "..");
+            try {
+                fs.rmSync(parentDir, { recursive: true, force: true });
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+        }
+    }
+    /**
+     * Build and deploy the image as a sandbox (sync version).
+     *
+     * @deprecated Use build() instead - this is provided for API parity with Python SDK
+     */
+    buildSync(options) {
+        return this.build(options);
+    }
+}