withruntime 0.12.0 → 0.16.0

package/dist/modal/index.js

@@ -1,5 +1,5 @@
 import { ConflictError as NativeConflictError, InvalidRequestError, NotFoundError as NativeNotFoundError, RateLimitError, RuntimeError, ServiceUnavailableError, } from "../errors.js";
-import { all, client, CompatibilityError, create, destroy, execOptions, only, refuse, region, } from "../compat/core.js";
+import { all, client, CompatibilityError, create, destroy, execOptions, only, refuse, refusal, refused, region, } from "../compat/core.js";
 import { GuestFiles } from "../compat/files.js";
 export { CompatibilityError };
 // Errors ----------------------------------------------------------------------
@@ -104,6 +104,9 @@ export class App {
         this.environmentName = environmentName;
     }
 }
+refuse("Modal", "App", App, {
+    info: "a Runtime app is a label on its sandboxes, with no lifecycle, Functions or Servers: list them with client.sandboxes.list({ appId: app.appId })",
+});
 export class AppService {
     client;
     constructor(client) {
@@ -183,9 +186,11 @@ export class VolumeService {
     }
     async fromName(name, params = {}) {
         this.client.open();
-        only("Modal volume", params, ["createIfMissing", "environment"]);
+        only("Modal volume", params, ["createIfMissing", "environment", "version"]);
         if (params.environment)
             throw new CompatibilityError("Modal", "named Modal environments");
+        if (params.version !== undefined)
+            throw new CompatibilityError("Modal", "VolumeFS versions; a Runtime volume has one format, so omit version");
         const found = await this.find(name);
         if (found)
             return new Volume(found.id, name);
@@ -402,6 +407,21 @@ export class SandboxSnapshotService {
         return new SandboxSnapshot(snapshot.id);
     }
 }
+// Environments ------------------------------------------------------------------
+const NO_ENVIRONMENTS = "Runtime has no Modal environments: an account's sandboxes share one namespace, grouped by app name (client.apps.fromName) and tags";
+/** `client.environments` (modal 0.11.1): refused, as `environment` options are. */
+export class EnvironmentService {
+}
+refuse("Modal", "EnvironmentService", EnvironmentService, { fromName: NO_ENVIRONMENTS });
+Object.defineProperty(EnvironmentService.prototype, "objects", {
+    configurable: true,
+    get() {
+        throw refusal("Modal", "EnvironmentService.objects", NO_ENVIRONMENTS);
+    },
+});
+export const Environment = refused("Modal", "Environment", NO_ENVIRONMENTS);
+export const EnvironmentAppsService = refused("Modal", "EnvironmentAppsService", NO_ENVIRONMENTS);
+export const EnvironmentObjectsService = refused("Modal", "EnvironmentObjectsService", NO_ENVIRONMENTS);
 export class ModalClient {
     runtime;
     apps;
@@ -412,6 +432,7 @@ export class ModalClient {
     cloudBucketMounts = new CloudBucketMountService();
     sandboxSnapshots;
     proxies = new ProxyService();
+    environments = new EnvironmentService();
     #closed = false;
     constructor(options = {}) {
         if (options.endpoint !== undefined ||
@@ -458,7 +479,7 @@ export class ModalClient {
     }
     /** The Modal SDK version whose interface this adapter implements. */
     version() {
-        return "0.11.0";
+        return "0.11.1";
     }
     close() {
         // The transport owns no background connection; later calls fail as Modal's do.
@@ -619,14 +640,21 @@ export class SandboxService {
             throw new NotFoundError("Sandbox is not a Modal-compatible sandbox");
         return new Sandbox(s, new ContainerProcess(await modal(() => s.processes.get(p)), "text"), this.client);
     }
+    /** The running sandbox of that name; with includeTerminated, when none
+     * runs, the one that stopped last (modal 0.11.1). */
     async fromName(appName, name, params = {}) {
         this.client?.open();
-        only("Modal sandbox name", params, ["environment"]);
+        only("Modal sandbox name", params, ["environment", "includeTerminated"]);
         if (params.environment)
             throw new CompatibilityError("Modal", ENVIRONMENTS);
-        const s = (await all(this.runtime, "modal")).find((s) => s.info.labels["modal.app"] === appName &&
-            s.info.labels["modal.name"] === name &&
-            s.state === "running");
+        const named = (await all(this.runtime, "modal")).filter((s) => s.info.labels["modal.app"] === appName && s.info.labels["modal.name"] === name);
+        const ended = (s) => s.info.endedAt ?? s.info.createdAt ?? "";
+        const s = named.find((s) => s.state === "running") ??
+            (params.includeTerminated
+                ? named
+                    .filter((s) => s.state === "stopped")
+                    .sort((a, b) => ended(b).localeCompare(ended(a)))[0]
+                : undefined);
         if (!s)
             throw new NotFoundError(`Sandbox ${name} not found`);
         return this.fromId(s.id);

package/dist/morph/index.d.ts

@@ -0,0 +1,255 @@
+import type { Runtime } from "../client.js";
+import type { Preview } from "../products/previews.js";
+import { Sandbox } from "../sandbox.js";
+import type { Snapshot as NativeSnapshot } from "../snapshots.js";
+import { CompatibilityError, type ClientOptions, type RefusedAsync } from "../compat/core.js";
+export { CompatibilityError };
+/** Morph's base image; on Runtime, the default image. */
+export declare const MORPH_DEFAULT_IMAGE = "morphvm-minimal";
+export declare enum SnapshotStatus {
+    PENDING = "pending",
+    READY = "ready",
+    FAILED = "failed",
+    DELETING = "deleting",
+    DELETED = "deleted"
+}
+export declare enum InstanceStatus {
+    PENDING = "pending",
+    READY = "ready",
+    PAUSED = "paused",
+    SAVING = "saving",
+    ERROR = "error"
+}
+export interface ResourceSpec {
+    vcpus: number;
+    /** MiB. */
+    memory: number;
+    /** MiB. */
+    diskSize: number;
+}
+export interface SnapshotRefs {
+    imageId: string;
+}
+export interface InstanceHttpService {
+    name: string;
+    port: number;
+    url: string;
+}
+export interface InstanceNetworking {
+    internalIp?: string;
+    httpServices: InstanceHttpService[];
+    auth_mode?: string;
+}
+export interface InstanceRefs {
+    snapshotId: string;
+    imageId: string;
+}
+export interface InstanceExecResponse {
+    exit_code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface InstanceTTL {
+    ttlSeconds?: number;
+    ttlExpireAt?: number;
+    ttlAction?: "stop" | "pause";
+}
+export interface InstanceWakeOn {
+    wakeOnSsh?: boolean;
+    wakeOnHttp?: boolean;
+}
+export interface ExecOptions {
+    /** Seconds; default 24 hours, as Morph's. */
+    timeout?: number;
+    onStdout?: (content: string) => void;
+    onStderr?: (content: string) => void;
+}
+export interface InstanceSshKey {
+    object: "instance_ssh_key";
+    private_key: string;
+    public_key: string;
+    password: string;
+}
+export interface MorphCloudClientOptions extends ClientOptions {
+    /** A Runtime key (`rtcloud_...`); a Morph key is never sent anywhere. */
+    apiKey?: string;
+    baseUrl?: string;
+    verbose?: boolean;
+}
+export type ImageListOptions = Record<string, never>;
+export interface SnapshotListOptions {
+    digest?: string;
+    metadata?: Record<string, string>;
+}
+export interface SnapshotCreateOptions {
+    imageId?: string;
+    vcpus?: number;
+    memory?: number;
+    diskSize?: number;
+    digest?: string;
+    metadata?: Record<string, string>;
+}
+export interface SnapshotGetOptions {
+    snapshotId: string;
+}
+export interface InstanceListOptions {
+    metadata?: Record<string, string>;
+}
+export interface InstanceStartOptions {
+    snapshotId: string;
+    metadata?: Record<string, string>;
+    ttlSeconds?: number;
+    ttlAction?: "stop" | "pause";
+    /** Seconds to wait until it runs. */
+    timeout?: number;
+}
+export interface InstanceSnapshotOptions {
+    digest?: string;
+    metadata?: Record<string, string>;
+}
+export interface InstanceGetOptions {
+    instanceId: string;
+}
+export interface InstanceStopOptions {
+    instanceId: string;
+}
+export interface InstanceBootOptions {
+    snapshotId: string;
+    vcpus?: number;
+    memory?: number;
+    diskSize?: number;
+    metadata?: Record<string, string>;
+    ttlSeconds?: number;
+    ttlAction?: "stop" | "pause";
+}
+export interface SyncOptions {
+    delete?: boolean;
+    dryRun?: boolean;
+    verbose?: boolean;
+    respectGitignore?: boolean;
+}
+export declare class Image {
+    readonly id: string;
+    readonly name: string;
+    readonly diskSize: number;
+    readonly created: number;
+    readonly description?: string | undefined;
+    readonly object: "image";
+    constructor(id: string, name: string, diskSize: number, created: number, description?: string | undefined);
+}
+export declare class Snapshot {
+    #private;
+    readonly native: NativeSnapshot;
+    readonly id: string;
+    readonly object: "snapshot";
+    readonly created: number;
+    readonly status: SnapshotStatus;
+    readonly spec: ResourceSpec;
+    readonly refs: SnapshotRefs;
+    readonly digest?: string;
+    metadata?: Record<string, string>;
+    constructor(native: NativeSnapshot, morph: MorphCloudClient);
+    delete(): Promise<void>;
+    /** Morph's chain hash: SHA-256 of the parent's hash, a newline and the effect. */
+    static computeChainHash(parentChainHash: string, effectIdentifier: string): string;
+    /** Runs `command` on a copy of this snapshot and snapshots the result, once:
+     * a later setup of the same command on the same snapshot answers the
+     * snapshot made the first time. A command that fails throws, and the copy
+     * is stopped either way. */
+    setup(command: string): Promise<Snapshot>;
+    /** Adds or changes these metadata keys; the others stay. */
+    setMetadata(metadata: Record<string, string>): Promise<void>;
+}
+export declare class Instance {
+    #private;
+    readonly id: string;
+    readonly object: "instance";
+    readonly created: number;
+    status: InstanceStatus;
+    readonly spec: ResourceSpec;
+    readonly refs: InstanceRefs;
+    networking: InstanceNetworking;
+    ttl: InstanceTTL;
+    wakeOn: InstanceWakeOn;
+    metadata?: Record<string, string>;
+    readonly ssh: RefusedAsync;
+    readonly sshKey: RefusedAsync;
+    readonly sshKeyRotate: RefusedAsync;
+    readonly reboot: RefusedAsync;
+    readonly setTTL: RefusedAsync;
+    constructor(sandbox: Sandbox, morph: MorphCloudClient, previews?: Preview[]);
+    /** The Runtime sandbox behind it, for what Morph has no call for. */
+    get native(): Sandbox;
+    /** Deletes it, with its disk and memory, as Morph's stop does; its snapshots stay. */
+    stop(): Promise<void>;
+    /** Keeps memory and disk, and stops compute charges. */
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    /** Adds or changes these metadata keys; the others stay. */
+    setMetadata(metadata: Record<string, string>): Promise<void>;
+    /** Runtime wakes a paused sandbox on any request (an API call, SSH, a
+     * visit to a shared port) or on none: both values must agree. */
+    setWakeOn(wakeOnSsh?: boolean, wakeOnHttp?: boolean): Promise<void>;
+    /** Files, memory and running processes; a running instance pauses for the
+     * moment it takes, then runs on. */
+    snapshot(options?: InstanceSnapshotOptions): Promise<Snapshot>;
+    /** `count` running copies, with its files, memory and processes, and the
+     * snapshot they were started from, which is kept. */
+    branch(count: number): Promise<{
+        snapshot: Snapshot;
+        instances: Instance[];
+    }>;
+    /** Shares `port` at an HTTPS address. With no auth_mode, anyone with the
+     * address reaches it (Runtime's public preview, which needs a kept
+     * top-up); with auth_mode "api_key", a request needs the preview's token
+     * in `x-runtime-preview-token` (native.previews.get(port)). */
+    exposeHttpService(name: string, port: number, auth_mode?: string): Promise<InstanceHttpService>;
+    hideHttpService(name: string): Promise<void>;
+    /** A string, or a one-item array, runs in a shell; a longer array runs as
+     * its arguments. Output streams to onStdout and onStderr as it comes. */
+    exec(command: string | string[], options?: ExecOptions): Promise<InstanceExecResponse>;
+    /** Seconds; waits until it runs, waking it if paused. */
+    waitUntilReady(timeout?: number): Promise<void>;
+    /** Copies a local file or folder into the instance, or out of it: the
+     * instance's side is written `<instance id>:<path>`. Without delete, dry
+     * runs or .gitignore, which refuse. */
+    sync(source: string, dest: string, options?: SyncOptions): Promise<void>;
+}
+/** Morph's client, on Runtime. `new MorphCloudClient()` reads RUNTIME_API_KEY
+ * (or a saved login), never MORPH_API_KEY. */
+export declare class MorphCloudClient {
+    readonly runtime: Runtime;
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly verbose: boolean;
+    readonly GET: RefusedAsync;
+    readonly POST: RefusedAsync;
+    readonly streamPOST: RefusedAsync;
+    readonly DELETE: RefusedAsync;
+    constructor(options?: MorphCloudClientOptions);
+    images: {
+        /** Morph's base image, which is Runtime's default image. Build others with runtime.images. */
+        list: (_options?: ImageListOptions) => Promise<Image[]>;
+    };
+    snapshots: {
+        list: (options?: SnapshotListOptions) => Promise<Snapshot[]>;
+        /** A bootable snapshot of an image at a size: Runtime boots a sandbox from
+         * the image, snapshots its disk and stops it. With a digest, a snapshot
+         * already made with it is answered instead. */
+        create: (options?: SnapshotCreateOptions) => Promise<Snapshot>;
+        get: (options: SnapshotGetOptions) => Promise<Snapshot>;
+    };
+    instances: {
+        /** Running and paused instances whose metadata match. */
+        list: (options?: InstanceListOptions) => Promise<Instance[]>;
+        /** A running copy of a snapshot: files, and memory and processes when the
+         * snapshot kept them. */
+        start: (options: InstanceStartOptions) => Promise<Instance>;
+        /** As start; a different vcpus or memory restarts it at that size (its
+         * files kept, its programs started afresh). The disk keeps the snapshot's size. */
+        boot: (options: InstanceBootOptions) => Promise<Instance>;
+        get: (options: InstanceGetOptions) => Promise<Instance>;
+        /** Deletes it, with its disk and memory, as Morph's stop does; its snapshots stay. */
+        stop: (options: InstanceStopOptions) => Promise<void>;
+    };
+}