withruntime 0.7.2 → 0.8.1

package/dist/blaxel/sandbox.d.ts

@@ -0,0 +1,180 @@
+import type { Runtime } from "../client.js";
+import { type RuntimeCreate, type RuntimeOptions, type RuntimeSandbox } from "./client.js";
+import { SandboxFileSystem } from "./filesystem.js";
+import { type PaginatedList } from "./pagination.js";
+import { SandboxPreviews } from "./preview.js";
+import { SandboxProcess } from "./process.js";
+import { SandboxSnapshotsResource, type Env, type SandboxForkResponse, type SandboxRestoreResponse, type SandboxSnapshot } from "./snapshot.js";
+import { type Metadata, type Sandbox as SandboxModel, type SandboxCreateConfiguration, type SandboxLifecycle, type SandboxNetwork, type SandboxSpec, type SandboxUpdateMetadata, type SandboxUpdateNetwork, type SessionWithToken, type Status, type VolumeAttachment } from "./types.js";
+import { type UnsupportedPart } from "./unsupported.js";
+/** Blaxel's defaults (checked 27 September 2026). */
+export declare const DEFAULT_IMAGE = "blaxel/base-image:latest";
+export declare const DEFAULT_MEMORY = 4096;
+/** Blaxel gives a sandbox one vCPU per 2048 MB of memory. */
+export declare const MEMORY_PER_VCPU = 2048;
+export type SandboxListQuery = {
+    showTerminated?: boolean;
+    cursor?: string;
+    limit?: number;
+    sort?: "createdAt:desc" | "createdAt:asc" | "name:asc" | "name:desc";
+    q?: string;
+    anchor?: "end";
+    status?: string;
+    externalId?: string;
+};
+export type SandboxForkOptions = {
+    targetType?: "sandbox" | "application";
+    port?: number;
+    traffic?: number;
+    customDomain?: string;
+    prefix?: string;
+    /** A snapshot's id or, of this sandbox's snapshots, its name. */
+    snapshotId?: string;
+    envs?: Env[];
+};
+export type SandboxArchiveOptions = {
+    wait?: boolean;
+    maxWait?: number;
+    interval?: number;
+};
+/** What a create asked for that no label keeps: shown by `spec` in the
+ * client that created the sandbox. */
+type Asked = {
+    envs?: Record<string, string>;
+    network?: SandboxNetwork;
+    volumes?: VolumeAttachment[];
+};
+/** The labels a new sandbox carries: the caller's, and under `blaxel/` what
+ * Blaxel keeps and Runtime has no field for, so any client (the Python
+ * adapter too) reads the same `spec`. */
+export declare function labelsFor(config: SandboxCreateConfiguration, image: string): Record<string, string>;
+type Resolved = {
+    runtime: RuntimeSandbox;
+    client: Runtime;
+    asked?: Asked;
+};
+/** A duration as Blaxel writes it ("30m", "24h", "7d", "1w", "1h30m"). */
+export declare function durationMs(value: string): number;
+/** The lease and the paused retention that honour Blaxel's TTL, expiry and
+ * lifecycle: never deleted before Blaxel would delete it. A fixed deadline
+ * within the hour is a lease that ends the sandbox; any other deadline keeps
+ * a paused sandbox that many days, rounded up; none keeps it 365 days. */
+export declare function lifetimeOf(asked: {
+    ttl?: string | null;
+    expires?: Date;
+    lifecycle?: SandboxLifecycle | null;
+}): {
+    timeoutSeconds: number;
+    onLeaseEnd: "pause" | "stop";
+    days: number;
+};
+/** Blaxel's network settings as Runtime's rules: allowed and forbidden
+ * domains, from the network itself or from its proxy (Blaxel's current
+ * place for them). Anything else of the proxy is refused. */
+export declare function networkRules(network: SandboxNetwork): NonNullable<RuntimeCreate["network"]>;
+/** A Blaxel image `ns/name:tag` as the Runtime image name and tag it maps to
+ * (Runtime names allow no "/"): every "/" becomes "-" (`ns-name`), and the
+ * tag is `latest` when none is given. The Python adapter maps the same way. */
+export declare function imageRef(image: string): {
+    name: string;
+    tag: string;
+};
+/** A sandbox with Blaxel's methods. `sandbox.withruntime` is the Runtime
+ * sandbox underneath, for anything Blaxel has no name for. */
+export declare class SandboxInstance {
+    #private;
+    readonly fs: SandboxFileSystem;
+    readonly network: {
+        fetch: (port: number, path?: string, init?: RequestInit) => Promise<Response>;
+    };
+    readonly process: SandboxProcess;
+    readonly previews: SandboxPreviews;
+    readonly snapshots: SandboxSnapshotsResource;
+    readonly sessions: UnsupportedPart;
+    readonly schedules: UnsupportedPart;
+    readonly codegen: UnsupportedPart;
+    readonly system: UnsupportedPart;
+    readonly drives: UnsupportedPart;
+    /** Blaxel's HTTP/2 session; Runtime's SDK keeps its own connections. */
+    h2Session: null;
+    /** Use SandboxInstance.create, createIfNotExists or get. */
+    constructor(resolved: Resolved);
+    /** The Runtime sandbox underneath: metrics, network rules, desktop,
+     * terminals and the rest of Runtime's SDK. */
+    get withruntime(): RuntimeSandbox;
+    /** The sandbox's name, or its Runtime id when it was made without one. */
+    get name(): string;
+    get metadata(): Metadata;
+    /** From the sandbox's labels, so every client sees the same; the envs,
+     * network and volumes only in the client that created it. */
+    get spec(): SandboxSpec;
+    get status(): Status;
+    /** RUNNING, or STANDBY for a paused sandbox. */
+    get state(): "RUNNING" | "STANDBY" | undefined;
+    get events(): [];
+    get errors(): [];
+    get lastUsedAt(): string | undefined;
+    get h2Domain(): null;
+    /** Seconds until Runtime deletes the sandbox: the end of a lease that ends
+     * it, or of a paused one's retention; undefined while not yet known. */
+    get expiresIn(): number | undefined;
+    /** Creates a sandbox and answers once it runs. Blaxel's defaults: the base
+     * image (Runtime's stock image) and 4096 MB, with vCPUs at one per 2048 MB.
+     * Funding is left to Runtime: the free trial while the account has trial
+     * time, then prepaid credit. A name another live sandbox holds is refused
+     * with a 409, as in Blaxel. */
+    static create<T extends typeof SandboxInstance>(this: T, sandbox?: SandboxCreateConfiguration | SandboxModel, { createIfNotExist }?: {
+        safe?: boolean;
+        createIfNotExist?: boolean;
+    }): Promise<InstanceType<T>>;
+    /** The named sandbox, or a new one when no live sandbox has the name.
+     * Runtime settles a race between two callers: both get the same sandbox. */
+    static createIfNotExists<T extends typeof SandboxInstance>(this: T, sandbox: SandboxCreateConfiguration | SandboxModel): Promise<InstanceType<T>>;
+    /** The live sandbox with this name (or Runtime id). It is not woken: the
+     * next call wakes it. */
+    static get<T extends typeof SandboxInstance>(this: T, sandboxName: string, options?: RuntimeOptions): Promise<InstanceType<T>>;
+    /** The newest live sandbox created with this externalId. */
+    static getByExternalId<T extends typeof SandboxInstance>(this: T, externalId: string, options?: RuntimeOptions): Promise<InstanceType<T>>;
+    /** Live sandboxes, oldest first, a page at a time; `for await` walks them
+     * all. `externalId` narrows; `showTerminated` adds ended ones. */
+    static list<T extends typeof SandboxInstance>(this: T, query?: SandboxListQuery, options?: RuntimeOptions): Promise<PaginatedList<InstanceType<T>>>;
+    /** Deletes the sandbox: it ends at once, its files and memory with it. */
+    static delete(sandboxName: string, options?: RuntimeOptions): Promise<SandboxModel>;
+    delete(): Promise<SandboxModel>;
+    /** Replaces the labels (when given), the display name and the externalId. */
+    static updateMetadata(sandboxName: string, metadata: SandboxUpdateMetadata, options?: RuntimeOptions): Promise<SandboxInstance>;
+    /** A new TTL (null: none): how long a paused sandbox is kept follows it, as
+     * at create. A running lease is not shortened. */
+    static updateTtl(sandboxName: string, ttl: string | null, options?: RuntimeOptions): Promise<SandboxInstance>;
+    /** A new lifecycle (null: none), as updateTtl. */
+    static updateLifecycle(sandboxName: string, lifecycle: SandboxLifecycle | null, options?: RuntimeOptions): Promise<SandboxInstance>;
+    /** Replaces the sandbox's network rules. */
+    static updateNetwork(sandboxName: string, network: SandboxUpdateNetwork, options?: RuntimeOptions): Promise<SandboxInstance>;
+    /** Deprecated in Blaxel: a sandbox is ready when create answers. */
+    wait(_options?: {
+        maxWait?: number;
+        interval?: number;
+    }): Promise<this>;
+    /** Archives the sandbox: on Runtime it pauses, keeping its files and also
+     * its memory and processes. The next call, or unarchive, wakes it. */
+    static archive(sandboxName: string, options?: SandboxArchiveOptions & RuntimeOptions): Promise<SandboxInstance>;
+    archive(options?: SandboxArchiveOptions): Promise<this>;
+    static unarchive(sandboxName: string, options?: SandboxArchiveOptions & RuntimeOptions): Promise<SandboxInstance>;
+    unarchive(options?: SandboxArchiveOptions): Promise<this>;
+    /** A request to a port inside the sandbox, through a private preview of
+     * that port (made on first use, then reused) and its token. */
+    fetch(port: number, path?: string, init?: RequestInit): Promise<Response>;
+    /** Deprecated in Blaxel: sandbox.snapshots.create(name). */
+    snapshot(name?: string): Promise<SandboxSnapshot>;
+    /** Deprecated in Blaxel: sandbox.snapshots.list(). */
+    listSnapshots(): Promise<SandboxSnapshot[]>;
+    /** Deprecated in Blaxel: sandbox.snapshots.delete(name). */
+    deleteSnapshot(snapshotId: string): Promise<void>;
+    restore(snapshotId: string): Promise<SandboxRestoreResponse>;
+    /** A new sandbox named `targetName`: a copy of this one as it is now
+     * (files, memory and running processes), or started from a snapshot with
+     * `snapshotId`. `envs` are added over this sandbox's. */
+    fork(targetName: string, options?: SandboxForkOptions): Promise<SandboxForkResponse>;
+    static fromSession(_session: SessionWithToken): Promise<never>;
+}
+export {};