withruntime 0.7.1 → 0.8.0

package/dist/blaxel/snapshot.d.ts

@@ -0,0 +1,119 @@
+import type { Runtime } from "../client.js";
+import type { Snapshot as RuntimeSnapshot } from "../snapshots.js";
+import { type RuntimeOptions, type RuntimeSandbox } from "./client.js";
+import { type PaginatedList } from "./pagination.js";
+export type SandboxSnapshotSource = {
+    readonly deleted?: boolean;
+    kind?: "sandbox";
+    name: string;
+};
+export type SandboxSnapshotSpec = {
+    image?: string;
+    memory?: number;
+    region?: string;
+};
+export type SandboxSnapshot = {
+    createdAt: string;
+    createdBy?: string;
+    readonly id: string;
+    name: string;
+    sandboxName?: string;
+    source?: SandboxSnapshotSource;
+    spec?: SandboxSnapshotSpec;
+    status: string;
+    workspace: string;
+};
+export type SandboxForkResponse = {
+    name?: string;
+    snapshotId?: string;
+    type?: "sandbox" | "application";
+};
+export type SandboxRestoreResponse = {
+    name: string;
+    snapshotId: string;
+};
+export type Env = {
+    name?: string;
+    secret?: boolean;
+    value?: string;
+};
+export type SnapshotCreateConfiguration = {
+    name?: string;
+    source: {
+        name: string;
+        kind?: "sandbox";
+    };
+};
+export type SnapshotForkOptions = {
+    targetType?: "sandbox" | "application";
+    port?: number;
+    traffic?: number;
+    customDomain?: string;
+    prefix?: string;
+    envs?: Env[];
+};
+export type SnapshotListQuery = {
+    cursor?: string;
+    limit?: number;
+    sort?: string;
+    q?: string;
+    anchor?: "end";
+};
+/** Paused sandboxes are kept this long when no TTL says otherwise. */
+export declare const KEEP_DAYS = 365;
+export declare function snapshotModel(snapshot: RuntimeSnapshot, sandboxName?: string): SandboxSnapshot;
+/** Envs as a record; a nameless one is refused. */
+export declare function envRecord(envs: Env[] | undefined): Record<string, string>;
+/** Appends envs to a sandbox's env file: they win over the ones it has. */
+export declare function appendEnvs(runtime: RuntimeSandbox, envs: Record<string, string>): Promise<void>;
+/** A new sandbox named `name`, started from a snapshot, behaving as a Blaxel
+ * sandbox. */
+export declare function startFromSnapshot(client: Runtime, snapshotId: string, name: string, labels: Record<string, string>, envs: Record<string, string>): Promise<RuntimeSandbox>;
+declare function refuseApplication(options?: {
+    targetType?: string;
+}): void;
+/** A snapshot, as Blaxel's Snapshot class. */
+export declare class Snapshot {
+    #private;
+    constructor(snapshot: SandboxSnapshot, client: Runtime);
+    get name(): string;
+    get id(): string;
+    get status(): string;
+    get workspace(): string;
+    get createdAt(): string;
+    get source(): SandboxSnapshotSource | undefined;
+    get spec(): SandboxSnapshotSpec | undefined;
+    /** Takes a snapshot of the sandbox named in `source`. */
+    static create(config: SnapshotCreateConfiguration, options?: RuntimeOptions): Promise<Snapshot>;
+    /** A snapshot by its id. */
+    static get(snapshotId: string, options?: RuntimeOptions): Promise<Snapshot>;
+    /** The account's snapshots, a page at a time; `for await` walks them all. */
+    static list(query?: SnapshotListQuery, options?: RuntimeOptions): Promise<PaginatedList<Snapshot>>;
+    static delete(snapshotId: string, options?: RuntimeOptions): Promise<void>;
+    delete(): Promise<void>;
+    /** A new sandbox named `targetName`, started from this snapshot. */
+    fork(targetName: string, options?: SnapshotForkOptions): Promise<SandboxForkResponse>;
+}
+/** What `sandbox.snapshots` needs from its sandbox. */
+export interface SnapshotContext {
+    readonly sandboxName: string;
+    readonly sandboxId: string;
+    readonly client: Runtime;
+    run<T>(work: (runtime: RuntimeSandbox) => Promise<T>): Promise<T>;
+    labels(): Record<string, string>;
+}
+/** `sandbox.snapshots`: this sandbox's snapshots, by name. */
+export declare class SandboxSnapshotsResource {
+    #private;
+    constructor(ctx: SnapshotContext);
+    get sandboxName(): string;
+    create(name?: string): Promise<Snapshot>;
+    list(): Promise<Snapshot[]>;
+    /** This sandbox's newest snapshot with that name, or with that id. */
+    get(snapshotName: string): Promise<Snapshot>;
+    /** The id of a snapshot named, or given by id, for a fork. */
+    idOf(nameOrId: string): Promise<string>;
+    delete(snapshotName: string): Promise<void>;
+    restore(_snapshotName: string): Promise<never>;
+}
+export { refuseApplication };

package/dist/blaxel/snapshot.js

@@ -0,0 +1,197 @@
+import { clientFor, } from "./client.js";
+import { envFileCommand, envFileLines } from "./context.js";
+import { guard, isNotFound, NotSupportedError, responseError } from "./errors.js";
+import { findSandbox, LEASE_SECONDS, STANDBY, userLabels, whenNameFree } from "./lookup.js";
+import { paginate } from "./pagination.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** A Blaxel snapshot is kept until deleted: Runtime's longest. */
+const SNAPSHOT_DAYS = 365;
+/** Paused sandboxes are kept this long when no TTL says otherwise. */
+export const KEEP_DAYS = 365;
+export function snapshotModel(snapshot, sandboxName) {
+    return {
+        id: snapshot.id,
+        name: snapshot.name ?? snapshot.id,
+        createdAt: snapshot.createdAt,
+        status: snapshot.state.toUpperCase(),
+        workspace: "",
+        ...(sandboxName ? { sandboxName } : {}),
+        source: { kind: "sandbox", name: sandboxName ?? snapshot.sourceSandboxId },
+        spec: { memory: snapshot.shape?.memoryMiB, region: "us-was-1" },
+    };
+}
+/** Envs as a record; a nameless one is refused. */
+export function envRecord(envs) {
+    const out = {};
+    for (const env of envs ?? []) {
+        if (!env.name)
+            throw responseError(400, "every env needs a name");
+        out[env.name] = env.value ?? "";
+    }
+    return out;
+}
+/** Appends envs to a sandbox's env file: they win over the ones it has. */
+export async function appendEnvs(runtime, envs) {
+    if (!Object.keys(envs).length)
+        return;
+    const result = await guard(() => runtime.exec(envFileCommand(true), { stdin: envFileLines(envs) }));
+    if (result.exitCode !== 0)
+        throw responseError(500, `Setting the sandbox's envs failed: ${result.stderr.trim()}`);
+}
+/** A new sandbox named `name`, started from a snapshot, behaving as a Blaxel
+ * sandbox. */
+export async function startFromSnapshot(client, snapshotId, name, labels, envs) {
+    const input = {
+        snapshot: snapshotId,
+        name,
+        labels,
+        ...STANDBY,
+        timeoutSeconds: LEASE_SECONDS,
+        onLeaseEnd: "pause",
+    };
+    const runtime = await guard(() => whenNameFree(client, () => client.sandboxes.create(input)));
+    try {
+        await Promise.all([
+            appendEnvs(runtime, envs),
+            runtime.info.funding === "paid" ? guard(() => runtime.setRetention(KEEP_DAYS)) : undefined,
+        ]);
+    }
+    catch (error) {
+        await runtime.stop({ wait: false }).catch(() => undefined);
+        throw error;
+    }
+    return runtime;
+}
+function refuseApplication(options = {}) {
+    if (options.targetType === "application")
+        throw new NotSupportedError("Forking into an application", "Fork into a sandbox and share its port with sandbox.previews.create.");
+}
+/** A snapshot, as Blaxel's Snapshot class. */
+export class Snapshot {
+    #snapshot;
+    #client;
+    constructor(snapshot, client) {
+        this.#snapshot = snapshot;
+        this.#client = client;
+    }
+    get name() {
+        return this.#snapshot.name;
+    }
+    get id() {
+        return this.#snapshot.id;
+    }
+    get status() {
+        return this.#snapshot.status;
+    }
+    get workspace() {
+        return this.#snapshot.workspace;
+    }
+    get createdAt() {
+        return this.#snapshot.createdAt;
+    }
+    get source() {
+        return this.#snapshot.source;
+    }
+    get spec() {
+        return this.#snapshot.spec;
+    }
+    /** Takes a snapshot of the sandbox named in `source`. */
+    static async create(config, options = {}) {
+        if (config.source.kind !== undefined && config.source.kind !== "sandbox")
+            throw new NotSupportedError(`A snapshot of a ${String(config.source.kind)}`, "Snapshot a sandbox.");
+        const client = clientFor(options);
+        const runtime = await guard(() => findSandbox(client, config.source.name));
+        const taken = await guard(() => runtime.snapshot({
+            ...(config.name ? { name: config.name } : {}),
+            labels: userLabels(runtime.info.labels),
+            retentionDays: SNAPSHOT_DAYS,
+        }));
+        return new Snapshot(snapshotModel(taken, config.source.name), client);
+    }
+    /** A snapshot by its id. */
+    static async get(snapshotId, options = {}) {
+        const client = clientFor(options);
+        return new Snapshot(snapshotModel(await guard(() => client.snapshots.get(snapshotId))), client);
+    }
+    /** The account's snapshots, a page at a time; `for await` walks them all. */
+    static async list(query = {}, options = {}) {
+        for (const field of ["cursor", "q", "anchor"])
+            if (query[field] !== undefined)
+                throw new NotSupportedError(`Listing snapshots by ${field}`, "List them (oldest first) and filter the result yourself; nextPage() walks the pages.");
+        if (query.sort !== undefined && query.sort !== "createdAt:asc")
+            throw new NotSupportedError(`Listing snapshots sorted by ${query.sort}`, "Runtime lists them oldest first: sort the result yourself.");
+        const client = clientFor(options);
+        const page = await guard(() => client.snapshots.list(query.limit ? { limit: Math.min(query.limit, 100) } : {}));
+        return paginate(page, (one) => new Snapshot(snapshotModel(one), client));
+    }
+    static async delete(snapshotId, options = {}) {
+        const client = clientFor(options);
+        await guard(() => client.snapshots.delete(snapshotId));
+    }
+    async delete() {
+        await guard(() => this.#client.snapshots.delete(this.id));
+    }
+    /** A new sandbox named `targetName`, started from this snapshot. */
+    async fork(targetName, options = {}) {
+        refuseApplication(options);
+        await startFromSnapshot(this.#client, this.id, targetName, {}, envRecord(options.envs));
+        return { name: targetName, snapshotId: this.id, type: "sandbox" };
+    }
+}
+/** `sandbox.snapshots`: this sandbox's snapshots, by name. */
+export class SandboxSnapshotsResource {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    get sandboxName() {
+        return this.#ctx.sandboxName;
+    }
+    async create(name) {
+        const taken = await this.#ctx.run((runtime) => runtime.snapshot({
+            ...(name ? { name } : {}),
+            labels: userLabels(this.#ctx.labels()),
+            retentionDays: SNAPSHOT_DAYS,
+        }));
+        return new Snapshot(snapshotModel(taken, this.sandboxName), this.#ctx.client);
+    }
+    async list() {
+        const page = await guard(() => this.#ctx.client.snapshots.list({ sandboxId: this.#ctx.sandboxId }));
+        const all = await guard(() => page.toArray());
+        return all.map((one) => new Snapshot(snapshotModel(one, this.sandboxName), this.#ctx.client));
+    }
+    /** This sandbox's newest snapshot with that name, or with that id. */
+    async get(snapshotName) {
+        return new Snapshot(snapshotModel(await this.#find(snapshotName), this.sandboxName), this.#ctx.client);
+    }
+    async #find(nameOrId) {
+        const client = this.#ctx.client;
+        const page = await guard(() => client.snapshots.list({ sandboxId: this.#ctx.sandboxId, name: nameOrId }));
+        const named = page.data.filter((one) => one.name === nameOrId).at(-1);
+        if (named)
+            return named;
+        if (UUID.test(nameOrId))
+            try {
+                const byId = await guard(() => client.snapshots.get(nameOrId));
+                if (byId.sourceSandboxId === this.#ctx.sandboxId)
+                    return byId;
+            }
+            catch (error) {
+                if (!isNotFound(error))
+                    throw error;
+            }
+        throw responseError(404, `snapshot ${nameOrId} not found`);
+    }
+    /** The id of a snapshot named, or given by id, for a fork. */
+    async idOf(nameOrId) {
+        return (await this.#find(nameOrId)).id;
+    }
+    async delete(snapshotName) {
+        const found = await this.#find(snapshotName);
+        await guard(() => this.#ctx.client.snapshots.delete(found.id));
+    }
+    restore(_snapshotName) {
+        return Promise.reject(new NotSupportedError("Restoring a sandbox to its snapshot in place", "Start a new sandbox from it: sandbox.fork(newName, { snapshotId }) or snapshot.fork(newName). The new sandbox has its own name and preview addresses."));
+    }
+}
+export { refuseApplication };

package/dist/blaxel/types.d.ts

@@ -0,0 +1,145 @@
+import type { WithRuntime } from "./client.js";
+import type { Env } from "./snapshot.js";
+export type Status = "DELETING" | "TERMINATED" | "FAILED" | "DEACTIVATED" | "DEACTIVATING" | "UPLOADING" | "BUILDING" | "DEPLOYING" | "DEPLOYED" | "BUILT" | "ARCHIVING" | "ARCHIVED" | "UNARCHIVING";
+export type Port = {
+    name?: string;
+    protocol?: "HTTP" | "TCP" | "UDP" | "TLS";
+    target: number;
+};
+export type EnvVar = {
+    name: string;
+    value: string;
+};
+export type ExpirationPolicy = {
+    action?: "delete";
+    type?: "ttl-idle" | "ttl-max-age" | "date";
+    value?: string;
+};
+export type SandboxLifecycle = {
+    expirationPolicies?: Array<ExpirationPolicy>;
+    terminatedRetention?: string;
+};
+export type SandboxNetwork = {
+    allowedDomains?: Array<string>;
+    egress?: unknown;
+    firewall?: unknown;
+    forbiddenDomains?: Array<string>;
+    proxy?: unknown;
+    subnet?: string;
+};
+export type VolumeBinding = {
+    name: string;
+    mountPath: string;
+    readOnly?: boolean;
+    type?: "persistent" | "ephemeral";
+    sizeMb?: number;
+};
+export type VolumeAttachment = {
+    mountPath?: string;
+    name?: string;
+    readOnly?: boolean;
+    sizeMb?: number;
+    type?: "persistent" | "ephemeral";
+};
+export type Metadata = {
+    name: string;
+    displayName?: string;
+    externalId?: string;
+    labels?: Record<string, string>;
+    createdAt?: string;
+    updatedAt?: string;
+    createdBy?: string;
+    updatedBy?: string;
+    readonly plan?: string;
+    readonly url?: string;
+    readonly workspace?: string;
+};
+export type SandboxRuntime = {
+    envs?: Array<Env>;
+    expires?: string;
+    extraArgs?: {
+        [key: string]: string;
+    };
+    image?: string;
+    memory?: number;
+    ports?: Array<Port>;
+    terminationGracePeriodSeconds?: number;
+    ttl?: string;
+};
+export type SandboxSpec = {
+    enabled?: boolean;
+    lifecycle?: SandboxLifecycle;
+    network?: SandboxNetwork;
+    region?: string;
+    runtime?: SandboxRuntime;
+    volumes?: Array<VolumeAttachment>;
+    vpc?: string;
+};
+export type CoreEvent = {
+    canaryRevision?: string;
+    message?: string;
+    revision?: string;
+    status?: string;
+    time?: string;
+    type?: string;
+};
+export type Sandbox = {
+    events?: Array<CoreEvent>;
+    readonly expiresIn?: number;
+    readonly lastUsedAt?: string;
+    metadata: Metadata;
+    spec: SandboxSpec;
+    state?: "RUNNING" | "STANDBY";
+    status?: Status;
+};
+export type SandboxConfiguration = {
+    forceUrl?: string;
+    headers?: Record<string, string>;
+    params?: Record<string, string>;
+} & Sandbox;
+export type SandboxCreateConfiguration = {
+    name?: string;
+    /** A Blaxel stock image (Runtime's stock image) or a ready Runtime image's name. */
+    image?: string;
+    /** MB; vCPUs follow as memory / 2048, at least 1. */
+    memory?: number;
+    ports?: (Port | Record<string, unknown>)[];
+    envs?: EnvVar[];
+    volumes?: (VolumeBinding | VolumeAttachment)[];
+    ttl?: string;
+    expires?: Date;
+    region?: string;
+    lifecycle?: SandboxLifecycle;
+    network?: SandboxNetwork;
+    snapshotEnabled?: boolean;
+    labels?: Record<string, string>;
+    extraArgs?: Record<string, string>;
+    externalId?: string;
+    /** Runtime-only: an explicit client, or fields for the create. */
+    withruntime?: WithRuntime;
+};
+export type SandboxUpdateMetadata = {
+    labels?: Record<string, string>;
+    displayName?: string;
+    externalId?: string;
+};
+export type SandboxUpdateNetwork = {
+    network?: SandboxNetwork;
+};
+export interface SessionCreateOptions {
+    expiresAt?: Date;
+    responseHeaders?: Record<string, string>;
+    requestHeaders?: Record<string, string>;
+}
+export interface SessionWithToken {
+    name: string;
+    url: string;
+    token: string;
+    expiresAt: Date;
+}
+/** Ports as Port objects, HTTP by default. */
+export declare function normalizePorts(ports?: (Port | Record<string, unknown>)[]): Port[] | undefined;
+/** Envs checked for a string name and value. */
+export declare function normalizeEnvs(envs?: EnvVar[]): EnvVar[] | undefined;
+/** Volume bindings as attachments. */
+export declare function normalizeVolumes(volumes?: (VolumeBinding | VolumeAttachment)[]): VolumeAttachment[] | undefined;

package/dist/blaxel/types.js

@@ -0,0 +1,60 @@
+/** Ports as Port objects, HTTP by default. */
+export function normalizePorts(ports) {
+    if (!ports || ports.length === 0)
+        return undefined;
+    return ports.map((port) => {
+        if (typeof port !== "object" ||
+            port === null ||
+            !("name" in port || "target" in port || "protocol" in port))
+            throw new Error(`Invalid port type: ${typeof port}. Expected Port object or object with port properties.`);
+        if (typeof port.target !== "number")
+            throw new Error(`Port target must be a number: ${JSON.stringify(port)}`);
+        return {
+            ...(typeof port.name === "string" ? { name: port.name } : {}),
+            target: port.target,
+            protocol: (typeof port.protocol === "string" ? port.protocol : "HTTP"),
+        };
+    });
+}
+/** Envs checked for a string name and value. */
+export function normalizeEnvs(envs) {
+    if (!envs || envs.length === 0)
+        return undefined;
+    return envs.map((env) => {
+        if (typeof env !== "object" || env === null)
+            throw new Error(`Invalid env type: ${typeof env}. Expected object with 'name' and 'value' keys.`);
+        if (!("name" in env) || !("value" in env))
+            throw new Error(`Environment variable object must have 'name' and 'value' keys: ${JSON.stringify(env)}`);
+        if (typeof env.name !== "string" || typeof env.value !== "string")
+            throw new Error(`Environment variable 'name' and 'value' must be strings: ${JSON.stringify(env)}`);
+        return { name: env.name, value: env.value };
+    });
+}
+/** Volume bindings as attachments. */
+export function normalizeVolumes(volumes) {
+    if (!volumes || volumes.length === 0)
+        return undefined;
+    return volumes.map((volume) => {
+        if (typeof volume !== "object" || volume === null)
+            throw new Error(`Invalid volume type: ${typeof volume}. Expected object with 'name' and 'mountPath' keys.`);
+        if (!("name" in volume) || !("mountPath" in volume))
+            throw new Error(`Volume binding object must have 'name' and 'mountPath' keys: ${JSON.stringify(volume)}`);
+        if (typeof volume.name !== "string" || typeof volume.mountPath !== "string")
+            throw new Error(`Volume binding 'name' and 'mountPath' must be strings: ${JSON.stringify(volume)}`);
+        const out = {
+            name: volume.name,
+            mountPath: volume.mountPath,
+            readOnly: volume.readOnly ?? false,
+        };
+        if (volume.type)
+            out.type = volume.type;
+        if (out.type === "ephemeral") {
+            if (typeof volume.sizeMb !== "number" || !(volume.sizeMb > 0))
+                throw new Error(`Ephemeral volume '${volume.name}' must have a positive 'sizeMb': ${JSON.stringify(volume)}`);
+            out.sizeMb = volume.sizeMb;
+        }
+        else if (typeof volume.sizeMb === "number")
+            out.sizeMb = volume.sizeMb;
+        return out;
+    });
+}

package/dist/blaxel/unsupported.d.ts

@@ -0,0 +1,22 @@
+/** A stand-in for a Blaxel export Runtime has no counterpart for. Importing
+ * it works, so a module that only mentions it still loads; calling it,
+ * building it or reading anything from it throws NotSupportedError naming the
+ * alternative. */
+export type Unsupported = {
+    (...args: unknown[]): never;
+    new (...args: unknown[]): never;
+    readonly [key: string]: (...args: unknown[]) => never;
+};
+export declare function unsupportedExport(name: string, alternative: string): Unsupported;
+/** A sandbox part Runtime has no counterpart for (`sandbox.sessions`,
+ * `sandbox.codegen`, ...): every method answers a rejected promise with
+ * NotSupportedError naming the alternative. */
+export declare function unsupportedPart(name: string, alternative: string): UnsupportedPart;
+export type UnsupportedPart = {
+    readonly [method: string]: (...args: unknown[]) => Promise<never>;
+};
+export declare const SESSIONS = "Share a port with sandbox.previews.create({ metadata: { name }, spec: { port, public: false } }) and a token from preview.tokens.create(expiresAt); drive the sandbox itself through this SDK.";
+export declare const CODEGEN = "Runtime has no hosted edit or rerank models: apply edits with sandbox.fs.write, and rank files with your own model.";
+export declare const SCHEDULES = "Schedule the call from your own scheduler (cron, a queue) and run it with sandbox.process.exec.";
+export declare const SYSTEM = "Runtime keeps each sandbox's agent current itself; there is nothing to upgrade.";
+export declare const DRIVES = "Use a Runtime volume: create one with runtime.volumes.create({ name }) and pass volumes: [{ name, mountPath }] at create.";

package/dist/blaxel/unsupported.js

@@ -0,0 +1,34 @@
+import { NotSupportedError } from "./errors.js";
+export function unsupportedExport(name, alternative) {
+    const fail = () => {
+        throw new NotSupportedError(`Blaxel's ${name}`, alternative);
+    };
+    return new Proxy(function unsupported() { }, {
+        apply: fail,
+        construct: fail,
+        get: (_target, property) => {
+            // Let the module system, inspectors and promise checks look at it
+            // without tripping: only a real use throws.
+            if (typeof property === "symbol" || property === "then" || property === "prototype")
+                return undefined;
+            return fail();
+        },
+    });
+}
+/** A sandbox part Runtime has no counterpart for (`sandbox.sessions`,
+ * `sandbox.codegen`, ...): every method answers a rejected promise with
+ * NotSupportedError naming the alternative. */
+export function unsupportedPart(name, alternative) {
+    return new Proxy({}, {
+        get: (_target, property) => {
+            if (typeof property === "symbol" || property === "then")
+                return undefined;
+            return () => Promise.reject(new NotSupportedError(`Blaxel's ${name}.${String(property)}`, alternative));
+        },
+    });
+}
+export const SESSIONS = "Share a port with sandbox.previews.create({ metadata: { name }, spec: { port, public: false } }) and a token from preview.tokens.create(expiresAt); drive the sandbox itself through this SDK.";
+export const CODEGEN = "Runtime has no hosted edit or rerank models: apply edits with sandbox.fs.write, and rank files with your own model.";
+export const SCHEDULES = "Schedule the call from your own scheduler (cron, a queue) and run it with sandbox.process.exec.";
+export const SYSTEM = "Runtime keeps each sandbox's agent current itself; there is nothing to upgrade.";
+export const DRIVES = "Use a Runtime volume: create one with runtime.volumes.create({ name }) and pass volumes: [{ name, mountPath }] at create.";