@hatchet-dev/sandbox 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -0,0 +1,188 @@
+import { JsonObject, HatchetClient } from '@hatchet-dev/typescript-sdk/v1';
+
+type FileType = 'file' | 'dir';
+interface EntryInfo {
+    name: string;
+    path: string;
+    type: FileType;
+    size: number;
+    mode: number;
+    permissions: string;
+    modifiedTime?: Date;
+}
+type FileData = string | ArrayBuffer | Uint8Array | Blob;
+interface WriteEntry {
+    path: string;
+    data: FileData;
+}
+interface ReadOpts {
+    format?: 'text' | 'bytes' | 'blob';
+}
+interface TransferOpts {
+    /** Give up after this long. */
+    timeoutMs?: number;
+}
+interface ListOpts {
+    depth?: number;
+}
+type FilesystemErrorCode = 'staging_failed' | 'not_found' | 'invalid_path' | 'invalid_url' | 'invalid_content' | 'invalid' | 'is_a_directory' | 'not_a_directory' | 'too_large' | 'transfer_failed';
+/** Thrown for caller mistakes such as a missing file or a path outside the workspace. */
+declare class FilesystemError extends Error {
+    readonly code: FilesystemErrorCode;
+    constructor(code: FilesystemErrorCode, message: string);
+}
+type RawEntry = Omit<EntryInfo, 'modifiedTime'> & {
+    modifiedTime?: string;
+};
+interface FsOutput extends JsonObject {
+    content?: string;
+    stagedKey?: string;
+    url?: string;
+    putUrl?: string;
+    getUrl?: string;
+    entry?: RawEntry | null;
+    entries?: RawEntry[];
+    created?: boolean;
+    error?: {
+        code: FilesystemErrorCode;
+        message: string;
+    };
+}
+/** @internal */
+type FsTurn = (fn: string, input: JsonObject, fresh?: boolean) => Promise<FsOutput>;
+/** File operations on a sandbox workspace. Paths are relative to the workspace. Each call is one Hatchet task. */
+declare class Files {
+    private readonly turn;
+    /** @internal */
+    constructor(turn: FsTurn);
+    private call;
+    /** Reads a file as text (default), bytes, or a Blob. Files over the provider's `--max-file-bytes` (2 MiB) come through the provider's `--store` instead of Hatchet. */
+    read(path: string, opts?: ReadOpts & {
+        format?: 'text';
+    }): Promise<string>;
+    read(path: string, opts: ReadOpts & {
+        format: 'bytes';
+    }): Promise<Uint8Array>;
+    read(path: string, opts: ReadOpts & {
+        format: 'blob';
+    }): Promise<Blob>;
+    /** A replayed durable read may hold a URL that has expired; the provider signs the same staged file again. The renewal is a plain run, not a durable child, so the replayed child sequence stays aligned. */
+    private readStaged;
+    /** Writes one file or several. Parent directories are created. Bytes are stored exactly. Files over 2 MiB go through the provider's `--store` instead of Hatchet. */
+    write(path: string, data: FileData): Promise<EntryInfo>;
+    write(files: WriteEntry[]): Promise<EntryInfo[]>;
+    /** Writes several files in one task. */
+    writeFiles(files: WriteEntry[]): Promise<EntryInfo[]>;
+    /** Lists a directory. `depth` 1 (default) is the directory itself; higher values recurse. No snapshot is made. */
+    list(path?: string, opts?: ListOpts): Promise<EntryInfo[]>;
+    /** True if the path exists. No snapshot is made. */
+    exists(path: string): Promise<boolean>;
+    /** Metadata of a file or directory. Throws `FilesystemError` with code `not_found` if absent. */
+    getInfo(path: string): Promise<EntryInfo>;
+    /** Creates a directory and its parents. Returns false if it already existed. */
+    makeDir(path: string): Promise<boolean>;
+    /** Renames or moves a file or directory. */
+    rename(oldPath: string, newPath: string): Promise<EntryInfo>;
+    /** Copies a file or directory tree. */
+    copy(srcPath: string, dstPath: string): Promise<EntryInfo>;
+    /** Deletes a file or directory tree. */
+    remove(path: string): Promise<void>;
+    /** The provider fetches an https URL into the workspace. The sandbox needs no network. Private and loopback addresses are refused. */
+    download(url: string, path: string, opts?: TransferOpts): Promise<EntryInfo>;
+    /** The provider sends a workspace file to an https URL with HTTP PUT, for example a presigned URL. */
+    upload(path: string, url: string, opts?: TransferOpts): Promise<void>;
+}
+
+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>;
+}
+interface CommandResult extends Timings {
+    stdout: string;
+    stderr: string;
+    /** A non-zero code is a normal result, not an error. */
+    exitCode: number;
+}
+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;
+    /** Name of the sandbox provider to create on. Required when the tenant has more than one; with `from`, it must be the provider that holds the snapshot. */
+    provider?: string;
+}
+interface ExecOpts {
+    /** Kill the command after this long. The result then has `exitCode` 124. */
+    timeoutMs?: number;
+}
+interface ConnectOpts {
+    /** Image to use if the sandbox has to be started again. Defaults to the provider's image. */
+    template?: string;
+}
+interface SandboxListOpts {
+    /** Only the sandbox with this ID. */
+    sandboxId?: string;
+    /** Only sandboxes whose metadata contains every one of these pairs. */
+    metadata?: Record<string, string>;
+}
+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 Hatchet task on the tenant's sandbox provider. */
+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`. */
+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;
+    }
+}
+
+export { type CommandResult, type ConnectOpts, type EntryInfo, type ExecOpts, type FileData, type FileType, Files, FilesystemError, type FilesystemErrorCode, type ListOpts, type ReadOpts, Sandbox, type SandboxInfo, type SandboxListOpts, type SandboxNamespace, type SandboxOpts, type Timings, type TransferOpts, type WriteEntry };

package/dist/index.d.ts

@@ -1,2 +1,188 @@
-export { Sandbox, type SandboxNamespace, type SandboxOpts, type ConnectOpts, type ExecOpts, type SandboxListOpts, type SandboxInfo, type CommandResult, type Timings, } from './sandbox.js';
-export { Files, FilesystemError, type FilesystemErrorCode, type EntryInfo, type FileType, type FileData, type WriteEntry, type ReadOpts, type ListOpts, type TransferOpts, } from './files.js';
+import { JsonObject, HatchetClient } from '@hatchet-dev/typescript-sdk/v1';
+
+type FileType = 'file' | 'dir';
+interface EntryInfo {
+    name: string;
+    path: string;
+    type: FileType;
+    size: number;
+    mode: number;
+    permissions: string;
+    modifiedTime?: Date;
+}
+type FileData = string | ArrayBuffer | Uint8Array | Blob;
+interface WriteEntry {
+    path: string;
+    data: FileData;
+}
+interface ReadOpts {
+    format?: 'text' | 'bytes' | 'blob';
+}
+interface TransferOpts {
+    /** Give up after this long. */
+    timeoutMs?: number;
+}
+interface ListOpts {
+    depth?: number;
+}
+type FilesystemErrorCode = 'staging_failed' | 'not_found' | 'invalid_path' | 'invalid_url' | 'invalid_content' | 'invalid' | 'is_a_directory' | 'not_a_directory' | 'too_large' | 'transfer_failed';
+/** Thrown for caller mistakes such as a missing file or a path outside the workspace. */
+declare class FilesystemError extends Error {
+    readonly code: FilesystemErrorCode;
+    constructor(code: FilesystemErrorCode, message: string);
+}
+type RawEntry = Omit<EntryInfo, 'modifiedTime'> & {
+    modifiedTime?: string;
+};
+interface FsOutput extends JsonObject {
+    content?: string;
+    stagedKey?: string;
+    url?: string;
+    putUrl?: string;
+    getUrl?: string;
+    entry?: RawEntry | null;
+    entries?: RawEntry[];
+    created?: boolean;
+    error?: {
+        code: FilesystemErrorCode;
+        message: string;
+    };
+}
+/** @internal */
+type FsTurn = (fn: string, input: JsonObject, fresh?: boolean) => Promise<FsOutput>;
+/** File operations on a sandbox workspace. Paths are relative to the workspace. Each call is one Hatchet task. */
+declare class Files {
+    private readonly turn;
+    /** @internal */
+    constructor(turn: FsTurn);
+    private call;
+    /** Reads a file as text (default), bytes, or a Blob. Files over the provider's `--max-file-bytes` (2 MiB) come through the provider's `--store` instead of Hatchet. */
+    read(path: string, opts?: ReadOpts & {
+        format?: 'text';
+    }): Promise<string>;
+    read(path: string, opts: ReadOpts & {
+        format: 'bytes';
+    }): Promise<Uint8Array>;
+    read(path: string, opts: ReadOpts & {
+        format: 'blob';
+    }): Promise<Blob>;
+    /** A replayed durable read may hold a URL that has expired; the provider signs the same staged file again. The renewal is a plain run, not a durable child, so the replayed child sequence stays aligned. */
+    private readStaged;
+    /** Writes one file or several. Parent directories are created. Bytes are stored exactly. Files over 2 MiB go through the provider's `--store` instead of Hatchet. */
+    write(path: string, data: FileData): Promise<EntryInfo>;
+    write(files: WriteEntry[]): Promise<EntryInfo[]>;
+    /** Writes several files in one task. */
+    writeFiles(files: WriteEntry[]): Promise<EntryInfo[]>;
+    /** Lists a directory. `depth` 1 (default) is the directory itself; higher values recurse. No snapshot is made. */
+    list(path?: string, opts?: ListOpts): Promise<EntryInfo[]>;
+    /** True if the path exists. No snapshot is made. */
+    exists(path: string): Promise<boolean>;
+    /** Metadata of a file or directory. Throws `FilesystemError` with code `not_found` if absent. */
+    getInfo(path: string): Promise<EntryInfo>;
+    /** Creates a directory and its parents. Returns false if it already existed. */
+    makeDir(path: string): Promise<boolean>;
+    /** Renames or moves a file or directory. */
+    rename(oldPath: string, newPath: string): Promise<EntryInfo>;
+    /** Copies a file or directory tree. */
+    copy(srcPath: string, dstPath: string): Promise<EntryInfo>;
+    /** Deletes a file or directory tree. */
+    remove(path: string): Promise<void>;
+    /** The provider fetches an https URL into the workspace. The sandbox needs no network. Private and loopback addresses are refused. */
+    download(url: string, path: string, opts?: TransferOpts): Promise<EntryInfo>;
+    /** The provider sends a workspace file to an https URL with HTTP PUT, for example a presigned URL. */
+    upload(path: string, url: string, opts?: TransferOpts): Promise<void>;
+}
+
+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>;
+}
+interface CommandResult extends Timings {
+    stdout: string;
+    stderr: string;
+    /** A non-zero code is a normal result, not an error. */
+    exitCode: number;
+}
+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;
+    /** Name of the sandbox provider to create on. Required when the tenant has more than one; with `from`, it must be the provider that holds the snapshot. */
+    provider?: string;
+}
+interface ExecOpts {
+    /** Kill the command after this long. The result then has `exitCode` 124. */
+    timeoutMs?: number;
+}
+interface ConnectOpts {
+    /** Image to use if the sandbox has to be started again. Defaults to the provider's image. */
+    template?: string;
+}
+interface SandboxListOpts {
+    /** Only the sandbox with this ID. */
+    sandboxId?: string;
+    /** Only sandboxes whose metadata contains every one of these pairs. */
+    metadata?: Record<string, string>;
+}
+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 Hatchet task on the tenant's sandbox provider. */
+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`. */
+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;
+    }
+}
+
+export { type CommandResult, type ConnectOpts, type EntryInfo, type ExecOpts, type FileData, type FileType, Files, FilesystemError, type FilesystemErrorCode, type ListOpts, type ReadOpts, Sandbox, type SandboxInfo, type SandboxListOpts, type SandboxNamespace, type SandboxOpts, type Timings, type TransferOpts, type WriteEntry };