withruntime 0.11.2 → 0.12.0

package/dist/sprites/index.d.ts

@@ -2,8 +2,173 @@ 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";
+import { CompatibilityError, type ClientOptions as RuntimeClientOptions, type Refused, type RefusedAsync } from "../compat/core.js";
 export { CompatibilityError };
+export declare const ERR_CODE_CREATION_RATE_LIMITED = "sprite_creation_rate_limited";
+export declare const ERR_CODE_CONCURRENT_LIMIT_EXCEEDED = "concurrent_sprite_limit_exceeded";
+export interface URLSettings {
+    auth?: string;
+    privateAccess?: "admins" | "org_users";
+}
+export interface Checkpoint {
+    id: string;
+    createTime: Date;
+    comment?: string;
+    history?: string[];
+    isAuto?: boolean;
+    sourceId?: string;
+    health?: string;
+}
+export interface StreamMessage {
+    type: "info" | "stdout" | "stderr" | "error" | "complete";
+    data?: string;
+    error?: string;
+}
+export interface PortMapping {
+    localPort: number;
+    remotePort: number;
+    remoteHost?: string;
+}
+export interface PolicyRule {
+    domain?: string;
+    action?: "allow" | "deny";
+    include?: string;
+}
+export interface NetworkPolicy {
+    rules: PolicyRule[];
+}
+export interface PrivilegesPolicy {
+    profile?: "" | "minimal" | "standard" | "privileged";
+    devices?: string[];
+    noNewPrivileges?: boolean;
+}
+export interface ResourcesPolicy {
+    memory?: {
+        limitMB: number;
+        autoscale?: boolean;
+    };
+}
+export interface ServiceRequest {
+    cmd: string;
+    args?: string[];
+    env?: Record<string, string>;
+    dir?: string;
+    needs?: string[];
+    httpPort?: number;
+}
+export interface ServiceLogEvent {
+    type: "stdout" | "stderr" | "exit" | "error" | "complete" | "started" | "stopping" | "stopped";
+    data?: string;
+    exitCode?: number;
+    timestamp: number;
+    logFiles?: Record<string, string>;
+}
+export interface SessionKillEvent {
+    type: "signal" | "timeout" | "exited" | "killed" | "error" | "complete";
+    message?: string;
+    signal?: string;
+    pid?: number;
+    exitCode?: number;
+}
+export interface SpriteCheck {
+    spriteName: string;
+    spriteId: string;
+    status: string;
+    reason?: string;
+    checkedAt: Date;
+    elapsed?: number;
+}
+export interface SpriteStateEvent {
+    type?: "heartbeat";
+    name?: string;
+    status?: string;
+    organization: {
+        running: number;
+        warm: number;
+        cold: number;
+    };
+}
+export interface PortNotification {
+    type: "port_opened" | "port_closed";
+    port: number;
+    address: string;
+    pid: number;
+}
+export interface PortList {
+    type: "port_list";
+    ports: PortNotification[];
+}
+export type PortWatchEvent = PortList | PortNotification;
+export interface FilesystemWatchEvent {
+    type: "subscribed" | "event" | "error";
+    paths?: string[];
+    path?: string;
+    event?: "write" | "create" | "remove" | "rename" | "chmod";
+    timestamp?: string;
+    size?: number;
+    isDir?: boolean;
+    message?: string;
+}
+/** A Sprites progress or event stream: the work behind it runs whether or
+ * not anyone reads, as the vendor's server-side operation does; `next()`
+ * answers null at the end, `close()` stops reading (and stops a watch). */
+declare class Feed<T> {
+    #private;
+    constructor(source?: AsyncIterable<T>);
+    protected push(item: T): void;
+    protected end(error?: unknown): void;
+    /** Called once by close(); a watch stops its native watch here. */
+    protected stop(): void;
+    next(): Promise<T | null>;
+    processAll(handler: (item: T) => void | Promise<void>): Promise<void>;
+    close(): void;
+    isClosed(): boolean;
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+}
+export declare class CheckpointStream extends Feed<StreamMessage> {
+}
+export declare class RestoreStream extends Feed<StreamMessage> {
+}
+export declare class ServiceLogStream extends Feed<ServiceLogEvent> {
+}
+export declare class SessionKillStream extends Feed<SessionKillEvent> {
+}
+export declare class SpriteListStream extends Feed<SpriteStateEvent> {
+}
+export declare class APIError extends Error {
+    readonly errorCode?: string;
+    readonly statusCode?: number;
+    readonly limit?: number;
+    readonly windowSeconds?: number;
+    readonly retryAfterSeconds?: number;
+    readonly currentCount?: number;
+    readonly upgradeAvailable?: boolean;
+    readonly upgradeUrl?: string;
+    readonly retryAfterHeader?: number;
+    readonly rateLimitLimit?: number;
+    readonly rateLimitRemaining?: number;
+    readonly rateLimitReset?: number;
+    constructor(message: string, options?: {
+        errorCode?: string;
+        statusCode?: number;
+        limit?: number;
+        windowSeconds?: number;
+        retryAfterSeconds?: number;
+        currentCount?: number;
+        upgradeAvailable?: boolean;
+        upgradeUrl?: string;
+        retryAfterHeader?: number;
+        rateLimitLimit?: number;
+        rateLimitRemaining?: number;
+        rateLimitReset?: number;
+    });
+    isRateLimitError(): boolean;
+    isCreationRateLimited(): boolean;
+    isConcurrentLimitExceeded(): boolean;
+    getRetryAfterSeconds(): number | undefined;
+}
+/** The vendor's parser, for callers that read Sprites-shaped answers themselves. */
+export declare function parseAPIError(statusCode: number, body: string | undefined, headers?: Record<string, string>): APIError | undefined;
 export interface ClientOptions extends RuntimeClientOptions {
     baseURL?: string;
     timeout?: number;
@@ -68,13 +233,45 @@ export interface ReaddirOptions {
     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);
+    readonly result: ExecResult;
+    constructor(message: string, result: ExecResult);
+    get exitCode(): number;
+    get stdout(): string | Buffer;
+    get stderr(): string | Buffer;
+}
+export declare class OpConn extends EventEmitter {
+    readonly write: Refused;
+    readonly sendEOF: Refused;
+    readonly resize: Refused;
+    readonly signal: Refused;
+    readonly handleData: Refused;
+    readonly handleText: Refused;
+    readonly complete: Refused;
+    readonly close: Refused;
+    readonly isClosed: Refused;
+    readonly getExitCode: Refused;
+    readonly wait: RefusedAsync;
+}
+export declare class ControlConnection extends EventEmitter {
+    readonly isActive: Refused;
+    readonly setActive: Refused;
+    readonly clearOpConn: Refused;
+    readonly connect: RefusedAsync;
+    readonly startOp: RefusedAsync;
+    readonly sendData: Refused;
+    readonly close: Refused;
+    readonly isClosed: Refused;
 }
 export declare class SpritesClient {
     readonly runtime: Runtime;
+    /** The Runtime API the calls go to. */
+    readonly baseURL: string;
+    /** The Runtime key given, if any; otherwise RUNTIME_API_KEY or the saved login is used. */
+    readonly token: string;
+    /** Always false: true is refused (control mode). */
+    readonly controlMode = false;
+    static readonly createToken: RefusedAsync;
+    readonly watchSprites: RefusedAsync;
     constructor(token?: string, options?: ClientOptions);
     sprite(name: string): Sprite;
     createSprite(name: string, input?: SpriteConfig | CreateSpriteOptions, extra?: Omit<CreateSpriteOptions, "config">): Promise<Sprite>;
@@ -108,28 +305,71 @@ export declare class SpritesClient {
         machineId: string;
         message: string;
     }>;
+    /** Its state as Runtime reports it now; `elapsed` is the lookup's milliseconds. */
+    checkSprite(name: string): Promise<SpriteCheck>;
+    /** Runtime keeps each sandbox's system current itself, so there is nothing
+     * to move to: this checks that the Sprite exists, as the vendor's call does. */
+    upgradeSprite(name: string): Promise<void>;
+    updateSprite(name: string, options: {
+        urlSettings?: URLSettings;
+        labels?: string[];
+    }): Promise<Sprite>;
     updateURLSettings(name: string, settings: {
         auth?: string;
         privateAccess?: string;
     }): Promise<void>;
 }
 export declare class Sprite {
+    #private;
     readonly name: string;
     readonly client: SpritesClient;
     id?: string;
+    /** Runtime does not send the organization's name with a sandbox. */
+    organizationName?: string;
     status?: string;
     config?: SpriteConfig;
+    /** Set by createSprite; Runtime keeps it in the sandbox, not in its listing. */
+    environment?: Record<string, string>;
     createdAt?: Date;
     updatedAt?: Date;
     url?: string;
+    urlSettings?: URLSettings;
+    /** Vendor storage and version fields; Runtime has no equivalent to report. */
+    bucketName?: string;
+    primaryRegion?: string;
+    version?: string;
+    environmentVersion?: string;
     labels: string[];
+    lastRunningAt?: Date;
+    lastWarmingAt?: Date;
+    readonly restoreCheckpoint: RefusedAsync;
+    readonly getControlConnection: RefusedAsync;
+    readonly listServices: RefusedAsync;
+    readonly getService: RefusedAsync;
+    readonly createService: RefusedAsync;
+    readonly deleteService: RefusedAsync;
+    readonly startService: RefusedAsync;
+    readonly stopService: RefusedAsync;
+    readonly restartService: RefusedAsync;
+    readonly getServiceLogs: RefusedAsync;
+    readonly signalService: RefusedAsync;
+    readonly getPrivilegesPolicy: RefusedAsync;
+    readonly updatePrivilegesPolicy: RefusedAsync;
+    readonly deletePrivilegesPolicy: RefusedAsync;
+    readonly getResourcesPolicy: RefusedAsync;
+    readonly updateResourcesPolicy: RefusedAsync;
+    readonly deleteResourcesPolicy: RefusedAsync;
     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>;
+    /** Runtime's commands are HTTP calls already; `input` is written to stdin
+     * and stdin closed, and without it stdin is closed at once. */
+    execFileHTTP(file: string, args?: string[], options?: Omit<ExecOptions, "tty" | "sessionId" | "controlMode" | "detachable"> & {
+        input?: string | Buffer;
+    }): Promise<ExecResult>;
     createSession(command: string, args?: string[], options?: SpawnOptions): SpriteCommand;
     attachSession(sessionId: string, options?: SpawnOptions): SpriteCommand;
     listSessions(): Promise<{
@@ -148,9 +388,34 @@ export declare class Sprite {
         message: string;
     }>;
     filesystem(workingDir?: string): SpriteFilesystem;
-    createCheckpoint(_comment?: string): Promise<never>;
-    listCheckpoints(): Promise<never>;
-    getCheckpoint(_id: string): Promise<never>;
+    /** Ends a session: `signal` (SIGTERM by default; "TERM" works too), then
+     * SIGKILL if it has not exited within `timeout` ("10s" by default). */
+    killSession(sessionId: string, signal?: string, timeout?: string): Promise<SessionKillStream>;
+    /** Ports listening in the Sprite now, then each one opened or closed. */
+    watchPorts(): Promise<PortWatcher>;
+    /** Runtime keeps each sandbox's system current itself; this checks it exists. */
+    upgrade(): Promise<void>;
+    check(): Promise<SpriteCheck>;
+    /** A checkpoint is a Runtime disk snapshot: the files, not the running
+     * processes. The Sprite is paused for the moment it takes, then woken.
+     * Progress arrives as the vendor's stream; a refusal is an `error` message. */
+    createCheckpoint(comment?: string): Promise<CheckpointStream>;
+    /** This Sprite's disk snapshots, newest first. */
+    listCheckpoints(historyFilter?: string): Promise<Checkpoint[]>;
+    getCheckpoint(id: string): Promise<Checkpoint>;
+    /** Forwards localhost:`localPort` here to `remotePort` in the Sprite. */
+    proxyPort(localPort: number, remotePort: number, remoteHost?: string): Promise<ProxySession>;
+    proxyPorts(mappings: PortMapping[]): Promise<ProxySession[]>;
+    /** Runtime's network rules as Sprites rules: `* deny` closes the internet,
+     * allow rules are the only destinations reachable, deny rules are refused. */
+    getNetworkPolicy(): Promise<NetworkPolicy>;
+    /** Replaces the rules, keeping any host:port openings set through Runtime. */
+    updateNetworkPolicy(policy: NetworkPolicy): Promise<void>;
+    /** Control mode is never on: Runtime refuses `controlMode: true`. */
+    useControlMode(): boolean;
+    hasControlConnection(): boolean;
+    /** Nothing to close: no control connection is ever opened. */
+    closeControlConnection(): void;
     updateURLSettings(settings: {
         auth?: string;
         privateAccess?: string;
@@ -163,6 +428,55 @@ export declare class Sprite {
         };
     }): Promise<this>;
 }
+/** A local listener that carries each connection to a port in the Sprite,
+ * over Runtime's tunnel. Node and Bun. */
+export declare class ProxySession extends EventEmitter {
+    #private;
+    readonly localPort: number;
+    readonly remotePort: number;
+    readonly remoteHost: string;
+    constructor(client: SpritesClient | {
+        baseURL: string;
+        token: string;
+    }, spriteName: string, mapping: PortMapping);
+    start(): Promise<void>;
+    localAddr(): string | null;
+    close(): void;
+    wait(): Promise<void>;
+}
+export declare class ProxyManager {
+    #private;
+    addSession(session: ProxySession): void;
+    closeAll(): void;
+    waitAll(): Promise<void>;
+}
+export declare function proxyPort(client: SpritesClient | {
+    baseURL: string;
+    token: string;
+}, spriteName: string, localPort: number, remotePort: number, remoteHost?: string): Promise<ProxySession>;
+/** All or none: a mapping that cannot start closes the ones before it. */
+export declare function proxyPorts(client: SpritesClient | {
+    baseURL: string;
+    token: string;
+}, spriteName: string, mappings: PortMapping[]): Promise<ProxySession[]>;
+/** Polls the Sprite's listening TCP sockets once a second with `ss` (as
+ * Sprites' own watcher keeps a connection open, this keeps it awake). */
+export declare class PortWatcher extends Feed<PortWatchEvent> {
+    #private;
+    constructor(client: SpritesClient, spriteName: string);
+    connect(): Promise<void>;
+    protected stop(): void;
+}
+/** Runtime's file watch, one per path, as Sprites' watch events. */
+export declare class FilesystemWatcher extends Feed<FilesystemWatchEvent> {
+    #private;
+    private readonly sandbox;
+    private readonly paths;
+    private readonly recursive;
+    constructor(sandbox: () => Promise<Sandbox>, paths: string[], workingDir: string, recursive: boolean);
+    connect(): Promise<void>;
+    protected stop(): void;
+}
 export declare class SpriteCommand extends EventEmitter {
     readonly stdout: PassThrough;
     readonly stderr: PassThrough;
@@ -182,7 +496,9 @@ export declare class SpriteCommand extends EventEmitter {
     exitCode(): number;
 }
 export declare class SpriteFilesystem {
+    #private;
     private readonly get;
+    private readonly cwd;
     private readonly files;
     constructor(get: () => Promise<Sandbox>, cwd?: string);
     readFile(path: string, encoding: "utf8"): Promise<string>;
@@ -203,6 +519,7 @@ export declare class SpriteFilesystem {
     rm(path: string, options?: {
         recursive?: boolean;
         force?: boolean;
+        asRoot?: boolean;
     }): Promise<void>;
     stat(path: string): Promise<{
         size: number;
@@ -214,13 +531,29 @@ export declare class SpriteFilesystem {
         isFile: () => boolean;
         isSymbolicLink: () => boolean;
     }>;
-    rename(from: string, to: string): Promise<void>;
+    rename(from: string, to: string, options?: {
+        asRoot?: boolean;
+    }): Promise<void>;
     copyFile(from: string, to: string, options?: {
         recursive?: boolean;
+        preserveAttrs?: boolean;
+        asRoot?: boolean;
     }): Promise<void>;
     chmod(path: string, mode: number, options?: {
         recursive?: boolean;
+        asRoot?: boolean;
     }): Promise<void>;
+    /** By number or name, as the Sprite's user unless `asRoot` (sudo). */
+    chown(path: string, options: {
+        uid?: number | string;
+        gid?: number | string;
+        recursive?: boolean;
+        asRoot?: boolean;
+    }): Promise<void>;
+    /** Changes to these paths until the watcher is closed. */
+    watch(paths: string | string[], options?: {
+        recursive?: boolean;
+    }): Promise<FilesystemWatcher>;
     exists(path: string): Promise<boolean>;
     appendFile(path: string, data: string | Uint8Array): Promise<void>;
     readJSON<T = unknown>(path: string): Promise<T>;
@@ -228,24 +561,3 @@ export declare class SpriteFilesystem {
         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>;
-}