@pablofdezr/microvm 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Wire types for the microvm API.
+ *
+ * These mirror the server's public types exactly. They are hand-written rather
+ * than generated so the names read naturally in TypeScript, and so a field
+ * added server-side is a deliberate change here rather than a silent one.
+ */
+/** How a sandbox or exec ended. */
+export type SandboxState = "running" | "stopped";
+/**
+ * Why a sandbox stopped.
+ *
+ * The distinctions are the point: `expired` and `idle` are our doing, `failed`
+ * means the VM died on its own, and `stopped` means you asked.
+ */
+export type StopReason = "stopped" | "expired" | "idle" | "failed";
+/**
+ * How an exec ended.
+ *
+ * `exited` is your code's own verdict. `vanished` means we took the VM away
+ * mid-run — a TTL, an OOM — and is not your code failing. `failed` means the
+ * command could never start at all, usually a missing binary.
+ */
+export type ExecStatus = "running" | "exited" | "timed_out" | "aborted" | "vanished" | "failed";
+/** Where a queued task is in its life. */
+export type TaskStatus = "pending" | "leased" | "done" | "failed";
+/** What a sandbox has consumed. */
+export interface Stats {
+    /**
+     * CPU actually burned, in milliseconds. This is the billable number: a
+     * sandbox blocked on the network contributes nothing to it.
+     */
+    active_cpu_ms: number;
+    /** How long the sandbox has existed. */
+    wall_ms: number;
+    /** Wall minus active CPU: existing but doing nothing. */
+    idle_ms: number;
+    memory_current_bytes: number;
+    memory_peak_bytes: number;
+}
+/** A sandbox's state. */
+export interface SandboxInfo {
+    id: string;
+    image: string;
+    state: SandboxState;
+    reason?: StopReason;
+    created_at: string;
+    expires_at: string;
+    stopped_at?: string;
+    stats: Stats;
+}
+/** Options for creating a sandbox. */
+export interface SandboxOptions {
+    vcpus?: number;
+    memMiB?: number;
+    /** May be fractional, e.g. 0.5. */
+    cpuCores?: number;
+    diskMiB?: number;
+    /**
+     * Enable filtered egress: the public internet is reachable, every private
+     * range is not. Package installs work; reaching the host's LAN does not.
+     */
+    network?: boolean;
+    /** Maximum lifetime in milliseconds. The sandbox is killed when it elapses. */
+    ttlMs?: number;
+    /**
+     * Reclaim the sandbox after this long with nothing running. Negative disables
+     * it, which only makes sense if you will definitely destroy it yourself.
+     */
+    idleTimeoutMs?: number;
+}
+/** Options for running a command. */
+export interface ExecOptions {
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    /** Written to the process, then closed. */
+    stdin?: Uint8Array | string;
+    /** Kills the process group when exceeded. */
+    timeoutMs?: number;
+    /** Makes the exec addressable before it finishes. Generated when absent. */
+    id?: string;
+    /** Aborts the process inside the guest when triggered. */
+    signal?: AbortSignal;
+}
+/** A finished command. */
+export interface ExecResult {
+    id: string;
+    status: ExecStatus;
+    exit_code?: number;
+    signal?: string;
+    /** Why the command could never start. */
+    error?: string;
+    stdout: string;
+    stderr: string;
+    /** Output exceeded the retention cap and the oldest bytes were dropped. */
+    stdout_truncated?: boolean;
+    stderr_truncated?: boolean;
+    started_at: string;
+    finished_at?: string;
+    duration_ms: number;
+}
+/** One event in a streamed exec. */
+export interface Frame {
+    type: "started" | "stdout" | "stderr" | "exit" | "error";
+    /** Base64 on the wire; decoded to bytes by the client. */
+    data?: Uint8Array;
+    pid?: number;
+    exit_code?: number;
+    signal?: string;
+    timed_out?: boolean;
+    message?: string;
+}
+/** Options for queueing a task. */
+export interface TaskOptions {
+    /** Written into the sandbox before the command runs, keyed by path. */
+    files?: Record<string, Uint8Array | string>;
+    args?: string[];
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    network?: boolean;
+    vcpus?: number;
+    memMiB?: number;
+    cpuCores?: number;
+    /** Higher runs first. Equal priorities are strictly FIFO. */
+    priority?: number;
+    /**
+     * Bounds retries. Retries exist for nodes dying, not for code failing: a task
+     * whose process exits non-zero is finished, never retried.
+     */
+    maxAttempts?: number;
+    /** Makes submission idempotent: the same ID twice is rejected, not re-run. */
+    id?: string;
+}
+/** A queued task. */
+export interface Task {
+    id: string;
+    status: TaskStatus;
+}
+/** A finished task's outcome. */
+export interface TaskResult {
+    task_id: string;
+    status: TaskStatus;
+    exit_code?: number;
+    stdout: string;
+    stderr: string;
+    /**
+     * An infrastructure failure — no sandbox, the VM died. Distinct from a
+     * non-zero exit, which is your code's own verdict.
+     */
+    error?: string;
+    attempts: number;
+    started_at?: string;
+    finished_at?: string;
+    active_cpu_ms: number;
+    memory_peak_bytes: number;
+}
+/** The queue's depth and a node's slots. */
+export interface QueueStats {
+    pending: number;
+    leased: number;
+    done: number;
+    failed: number;
+    /**
+     * How long the head of the queue has waited. The number that says whether the
+     * fleet is big enough: rising means work arrives faster than it finishes.
+     */
+    oldest_pending_ms: number;
+    /** This node's slots, not the fleet's. */
+    slots: number;
+    busy: number;
+}
+/** The daemon's status. */
+export interface Health {
+    ok: boolean;
+    version: string;
+    images: string[];
+}