@schemavaults/sandbox-management-sdk 0.0.0-stage → 0.1.0

package/dist/errors.js

@@ -0,0 +1,67 @@
+export class SandboxError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+export class SandboxNotFoundError extends SandboxError {
+    sandboxId;
+    constructor(sandboxId) {
+        super(`Sandbox "${sandboxId}" not found`);
+        this.sandboxId = sandboxId;
+    }
+}
+export class ProviderNotFoundError extends SandboxError {
+    providerName;
+    constructor(providerName) {
+        super(`No sandbox provider registered under the name "${providerName}"`);
+        this.providerName = providerName;
+    }
+}
+/** The operation is not allowed while the sandbox is in its current status. */
+export class SandboxStateError extends SandboxError {
+    sandboxId;
+    status;
+    constructor(sandboxId, status, operation) {
+        super(`Cannot ${operation} sandbox "${sandboxId}" while it is ${status}`);
+        this.sandboxId = sandboxId;
+        this.status = status;
+    }
+}
+/** The sandbox stayed in a transitional status for longer than the manager waits. */
+export class SandboxBusyError extends SandboxError {
+    sandboxId;
+    status;
+    constructor(sandboxId, status) {
+        super(`Timed out waiting for sandbox "${sandboxId}" to leave status ${status}`);
+        this.sandboxId = sandboxId;
+        this.status = status;
+    }
+}
+/** A lifecycle command (git clone or a setup step) exited non-zero. */
+export class SandboxCommandError extends SandboxError {
+    step;
+    result;
+    constructor(step, result) {
+        const output = (result.stderr || result.stdout).trim().slice(-2000);
+        super(`${step} exited with code ${result.exitCode}${output ? `: ${output}` : ""}`);
+        this.step = step;
+        this.result = result;
+    }
+}
+/** Thrown by providers when an operation needs a running sandbox but it is stopped. */
+export class ProviderSandboxStoppedError extends SandboxError {
+    providerRef;
+    constructor(providerRef) {
+        super(`Provider sandbox "${providerRef}" is not running`);
+        this.providerRef = providerRef;
+    }
+}
+/** Thrown by providers when the sandbox no longer exists on the provider. */
+export class ProviderSandboxMissingError extends SandboxError {
+    providerRef;
+    constructor(providerRef) {
+        super(`Provider sandbox "${providerRef}" no longer exists`);
+        this.providerRef = providerRef;
+    }
+}

package/dist/in-memory-store.d.ts

@@ -0,0 +1,11 @@
+import type { SandboxListFilter, SandboxRecordPatch, SandboxStore } from "./store.js";
+import type { SandboxRecord } from "./types.js";
+/** A process-local store for tests and single-process development. */
+export declare class InMemorySandboxStore implements SandboxStore {
+    private readonly records;
+    insert(record: SandboxRecord): Promise<void>;
+    get(id: string): Promise<SandboxRecord | null>;
+    list(filter?: SandboxListFilter): Promise<SandboxRecord[]>;
+    update(id: string, expectedVersion: number, patch: SandboxRecordPatch): Promise<SandboxRecord | null>;
+    delete(id: string): Promise<boolean>;
+}

package/dist/in-memory-store.js

@@ -0,0 +1,40 @@
+import { matchesFilter } from "./store.js";
+/** A process-local store for tests and single-process development. */
+export class InMemorySandboxStore {
+    records = new Map();
+    async insert(record) {
+        if (this.records.has(record.id)) {
+            throw new Error(`Sandbox record "${record.id}" already exists`);
+        }
+        this.records.set(record.id, structuredClone(record));
+    }
+    async get(id) {
+        const record = this.records.get(id);
+        return record ? structuredClone(record) : null;
+    }
+    async list(filter = {}) {
+        const matches = [...this.records.values()]
+            .filter((record) => matchesFilter(record, filter))
+            .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+        const offset = filter.offset ?? 0;
+        const end = filter.limit === undefined ? undefined : offset + filter.limit;
+        return matches.slice(offset, end).map((record) => structuredClone(record));
+    }
+    async update(id, expectedVersion, patch) {
+        const current = this.records.get(id);
+        if (!current || current.version !== expectedVersion)
+            return null;
+        const defined = Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== undefined));
+        const next = {
+            ...current,
+            ...structuredClone(defined),
+            version: current.version + 1,
+            updatedAt: new Date(),
+        };
+        this.records.set(id, next);
+        return structuredClone(next);
+    }
+    async delete(id) {
+        return this.records.delete(id);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { SandboxManager, generateSandboxId } from "./manager.js";
+export type { CreateSandboxOptions, LogsOptions, SandboxManagerOptions } from "./manager.js";
+export { InMemorySandboxStore } from "./in-memory-store.js";
+export { matchesFilter } from "./store.js";
+export type { SandboxListFilter, SandboxRecordPatch, SandboxStore } from "./store.js";
+export type { MainLogChunk, ProviderCreateInput, ProviderCreateResult, ProviderSandbox, ProviderSandboxStatus, ResolvedSandboxFile, SandboxProvider, } from "./provider.js";
+export { ProviderNotFoundError, ProviderSandboxMissingError, ProviderSandboxStoppedError, SandboxBusyError, SandboxCommandError, SandboxError, SandboxNotFoundError, SandboxStateError, } from "./errors.js";
+export { gitCloneCommand, normalizeCommand, resolveSandboxPath, shellQuote, toShellCommandLine, validateSpec, } from "./commands.js";
+export { MAIN_PROCESS_DIR, mainProcessLauncher, shellGetMainProcess, shellReadMainLog, shellStartMainProcess, } from "./shell-main-process.js";
+export { assertNetworkPolicySupported, networkPolicyKind, normalizeCidr } from "./network.js";
+export { SANDBOX_STATUSES, TRANSITIONAL_STATUSES } from "./types.js";
+export type { ArgvCommand, CommandInput, ExecOptions, ExecResult, GitSource, MainProcessInfo, NormalizedCommand, SandboxFile, SandboxNetworkAllowlist, SandboxNetworkPolicy, SandboxNetworkPolicyKind, SandboxProviderOptions, SandboxRecord, SandboxResources, SandboxSpec, SandboxStatus, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { SandboxManager, generateSandboxId } from "./manager.js";
+export { InMemorySandboxStore } from "./in-memory-store.js";
+export { matchesFilter } from "./store.js";
+export { ProviderNotFoundError, ProviderSandboxMissingError, ProviderSandboxStoppedError, SandboxBusyError, SandboxCommandError, SandboxError, SandboxNotFoundError, SandboxStateError, } from "./errors.js";
+export { gitCloneCommand, normalizeCommand, resolveSandboxPath, shellQuote, toShellCommandLine, validateSpec, } from "./commands.js";
+export { MAIN_PROCESS_DIR, mainProcessLauncher, shellGetMainProcess, shellReadMainLog, shellStartMainProcess, } from "./shell-main-process.js";
+export { assertNetworkPolicySupported, networkPolicyKind, normalizeCidr } from "./network.js";
+export { SANDBOX_STATUSES, TRANSITIONAL_STATUSES } from "./types.js";

package/dist/internal/base64.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Base64 without `Buffer`, so the core also runs in browsers. `btoa` and
+ * `atob` are globals in Node.js, Bun and every browser.
+ */
+export declare function encodeBase64(bytes: Uint8Array): string;
+/** Whitespace in `text` is ignored. */
+export declare function decodeBase64(text: string): Uint8Array;

package/dist/internal/base64.js

@@ -0,0 +1,20 @@
+/**
+ * Base64 without `Buffer`, so the core also runs in browsers. `btoa` and
+ * `atob` are globals in Node.js, Bun and every browser.
+ */
+const CHUNK = 0x8000;
+export function encodeBase64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    return btoa(binary);
+}
+/** Whitespace in `text` is ignored. */
+export function decodeBase64(text) {
+    const binary = atob(text.replace(/\s+/g, ""));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}

package/dist/internal/output.d.ts

@@ -0,0 +1,6 @@
+import { Writable } from "node:stream";
+/** A Writable that decodes UTF-8 output, forwards each chunk and keeps the full text. */
+export declare function outputCollector(onChunk?: (chunk: string) => void): {
+    writable: Writable;
+    finish: () => string;
+};

package/dist/internal/output.js

@@ -0,0 +1,25 @@
+import { Writable } from "node:stream";
+/** A Writable that decodes UTF-8 output, forwards each chunk and keeps the full text. */
+export function outputCollector(onChunk) {
+    const decoder = new TextDecoder();
+    let text = "";
+    const push = (chunk) => {
+        if (!chunk)
+            return;
+        text += chunk;
+        onChunk?.(chunk);
+    };
+    const writable = new Writable({
+        write(chunk, _encoding, callback) {
+            push(typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true }));
+            callback();
+        },
+    });
+    return {
+        writable,
+        finish: () => {
+            push(decoder.decode());
+            return text;
+        },
+    };
+}

package/dist/internal/posix-path.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The POSIX path helpers the core needs, without `node:path`, so the core
+ * also runs in browsers. Same results as `posix.isAbsolute`,
+ * `posix.normalize` and `posix.join` from `node:path`.
+ */
+export declare function isAbsolute(path: string): boolean;
+export declare function normalize(path: string): string;
+export declare function join(...paths: string[]): string;

package/dist/internal/posix-path.js

@@ -0,0 +1,38 @@
+/**
+ * The POSIX path helpers the core needs, without `node:path`, so the core
+ * also runs in browsers. Same results as `posix.isAbsolute`,
+ * `posix.normalize` and `posix.join` from `node:path`.
+ */
+export function isAbsolute(path) {
+    return path.startsWith("/");
+}
+export function normalize(path) {
+    if (path === "")
+        return ".";
+    const absolute = isAbsolute(path);
+    const trailingSlash = path.endsWith("/");
+    const segments = [];
+    for (const segment of path.split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment !== "..") {
+            segments.push(segment);
+        }
+        else if (segments.length > 0 && segments.at(-1) !== "..") {
+            segments.pop();
+        }
+        else if (!absolute) {
+            segments.push("..");
+        }
+    }
+    let result = segments.join("/");
+    if (result === "")
+        return absolute ? "/" : trailingSlash ? "./" : ".";
+    if (trailingSlash)
+        result += "/";
+    return absolute ? `/${result}` : result;
+}
+export function join(...paths) {
+    const joined = paths.filter((path) => path !== "").join("/");
+    return joined === "" ? "." : normalize(joined);
+}

package/dist/manager.d.ts

@@ -0,0 +1,126 @@
+import type { SandboxProvider } from "./provider.js";
+import type { SandboxListFilter, SandboxStore } from "./store.js";
+import type { CommandInput, ExecOptions, ExecResult, MainProcessInfo, SandboxFile, SandboxRecord, SandboxSpec } from "./types.js";
+export interface SandboxManagerOptions {
+    providers: SandboxProvider[];
+    store: SandboxStore;
+    /** Provider used by `create` when none is given. Defaults to the only provider, if there is one. */
+    defaultProvider?: string;
+    /** Resume stopped sandboxes automatically when they are accessed. Default `true`. */
+    autoResume?: boolean;
+    /** How long to wait for another caller's in-flight transition. Default 10 minutes. */
+    transitionTimeoutMs?: number;
+    /** Poll interval while waiting for a transition. Default 250ms. */
+    pollIntervalMs?: number;
+    /** ID generator for new sandboxes. */
+    generateId?: () => string;
+    /** Clock, for tests. */
+    now?: () => Date;
+}
+export interface CreateSandboxOptions extends Pick<ExecOptions, "onStdout" | "onStderr"> {
+    spec: SandboxSpec;
+    /** Provider name. Defaults to `defaultProvider`. */
+    provider?: string;
+    ownerId?: string | null;
+    labels?: Record<string, string>;
+    metadata?: Record<string, unknown>;
+}
+export interface LogsOptions {
+    /** Keep polling for new output until `signal` aborts. Default `false`. */
+    follow?: boolean;
+    signal?: AbortSignal;
+    /** Poll interval when following. Default 1000ms. */
+    pollIntervalMs?: number;
+}
+export declare function generateSandboxId(): string;
+/**
+ * Creates, lists and drives sandboxes across providers, keeping their state in
+ * a `SandboxStore`. Safe to use from many processes at once: every status
+ * change is a compare-and-set on the record's version.
+ */
+export declare class SandboxManager {
+    private readonly providers;
+    private readonly store;
+    private readonly defaultProvider;
+    private readonly autoResume;
+    private readonly transitionTimeoutMs;
+    private readonly pollIntervalMs;
+    private readonly generateId;
+    private readonly now;
+    constructor(options: SandboxManagerOptions);
+    /**
+     * Create a sandbox, clone `spec.git`, run `spec.setup` and launch
+     * `spec.start`. Resolves once the sandbox is running. On failure the record
+     * is marked `failed` and the provider sandbox is kept for inspection; call
+     * `destroy` to remove it.
+     */
+    create(options: CreateSandboxOptions): Promise<SandboxRecord>;
+    /** Resolves the record, or throws `SandboxNotFoundError`. */
+    get(id: string): Promise<SandboxRecord>;
+    /** Resolves the record, or `null` if it does not exist. */
+    find(id: string): Promise<SandboxRecord | null>;
+    list(filter?: SandboxListFilter): Promise<SandboxRecord[]>;
+    /** Run a one-shot command and wait for it to finish. A non-zero exit does not throw. */
+    exec(id: string, command: CommandInput, options?: ExecOptions): Promise<ExecResult>;
+    /**
+     * Wake a stopped sandbox and relaunch `spec.resume` (or `spec.start`) as its
+     * main process. Also retries a `failed` sandbox that still has a provider
+     * sandbox; `setup` is not re-run. No-op if it is already running.
+     */
+    resume(id: string): Promise<SandboxRecord>;
+    /** Stop a running sandbox, keeping its filesystem. No-op if it is already stopped. */
+    stop(id: string): Promise<SandboxRecord>;
+    /** Delete the provider sandbox. The record is kept with status `destroyed`. */
+    destroy(id: string): Promise<SandboxRecord>;
+    /** A URL that reaches `port` (which must be listed in `spec.ports`). */
+    getUrl(id: string, port: number): Promise<string>;
+    writeFiles(id: string, files: SandboxFile[]): Promise<void>;
+    /** Resolves the file's bytes, or `null` if it does not exist. */
+    readFile(id: string, path: string): Promise<Uint8Array | null>;
+    readTextFile(id: string, path: string): Promise<string | null>;
+    /** State of the detached main process, or `null` if none was launched. */
+    getMainProcess(id: string): Promise<MainProcessInfo | null>;
+    /** The main process's full log so far. */
+    readLogs(id: string): Promise<string>;
+    /**
+     * Stream the main process's log, from the beginning. Only the first read
+     * auto-resumes a stopped sandbox; when following, the stream ends once the
+     * sandbox stops or `signal` aborts.
+     */
+    logs(id: string, options?: LogsOptions): AsyncGenerator<string, void, void>;
+    /** Reads the log without resuming; `null` once the sandbox is no longer running. */
+    private readMainLogIfRunning;
+    /** Push back the sandbox's expiry (and the provider's own timeout, if it has one). */
+    extendTimeout(id: string, durationMs: number): Promise<SandboxRecord>;
+    /**
+     * Stop every running sandbox whose `expiresAt` has passed. Run this
+     * periodically (e.g. from a cron job) for providers without native
+     * timeouts, such as Docker.
+     */
+    stopExpired(): Promise<SandboxRecord[]>;
+    /**
+     * Bring records in line with what the providers report: running sandboxes
+     * the provider has stopped become `stopped`, vanished ones become `failed`,
+     * and transitions abandoned for longer than the transition timeout (e.g. a
+     * crashed process) are settled. Defaults to every non-destroyed sandbox;
+     * sandboxes on unregistered providers, or whose provider errors, are
+     * skipped. Resolves the records that changed.
+     */
+    reconcile(ids?: string[]): Promise<SandboxRecord[]>;
+    private reconcilePatch;
+    /** Runs `fn` against a running sandbox, auto-resuming it if it is (or turns out to be) stopped. */
+    private withRunning;
+    private ensureRunning;
+    /** Claims the record for resuming. Resolves `null` if another caller claimed it first. */
+    private tryResume;
+    /** Waits until the record is not in a transitional status. */
+    private settle;
+    private runStep;
+    /** Update that must succeed because this caller holds the record's transitional status. */
+    private mustUpdate;
+    private markFailed;
+    private getProvider;
+    private workdirFor;
+    private toProviderSandbox;
+    private expiryFor;
+}