withruntime 0.8.4 → 0.10.0

package/dist/snapshots.d.ts

@@ -1,11 +1,12 @@
 import { Page } from "./page.js";
 import type { RequestOptions, Transport } from "./transport.js";
-/** A sandbox's whole machine (files, memory, running processes), kept on its
- * host to start new sandboxes from, and copied off the host so it survives
- * losing that host. */
+/** A sandbox's saved machine or disk, used to start new sandboxes. A verified
+ * off-host copy protects it from host loss once `backedUp` is true. */
 export type Snapshot = {
     id: string;
     kind: "snapshot";
+    /** Absent on older servers means memory. */
+    mode?: "memory" | "disk";
     status: string;
     state: "capturing" | "ready" | "failed" | "deleting" | "deleted";
     name: string | null;
@@ -17,13 +18,19 @@ export type Snapshot = {
         memoryGuarantee: string;
     };
     retentionDays: number;
+    /** True while raw fork memory awaits verified compression. The snapshot
+     * remains ready for starts on its current host, with no storage charge or
+     * off-host copy until final publication. Absent on older servers. */
+    compressionPending?: boolean;
     /** What it stores, and what storage is metered for: the bytes it alone holds. */
     storedBytes: number | null;
+    /** Zero while compression is pending; final bytes once verified. */
     meteredBytes: number | null;
     /** Whether its copy off the host is made and checked. */
     backedUp: boolean;
     /** Where that copy stands. `restoring`: its host was lost and it is being
-     * restored onto another; forks answer `snapshot_restoring` until it is. */
+     * restored onto another; forks answer `snapshot_restoring` until it is.
+     * `none` also covers temporary fork snapshots and pending compression. */
     durability: {
         state: "none" | "pending" | "durable" | "failed" | "restoring";
         durableAt: string | null;
@@ -36,6 +43,8 @@ export type Snapshot = {
     [key: string]: unknown;
 };
 export type SnapshotOptions = {
+    /** Save files for a fresh boot, or the whole machine (default). */
+    mode?: "memory" | "disk";
     name?: string;
     labels?: Record<string, string>;
     retentionDays?: number;
@@ -54,7 +63,13 @@ export declare class Snapshots {
         name?: string;
         state?: "capturing" | "ready" | "failed" | "deleting";
         limit?: number;
-    }): Promise<Page<Snapshot>>;
+    }, options?: RequestOptions): Promise<Page<Snapshot>>;
+    /** Replace supplied labels or name; omitted fields are preserved. Null clears the name. */
+    update(id: string, input: {
+        name?: string | null;
+        labels?: Record<string, string>;
+        ifLabels?: Record<string, string>;
+    }, options?: RequestOptions): Promise<Snapshot>;
     delete(id: string, options?: RequestOptions): Promise<void>;
     extend(id: string, retentionDays: number, options?: RequestOptions): Promise<Snapshot>;
 }

package/dist/snapshots.js

@@ -19,7 +19,7 @@ export class Snapshots {
     get(id, options = {}) {
         return this.t.json({ method: "GET", path: `/v1/snapshots/${enc(id)}`, ...options });
     }
-    async list(filter = {}) {
+    async list(filter = {}, options = {}) {
         const query = {
             sandboxId: filter.sandboxId,
             name: filter.name,
@@ -31,11 +31,21 @@ export class Snapshots {
                 method: "GET",
                 path: "/v1/snapshots",
                 query: { ...query, cursor },
+                ...options,
             });
             return new Page(body.data, body.nextCursor, (next) => fetchPage(next));
         };
         return fetchPage();
     }
+    /** Replace supplied labels or name; omitted fields are preserved. Null clears the name. */
+    update(id, input, options = {}) {
+        return this.t.json({
+            method: "POST",
+            path: `/v1/snapshots/${enc(id)}:update`,
+            body: input,
+            ...options,
+        });
+    }
     async delete(id, options = {}) {
         await this.t.json({
             method: "POST",

package/dist/sprites/index.d.ts

@@ -0,0 +1,251 @@
+import { EventEmitter } from "node:events";
+import { PassThrough, Writable } from "node:stream";
+import type { Runtime } from "../client.js";
+import type { Sandbox } from "../sandbox.js";
+import { CompatibilityError, type ClientOptions as RuntimeClientOptions } from "../compat/core.js";
+export { CompatibilityError };
+export interface ClientOptions extends RuntimeClientOptions {
+    baseURL?: string;
+    timeout?: number;
+    controlMode?: boolean;
+}
+export interface SpriteConfig {
+    ramMB?: number;
+    cpus?: number;
+    region?: string;
+    storageGB?: number;
+}
+export interface CreateSpriteOptions {
+    config?: SpriteConfig;
+    environment?: Record<string, string>;
+    labels?: string[];
+    urlSettings?: {
+        auth?: string;
+        privateAccess?: string;
+    };
+    runtime?: "default" | "dev";
+    waitForCapacity?: boolean;
+}
+export interface SpawnOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    tty?: boolean;
+    rows?: number;
+    cols?: number;
+    detachable?: boolean;
+    sessionId?: string;
+    controlMode?: boolean;
+}
+export interface ExecOptions extends SpawnOptions {
+    encoding?: BufferEncoding;
+    maxBuffer?: number;
+    signal?: AbortSignal;
+    timeout?: number;
+}
+export interface ExecResult {
+    stdout: string | Buffer;
+    stderr: string | Buffer;
+    exitCode: number;
+}
+export type FilesystemErrorCode = "ENOENT" | "EEXIST" | "ENOTDIR" | "EISDIR" | "EACCES" | "EPERM" | "ENOTEMPTY" | "EINVAL" | "EIO" | "UNKNOWN";
+export declare class FilesystemError extends Error {
+    readonly code: FilesystemErrorCode;
+    readonly path: string;
+    readonly syscall?: string | undefined;
+    constructor(message: string, code: FilesystemErrorCode, path: string, syscall?: string | undefined);
+}
+export interface Dirent {
+    name: string;
+    parentPath: string;
+    isDirectory(): boolean;
+    isFile(): boolean;
+    isSymbolicLink(): boolean;
+}
+export interface ReaddirOptions {
+    withFileTypes?: boolean;
+    recursive?: boolean;
+    pattern?: string;
+    encoding?: BufferEncoding;
+}
+export declare class ExecError extends Error {
+    readonly exitCode: number;
+    readonly stdout: string | Buffer;
+    readonly stderr: string | Buffer;
+    constructor(message: string, exitCode: number, stdout: string | Buffer, stderr: string | Buffer);
+}
+export declare class SpritesClient {
+    readonly runtime: Runtime;
+    constructor(token?: string, options?: ClientOptions);
+    sprite(name: string): Sprite;
+    createSprite(name: string, input?: SpriteConfig | CreateSpriteOptions, extra?: Omit<CreateSpriteOptions, "config">): Promise<Sprite>;
+    getSprite(name: string): Promise<Sprite>;
+    deleteSprite(name: string): Promise<void>;
+    listSprites(options?: {
+        prefix?: string;
+        maxResults?: number;
+        continuationToken?: string;
+        bulkLoad?: boolean;
+    }): Promise<{
+        sprites: {
+            id: string;
+            name: string;
+            status: "paused" | "stopped" | "stopping" | "starting" | "running" | "pausing" | "resuming";
+            createdAt: Date;
+            updatedAt: Date;
+            config: {
+                cpus: number;
+                ramMB: number;
+                storageGB: number;
+                region: string;
+            };
+        }[];
+        hasMore: boolean;
+        nextContinuationToken: string | undefined;
+    }>;
+    listAllSprites(prefix?: string): Promise<Sprite[]>;
+    restartSprite(name: string): Promise<{
+        spriteName: string;
+        machineId: string;
+        message: string;
+    }>;
+    updateURLSettings(name: string, settings: {
+        auth?: string;
+        privateAccess?: string;
+    }): Promise<void>;
+}
+export declare class Sprite {
+    readonly name: string;
+    readonly client: SpritesClient;
+    id?: string;
+    status?: string;
+    config?: SpriteConfig;
+    createdAt?: Date;
+    updatedAt?: Date;
+    url?: string;
+    labels: string[];
+    constructor(name: string, client: SpritesClient);
+    hydrate(s: Sandbox): void;
+    native(): Promise<Sandbox>;
+    spawn(command: string, args?: string[], options?: SpawnOptions): SpriteCommand;
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    execFile(file: string, args?: string[], options?: ExecOptions): Promise<ExecResult>;
+    execFileHTTP(file: string, args?: string[], options?: ExecOptions): Promise<ExecResult>;
+    createSession(command: string, args?: string[], options?: SpawnOptions): SpriteCommand;
+    attachSession(sessionId: string, options?: SpawnOptions): SpriteCommand;
+    listSessions(): Promise<{
+        id: string;
+        command: string;
+        created: Date;
+        workdir: string;
+        isActive: boolean;
+        tty: boolean;
+    }[]>;
+    delete(): Promise<void>;
+    destroy(): Promise<void>;
+    restart(): Promise<{
+        spriteName: string;
+        machineId: string;
+        message: string;
+    }>;
+    filesystem(workingDir?: string): SpriteFilesystem;
+    createCheckpoint(_comment?: string): Promise<never>;
+    listCheckpoints(): Promise<never>;
+    getCheckpoint(_id: string): Promise<never>;
+    updateURLSettings(settings: {
+        auth?: string;
+        privateAccess?: string;
+    }): Promise<void>;
+    update(options: {
+        labels?: string[];
+        urlSettings?: {
+            auth?: string;
+            privateAccess?: string;
+        };
+    }): Promise<this>;
+}
+export declare class SpriteCommand extends EventEmitter {
+    readonly stdout: PassThrough;
+    readonly stderr: PassThrough;
+    readonly stdin: Writable;
+    private readonly process;
+    private readonly completion;
+    private code;
+    private readonly controller;
+    constructor(sprite: Sprite, command: string, args?: string[], options?: SpawnOptions);
+    private follow;
+    start(): Promise<void>;
+    wait(): Promise<number>;
+    kill(signal?: string): void;
+    signal(signal: string): void;
+    resize(cols: number, rows: number): void;
+    close(): void;
+    exitCode(): number;
+}
+export declare class SpriteFilesystem {
+    private readonly get;
+    private readonly files;
+    constructor(get: () => Promise<Sandbox>, cwd?: string);
+    readFile(path: string, encoding: "utf8"): Promise<string>;
+    readFile(path: string, encoding?: null): Promise<Buffer>;
+    writeFile(path: string, data: string | Uint8Array, options?: {
+        mode?: number;
+    }): Promise<void>;
+    readdir(path: string, options?: ReaddirOptions & {
+        withFileTypes?: false;
+    }): Promise<string[]>;
+    readdir(path: string, options: ReaddirOptions & {
+        withFileTypes: true;
+    }): Promise<Dirent[]>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+        mode?: number;
+    }): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    stat(path: string): Promise<{
+        size: number;
+        mode: number;
+        mtime: Date;
+        atime: Date;
+        birthtime: Date;
+        isDirectory: () => boolean;
+        isFile: () => boolean;
+        isSymbolicLink: () => boolean;
+    }>;
+    rename(from: string, to: string): Promise<void>;
+    copyFile(from: string, to: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    chmod(path: string, mode: number, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    appendFile(path: string, data: string | Uint8Array): Promise<void>;
+    readJSON<T = unknown>(path: string): Promise<T>;
+    writeJSON(path: string, data: unknown, options?: {
+        spaces?: number;
+    }): Promise<void>;
+}
+export declare class CheckpointStream {
+    private readonly messages;
+    private index;
+    constructor(messages: {
+        type: "complete" | "error" | "info";
+        data?: string;
+        error?: string;
+    }[]);
+    next(): Promise<{
+        type: "complete" | "error" | "info";
+        data?: string;
+        error?: string;
+    } | null>;
+    processAll(handler: (message: (typeof this.messages)[number]) => void | Promise<void>): Promise<void>;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncGenerator<{
+        type: "complete" | "error" | "info";
+        data?: string;
+        error?: string;
+    }, void, unknown>;
+}