@hatchet-dev/sandbox 0.1.1 → 0.1.2

package/dist/files.js

@@ -1,179 +0,0 @@
-"use strict";
-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 () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Files = exports.FilesystemError = void 0;
-const fs = __importStar(require("node:fs/promises"));
-/** Thrown for caller mistakes such as a missing file or a path outside the workspace. */
-class FilesystemError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-        this.name = 'FilesystemError';
-    }
-}
-exports.FilesystemError = FilesystemError;
-const toEntry = (e) => ({
-    ...e,
-    modifiedTime: e.modifiedTime ? new Date(e.modifiedTime) : undefined,
-});
-const STAGE_OVER_BYTES = 2 << 20;
-async function toBytes(data) {
-    if (typeof data === 'string')
-        return Buffer.from(data, 'utf8');
-    if (data instanceof Blob)
-        return Buffer.from(await data.arrayBuffer());
-    if (data instanceof Uint8Array)
-        return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
-    return Buffer.from(data);
-}
-async function putStaged(url, bytes) {
-    if (url.startsWith('file://')) {
-        await fs.writeFile(decodeURIComponent(url.slice('file://'.length)), bytes);
-        return;
-    }
-    const res = await fetch(url, { method: 'PUT', body: new Uint8Array(bytes), headers: { 'Content-Type': 'application/octet-stream' } });
-    if (!res.ok)
-        throw new FilesystemError('staging_failed', `stage upload failed: HTTP ${res.status}`);
-}
-async function getStaged(url) {
-    if (url.startsWith('file://')) {
-        return fs.readFile(decodeURIComponent(url.slice('file://'.length)));
-    }
-    const res = await fetch(url);
-    if (!res.ok)
-        throw new FilesystemError('staging_failed', `stage download failed: HTTP ${res.status}`);
-    return Buffer.from(await res.arrayBuffer());
-}
-/** File operations on a sandbox workspace. Paths are relative to the workspace. Each call is one Hatchet task. */
-class Files {
-    turn;
-    /** @internal */
-    constructor(turn) {
-        this.turn = turn;
-    }
-    async call(fn, input) {
-        const out = await this.turn(`$fs.${fn}`, input);
-        if (out.error)
-            throw new FilesystemError(out.error.code, out.error.message);
-        return out;
-    }
-    async read(path, opts = {}) {
-        const out = await this.call('read', { path });
-        const bytes = out.url ? await this.readStaged(out.url, out.stagedKey) : Buffer.from(out.content ?? '', 'base64');
-        if (opts.format === 'bytes')
-            return new Uint8Array(bytes);
-        if (opts.format === 'blob')
-            return new Blob([new Uint8Array(bytes)]);
-        return bytes.toString('utf8');
-    }
-    /** A replayed durable read may hold a URL that has expired; the provider signs the same staged file again. */
-    async readStaged(url, stagedKey) {
-        try {
-            return await getStaged(url);
-        }
-        catch (e) {
-            if (url.startsWith('file://') || !(e instanceof FilesystemError))
-                throw e;
-            const { getUrl } = await this.call('presign', { stagedKey });
-            return getStaged(getUrl);
-        }
-    }
-    async write(pathOrFiles, data) {
-        if (typeof pathOrFiles !== 'string')
-            return this.writeFiles(pathOrFiles);
-        const [entry] = await this.writeFiles([{ path: pathOrFiles, data: data ?? '' }]);
-        return entry;
-    }
-    /** Writes several files in one task. */
-    async writeFiles(files) {
-        const encoded = await Promise.all(files.map(async (f) => {
-            const bytes = await toBytes(f.data);
-            if (bytes.length <= STAGE_OVER_BYTES)
-                return { path: f.path, content: bytes.toString('base64') };
-            const { stagedKey, putUrl } = await this.call('presign', {});
-            await putStaged(putUrl, bytes);
-            return { path: f.path, stagedKey: stagedKey };
-        }));
-        const { entries = [] } = await this.call('write', { files: encoded });
-        return entries.map(toEntry);
-    }
-    /** Lists a directory. `depth` 1 (default) is the directory itself; higher values recurse. No snapshot is made. */
-    async list(path = '.', opts = {}) {
-        const { entries = [] } = await this.call('list', { path, depth: opts.depth ?? 1 });
-        return entries.map(toEntry);
-    }
-    /** True if the path exists. No snapshot is made. */
-    async exists(path) {
-        const { entry } = await this.call('stat', { path });
-        return entry != null;
-    }
-    /** Metadata of a file or directory. Throws `FilesystemError` with code `not_found` if absent. */
-    async getInfo(path) {
-        const { entry } = await this.call('stat', { path });
-        if (!entry)
-            throw new FilesystemError('not_found', `${path} does not exist`);
-        return toEntry(entry);
-    }
-    /** Creates a directory and its parents. Returns false if it already existed. */
-    async makeDir(path) {
-        const { created } = await this.call('mkdir', { path });
-        return created === true;
-    }
-    /** Renames or moves a file or directory. */
-    async rename(oldPath, newPath) {
-        const { entry } = await this.call('rename', { path: oldPath, newPath });
-        return toEntry(entry);
-    }
-    /** Copies a file or directory tree. */
-    async copy(srcPath, dstPath) {
-        const { entry } = await this.call('copy', { path: srcPath, newPath: dstPath });
-        return toEntry(entry);
-    }
-    /** Deletes a file or directory tree. */
-    async remove(path) {
-        await this.call('remove', { path });
-    }
-    /** The provider fetches an https URL into the workspace. The sandbox needs no network. Private and loopback addresses are refused. */
-    async download(url, path, opts = {}) {
-        const { entry } = await this.call('download', { url, path, ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}) });
-        return toEntry(entry);
-    }
-    /** The provider sends a workspace file to an https URL with HTTP PUT, for example a presigned URL. */
-    async upload(path, url, opts = {}) {
-        await this.call('upload', { path, url, ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}) });
-    }
-}
-exports.Files = Files;

package/dist/otel.d.ts

@@ -1 +0,0 @@
-export declare function setupTelemetry(): Promise<void>;

package/dist/otel.js

@@ -1,20 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.setupTelemetry = setupTelemetry;
-let telemetryStarted = false;
-async function setupTelemetry() {
-    if (telemetryStarted || process.env.BRICKIE_OTEL === 'false') {
-        return;
-    }
-    telemetryStarted = true;
-    try {
-        const [{ registerInstrumentations }, { HatchetInstrumentor }] = await Promise.all([
-            import('@opentelemetry/instrumentation'),
-            import('@hatchet-dev/typescript-sdk/opentelemetry/index.js'),
-        ]);
-        registerInstrumentations({ instrumentations: [new HatchetInstrumentor()] });
-    }
-    catch (err) {
-        console.error(`brickie: opentelemetry disabled: ${err.message}`);
-    }
-}

package/dist/sandbox.d.ts

@@ -1,91 +0,0 @@
-import { HatchetClient } from '@hatchet-dev/typescript-sdk/v1';
-import { Files } from './files.js';
-export interface Timings {
-    /** Snapshot made after this turn. Absent for turns that do not change the workspace. */
-    snapshotId?: string;
-    /** Milliseconds per phase: `claim`, `restore`, `exec`, `checkpoint`. */
-    timings?: Record<string, number>;
-}
-export interface CommandResult extends Timings {
-    stdout: string;
-    stderr: string;
-    /** A non-zero code is a normal result, not an error. */
-    exitCode: number;
-}
-export interface SandboxOpts {
-    /** Sandbox ID to use instead of a generated one. Lowercase letters, digits, and hyphens; must be new on the provider. */
-    id?: string;
-    /** Container image. Defaults to the provider's image. */
-    template?: string;
-    /** Snapshot to start from. Two sandboxes with the same `from` are a fork. */
-    from?: string;
-    /** Key-value tags, used to find the sandbox again with {@link SandboxNamespace.list}. */
-    metadata?: Record<string, string>;
-    /** Milliseconds without a turn before the provider removes the sandbox. Capped by the provider. */
-    idleTimeoutMs?: number;
-    /** With `from`, start from the metadata of the sandbox that made that snapshot. Pairs given in `metadata` take precedence over inherited ones. */
-    inheritParentMetadata?: boolean;
-}
-export interface ExecOpts {
-    /** Kill the command after this long. The result then has `exitCode` 124. */
-    timeoutMs?: number;
-}
-export interface ConnectOpts {
-    /** Image to use if the sandbox has to be started again. Defaults to the provider's image. */
-    template?: string;
-}
-export interface SandboxListOpts {
-    /** Only the sandbox with this ID. */
-    sandboxId?: string;
-    /** Only sandboxes whose metadata contains every one of these pairs. */
-    metadata?: Record<string, string>;
-}
-export interface SandboxInfo {
-    sandboxId: string;
-    metadata?: Record<string, string>;
-    /** True while the sandbox is running. A sandbox that is not live is started again by `connect`. */
-    live: boolean;
-    latestSnapshot?: string;
-    createdAt: Date;
-    lastUsed?: Date;
-}
-/** One sandbox. Every method is one `brickie-sandbox` Hatchet task. */
-export declare class Sandbox {
-    private readonly run;
-    readonly sandboxId: string;
-    private readonly template?;
-    /** File operations on the workspace. */
-    readonly files: Files;
-    private constructor();
-    /** Starts a new sandbox. Prefer `hatchet.sandbox.create`. */
-    static create(client: HatchetClient, opts?: SandboxOpts): Promise<Sandbox>;
-    /** Attaches to a sandbox by ID. Prefer `hatchet.sandbox.connect`. */
-    static connect(client: HatchetClient, sandboxId: string, opts?: ConnectOpts): Promise<Sandbox>;
-    /** Lists sandboxes on the provider. Prefer `hatchet.sandbox.list`. */
-    static list(client: HatchetClient, opts?: SandboxListOpts): Promise<SandboxInfo[]>;
-    /** Deletes every sandbox matching the filter, with all their snapshots and files. Prefer `hatchet.sandbox.delete`. */
-    static delete(client: HatchetClient, opts: SandboxListOpts): Promise<string[]>;
-    /** Runs a shell command with `sh -c` in the workspace and makes a snapshot. A timeout gives `exitCode` 124, not an error. */
-    exec(cmd: string, opts?: ExecOpts): Promise<CommandResult>;
-    /** Removes the sandbox. Its snapshots stay; `connect` can bring it back. */
-    kill(): Promise<void>;
-    /** Removes the sandbox and deletes every snapshot and file the provider stored for it. `connect` fails afterwards. */
-    delete(): Promise<void>;
-    private turn;
-}
-/** `hatchet.sandbox`, added to `HatchetClient` by importing `@hatchet-dev/sandbox`. */
-export interface SandboxNamespace {
-    /** Starts a new sandbox. Inside a durable task this is a durable step. */
-    create(opts?: SandboxOpts): Promise<Sandbox>;
-    /** Attaches to a sandbox by ID. If it is not running, the provider starts it from its latest snapshot. */
-    connect(sandboxId: string, opts?: ConnectOpts): Promise<Sandbox>;
-    /** Lists sandboxes the provider knows, filtered by ID or metadata. */
-    list(opts?: SandboxListOpts): Promise<SandboxInfo[]>;
-    /** Deletes the sandboxes matching the filter, with every snapshot and file stored for them. Returns their IDs. */
-    delete(opts: SandboxListOpts): Promise<string[]>;
-}
-declare module '@hatchet-dev/typescript-sdk/v1' {
-    interface HatchetClient {
-        readonly sandbox: SandboxNamespace;
-    }
-}

package/dist/sandbox.js

@@ -1,112 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Sandbox = void 0;
-const v1_1 = require("@hatchet-dev/typescript-sdk/v1");
-const files_js_1 = require("./files.js");
-const otel_js_1 = require("./otel.js");
-const SANDBOX_TASK_NAME = 'brickie-sandbox';
-function turnRunner(client) {
-    const task = client.workflow({ name: SANDBOX_TASK_NAME });
-    return async (input) => {
-        const result = await task.run(input, {
-            additionalMetadata: {
-                'brickie.fn': input.fn,
-                ...(input.sandboxId ? { 'brickie.sandbox': input.sandboxId } : {}),
-                ...(input.image ? { 'brickie.image': input.image } : {}),
-                ...(input.snapshotId ? { 'brickie.from': input.snapshotId } : {}),
-            },
-        });
-        return result[SANDBOX_TASK_NAME] ?? result;
-    };
-}
-/** One sandbox. Every method is one `brickie-sandbox` Hatchet task. */
-class Sandbox {
-    run;
-    sandboxId;
-    template;
-    /** File operations on the workspace. */
-    files;
-    constructor(run, sandboxId, template) {
-        this.run = run;
-        this.sandboxId = sandboxId;
-        this.template = template;
-        this.files = new files_js_1.Files((fn, input) => this.turn(fn, input));
-    }
-    /** Starts a new sandbox. Prefer `hatchet.sandbox.create`. */
-    static async create(client, opts = {}) {
-        void (0, otel_js_1.setupTelemetry)();
-        const run = turnRunner(client);
-        const created = await run({
-            fn: '$create',
-            input: {},
-            ...(opts.id ? { sandboxId: opts.id } : {}),
-            ...(opts.template ? { image: opts.template } : {}),
-            ...(opts.from ? { snapshotId: opts.from } : {}),
-            ...(opts.metadata ? { metadata: opts.metadata } : {}),
-            ...(opts.idleTimeoutMs ? { idleTtlMs: opts.idleTimeoutMs } : {}),
-            ...(opts.inheritParentMetadata ? { inheritMetadata: true } : {}),
-        });
-        return new Sandbox(run, created.sandboxId, opts.template);
-    }
-    /** Attaches to a sandbox by ID. Prefer `hatchet.sandbox.connect`. */
-    static async connect(client, sandboxId, opts = {}) {
-        void (0, otel_js_1.setupTelemetry)();
-        const run = turnRunner(client);
-        await run({ fn: '$connect', input: {}, sandboxId, ...(opts.template ? { image: opts.template } : {}) });
-        return new Sandbox(run, sandboxId, opts.template);
-    }
-    /** Lists sandboxes on the provider. Prefer `hatchet.sandbox.list`. */
-    static async list(client, opts = {}) {
-        const result = await turnRunner(client)({
-            fn: '$list',
-            input: { ...(opts.sandboxId ? { sandboxId: opts.sandboxId } : {}), ...(opts.metadata ? { metadata: opts.metadata } : {}) },
-        });
-        const raw = (result.output.sandboxes ?? []);
-        return raw.map((s) => ({ ...s, createdAt: new Date(s.createdAt), lastUsed: s.lastUsed ? new Date(s.lastUsed) : undefined }));
-    }
-    /** Deletes every sandbox matching the filter, with all their snapshots and files. Prefer `hatchet.sandbox.delete`. */
-    static async delete(client, opts) {
-        if (!opts.sandboxId && Object.keys(opts.metadata ?? {}).length === 0)
-            throw new Error('delete needs a sandboxId or a metadata filter');
-        const run = turnRunner(client);
-        const ids = [];
-        for (const { sandboxId } of await Sandbox.list(client, opts)) {
-            await run({ fn: '$delete', input: {}, sandboxId });
-            ids.push(sandboxId);
-        }
-        return ids;
-    }
-    /** Runs a shell command with `sh -c` in the workspace and makes a snapshot. A timeout gives `exitCode` 124, not an error. */
-    async exec(cmd, opts = {}) {
-        return this.turn('$command', { cmd, ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}) });
-    }
-    /** Removes the sandbox. Its snapshots stay; `connect` can bring it back. */
-    async kill() {
-        await this.turn('$destroy', {});
-    }
-    /** Removes the sandbox and deletes every snapshot and file the provider stored for it. `connect` fails afterwards. */
-    async delete() {
-        await this.turn('$delete', {});
-    }
-    async turn(fn, input) {
-        const result = await this.run({
-            sandboxId: this.sandboxId,
-            ...(this.template ? { image: this.template } : {}),
-            fn,
-            input,
-        });
-        return { ...result.output, snapshotId: result.snapshotId, timings: result.timings };
-    }
-}
-exports.Sandbox = Sandbox;
-Object.defineProperty(v1_1.HatchetClient.prototype, 'sandbox', {
-    configurable: true,
-    get() {
-        return {
-            create: (opts) => Sandbox.create(this, opts),
-            connect: (sandboxId, opts) => Sandbox.connect(this, sandboxId, opts),
-            list: (opts) => Sandbox.list(this, opts),
-            delete: (opts) => Sandbox.delete(this, opts),
-        };
-    },
-});