withruntime 0.11.1 → 0.12.0

package/dist/client.d.ts

@@ -1,11 +1,12 @@
-import { RuntimeError } from "./errors.js";
-import type { Page } from "./page.js";
 import { type ClientExtensions } from "./products/index.js";
+import { type RenamedProducts } from "./renamed-products.js";
 import { usageExport as makeUsageExport } from "./products/observability.js";
+import { Machines } from "./machine.js";
 import { Sandbox } from "./sandbox.js";
 import { Snapshots } from "./snapshots.js";
 import { Transport, type RequestOptions } from "./transport.js";
 import type { CreateSandbox, DeletedSandbox, FeedbackKind, SandboxInfo, Usage } from "./types.js";
+export type { CreateOptions } from "./machine.js";
 export type RuntimeOptions = {
     /** Default: the RUNTIME_API_KEY environment variable. */
     apiKey?: string;
@@ -22,23 +23,23 @@ export type RuntimeOptions = {
      * before it has used a valid key. 8 are kept for calls whatever the
      * streams hold. */
     maxConnections?: number;
+    /** Called each time a call has to wait for one of those connections: an
+     * adapter warns with it, once, that its caller is being held back. */
+    onQueued?: (maxConnections: number) => void;
     /** How long `sandboxes.create` keeps retrying, with the same key and input,
-     * when the trial's slots, the account's quota or the region is full
-     * (trial_busy, quota_exceeded, no_capacity and the like). Default 120 000
+     * when the slots without credit, the account's quota or the region is full
+     * (no_credit_running_limit, quota_exceeded, no_capacity and the like). Default 120 000
      * (two minutes); 0 fails at once. The refusal is thrown as it came when the
      * wait runs out. */
     waitForCapacityMs?: number;
 };
 /** One client for every Runtime Cloud product. Create it once and reuse it:
  * it keeps its connections open. */
-export interface Runtime extends ClientExtensions {
+export interface Runtime extends ClientExtensions, RenamedProducts {
 }
 export declare class Runtime {
     readonly transport: Transport;
-    /** The sandbox product; `sandboxes` remains the same client for compatibility. */
-    readonly sandbox: Sandboxes;
     readonly sandboxes: Sandboxes;
-    readonly snapshot: Snapshots;
     readonly snapshots: Snapshots;
     readonly feedback: FeedbackApi;
     readonly support: SupportApi;
@@ -57,8 +58,8 @@ export declare class Runtime {
         /** The role of the member who made this key: owner, admin, developer or billing. */
         role?: string | null;
     }>;
-    /** Balance, holds, trial time and per-resource charges, in integer microdollars. */
-    /** Credit, holds, trial time and per-resource charges. */
+    /** Balance, holds, free time and per-resource charges, in integer microdollars. */
+    /** Credit, holds, free time and per-resource charges. */
     usage(options?: RequestOptions): Promise<Usage>;
     /** This account's authenticated API answers, in hourly windows. Counts are
      * exact decimal strings, and an empty window has a null error percentage.
@@ -80,60 +81,9 @@ export declare class Runtime {
         }>;
     }>;
 }
-/** How `sandboxes.create` waits when every trial slot, the account's quota or
- * the region is full. */
-export type CreateOptions = RequestOptions & {
-    /** How long to keep retrying a refusal that clears by itself. Default: the
-     * client's, two minutes; 0 fails at once. */
-    waitForCapacityMs?: number;
-    /** Called before each wait, with the refusal and the milliseconds until the
-     * next try: to tell a person why nothing has happened yet. */
-    onCapacityWait?: (refusal: RuntimeError, waitMs: number) => void;
-};
-export declare class Sandboxes {
-    private readonly t;
+/** `runtime.sandboxes`: the sandbox product of the machine engine. */
+export declare class Sandboxes extends Machines<Sandbox, SandboxInfo, CreateSandbox, DeletedSandbox> {
     constructor(t: Transport);
-    /** Creates a sandbox and waits until it is running. Every field is optional:
-     * with none you get the free trial while it lasts, the default region and a
-     * 2 vCPU / 4 GiB machine from a warm template. `wait: false` returns at once.
-     * When every trial slot or the account's quota is taken, it waits for one to
-     * free, up to `waitForCapacityMs` (the client's, two minutes by default). */
-    create(input?: CreateSandbox & {
-        wait?: boolean;
-    }, options?: CreateOptions): Promise<Sandbox>;
-    /** The sandbox named `name` in this account, ready to use: running as it
-     * is, woken if it is paused, restarted if it is stopped and persistent, or
-     * created with `input` when no sandbox has the name. `sandbox.info.reused`
-     * says which. The other fields apply only when it is created. */
-    getOrCreate(name: string, input?: Omit<CreateSandbox, "name" | "getOrCreate"> & {
-        wait?: boolean;
-    }, options?: CreateOptions): Promise<Sandbox>;
-    get(id: string, options?: RequestOptions): Promise<Sandbox>;
-    /** Deletes a sandbox for good, by id, without reading it first: see
-     * `sandbox.delete()`. Deleting it again answers the same. */
-    delete(id: string, options?: RequestOptions): Promise<DeletedSandbox>;
-    /** Live sandboxes, oldest first. Await for a page, or `for await` over all.
-     * Request options apply to the initial request and every subsequent page. */
-    list(filter?: {
-        state?: SandboxInfo["state"][];
-        includeStopped?: boolean;
-        /** Every label must match. */
-        labels?: Record<string, string>;
-        name?: string;
-        limit?: number;
-    }, options?: RequestOptions): Promise<Page<Sandbox>>;
-    /** Stops every live sandbox whose labels all match, eight at a time, and
-     * says which stopped and which failed; one failure does not stop the rest.
-     * Needs at least one label, so stopping everything is never one call. */
-    stopAll(filter: {
-        labels: Record<string, string>;
-    }, options?: RequestOptions): Promise<{
-        stopped: string[];
-        failed: {
-            id: string;
-            error: unknown;
-        }[];
-    }>;
 }
 export declare class FeedbackApi {
     private readonly t;

package/dist/client.js

@@ -1,10 +1,12 @@
-import { WAIT_FOR_TIMEOUT_SECONDS } from "./api-defaults.js";
-import { RuntimeError } from "./errors.js";
-import { clientFactories, clientProductAliases } from "./products/index.js";
+import { clientFactories } from "./products/index.js";
+import { installRenamedProducts } from "./renamed-products.js";
 import { usageExport as makeUsageExport } from "./products/observability.js";
-import { Sandbox, deleteSandbox, sandboxPage } from "./sandbox.js";
+import { Machines } from "./machine.js";
+import { SANDBOXES, Sandbox } from "./sandbox.js";
 import { Snapshots } from "./snapshots.js";
-import { DEFAULT_BASE_URL, Transport, missingKey } from "./transport.js";
+import { DEFAULT_BASE_URL, Transport, missingKey, sayRenamed, } from "./transport.js";
+import { RuntimeError } from "./errors.js";
+import { RENAMED_FIELDS, fieldUse } from "./product-renames.js";
 /** The key `runtime login` saved for this machine and this API origin, found
  * on first use. A constructor override must never receive another API's key. */
 const savedKey = async (apiOrigin) => {
@@ -19,10 +21,7 @@ const env = (name) => typeof process === "undefined"
 // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class Runtime {
     transport;
-    /** The sandbox product; `sandboxes` remains the same client for compatibility. */
-    sandbox;
     sandboxes;
-    snapshot;
     snapshots;
     feedback;
     support;
@@ -43,22 +42,20 @@ export class Runtime {
             ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
             ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
             ...(options.maxConnections !== undefined ? { maxConnections: options.maxConnections } : {}),
+            ...(options.onQueued ? { onQueued: options.onQueued } : {}),
             ...(options.waitForCapacityMs !== undefined
                 ? { waitForCapacityMs: options.waitForCapacityMs }
                 : {}),
         });
         this.sandboxes = new Sandboxes(this.transport);
-        this.sandbox = this.sandboxes;
         this.snapshots = new Snapshots(this.transport);
-        this.snapshot = this.snapshots;
         this.feedback = new FeedbackApi(this.transport);
         this.support = new SupportApi(this.transport);
         this.account = new AccountApi(this.transport);
         this.usageExport = makeUsageExport(this.transport);
         for (const [name, make] of clientFactories())
             Object.defineProperty(this, name, { value: make(this.transport), enumerable: true });
-        for (const [alias, name] of Object.entries(clientProductAliases))
-            Object.defineProperty(this, alias, { value: this[name], enumerable: true });
+        installRenamedProducts(this);
     }
     /** Who this key is: organization, agent and credential. */
     me(options = {}) {
@@ -68,14 +65,33 @@ export class Runtime {
             ...options,
         });
     }
-    /** Balance, holds, trial time and per-resource charges, in integer microdollars. */
-    /** Credit, holds, trial time and per-resource charges. */
-    usage(options = {}) {
-        return this.transport.json({
+    /** Balance, holds, free time and per-resource charges, in integer microdollars. */
+    /** Credit, holds, free time and per-resource charges. */
+    async usage(options = {}) {
+        const value = await this.transport.json({
             method: "GET",
             path: "/v1/usage",
             ...options,
         });
+        const fields = value;
+        for (const field of RENAMED_FIELDS) {
+            // An older server only sends the old name. Preserve its value before
+            // replacing that property with the warning getter.
+            if (!(field.now in fields) && field.name in fields)
+                fields[field.now] = fields[field.name];
+            Object.defineProperty(value, field.name, {
+                configurable: true,
+                enumerable: false,
+                get() {
+                    const use = fieldUse(field.name);
+                    if (use.kind === "retired")
+                        throw new RuntimeError({ ...use.error });
+                    sayRenamed(`299 runtime "${use.warning.replaceAll('"', "'")}"`);
+                    return fields[field.now];
+                },
+            });
+        }
+        return value;
     }
     /** This account's authenticated API answers, in hourly windows. Counts are
      * exact decimal strings, and an empty window has a null error percentage.
@@ -89,115 +105,10 @@ export class Runtime {
         });
     }
 }
-export class Sandboxes {
-    t;
+/** `runtime.sandboxes`: the sandbox product of the machine engine. */
+export class Sandboxes extends Machines {
     constructor(t) {
-        this.t = t;
-    }
-    /** Creates a sandbox and waits until it is running. Every field is optional:
-     * with none you get the free trial while it lasts, the default region and a
-     * 2 vCPU / 4 GiB machine from a warm template. `wait: false` returns at once.
-     * When every trial slot or the account's quota is taken, it waits for one to
-     * free, up to `waitForCapacityMs` (the client's, two minutes by default). */
-    async create(input = {}, options = {}) {
-        const { wait, ...body } = input;
-        const began = performance.now();
-        // Time spent waiting for capacity is the room's, not the deadline's.
-        let waited = 0;
-        const info = await this.t.json({
-            method: "POST",
-            path: "/v1/sandboxes",
-            body,
-            wait: wait === false ? 0 : 60,
-            ...options,
-            waitForCapacityMs: options.waitForCapacityMs ?? this.t.waitForCapacityMs,
-            onCapacityWait: (refusal, waitMs) => {
-                waited += waitMs;
-                options.onCapacityWait?.(refusal, waitMs);
-            },
-        });
-        const sandbox = new Sandbox(this.t, info);
-        if (wait !== false && info.state !== "running") {
-            // One deadline for the whole create: the wait for running gets what the
-            // create left of it (1 ms when nothing is left, so it ends as a timeout).
-            const { timeoutMs } = options;
-            await sandbox.waitFor("running", {
-                timeoutSeconds: WAIT_FOR_TIMEOUT_SECONDS,
-                signal: options.signal,
-                timeoutMs: timeoutMs
-                    ? Math.max(1, Math.ceil(timeoutMs - (performance.now() - began - waited)))
-                    : timeoutMs,
-                idempotencyKey: options.idempotencyKey,
-            });
-            if (sandbox.state !== "running")
-                throw new RuntimeError({
-                    message: `Sandbox ${info.id} is ${sandbox.state}, not running.`,
-                    code: "start_failed",
-                    status: 0,
-                    hint: "Read it with runtime.sandboxes.get(id); stopReason says why.",
-                });
-        }
-        return sandbox;
-    }
-    /** The sandbox named `name` in this account, ready to use: running as it
-     * is, woken if it is paused, restarted if it is stopped and persistent, or
-     * created with `input` when no sandbox has the name. `sandbox.info.reused`
-     * says which. The other fields apply only when it is created. */
-    async getOrCreate(name, input = {}, options = {}) {
-        return this.create({ ...input, name, getOrCreate: true }, options);
-    }
-    async get(id, options = {}) {
-        return new Sandbox(this.t, await this.t.json({
-            method: "GET",
-            path: `/v1/sandboxes/${encodeURIComponent(id)}`,
-            ...options,
-        }));
-    }
-    /** Deletes a sandbox for good, by id, without reading it first: see
-     * `sandbox.delete()`. Deleting it again answers the same. */
-    delete(id, options = {}) {
-        return deleteSandbox(this.t, id, options);
-    }
-    /** Live sandboxes, oldest first. Await for a page, or `for await` over all.
-     * Request options apply to the initial request and every subsequent page. */
-    async list(filter = {}, options = {}) {
-        const query = {
-            ...(filter.state ? { state: filter.state } : {}),
-            ...(filter.includeStopped ? { includeStopped: true } : {}),
-            ...(filter.labels
-                ? { label: Object.entries(filter.labels).map(([k, v]) => `${k}:${v}`) }
-                : {}),
-            ...(filter.name ? { name: filter.name } : {}),
-            ...(filter.limit ? { limit: filter.limit } : {}),
-        };
-        return sandboxPage(this.t, await this.t.json({ method: "GET", path: "/v1/sandboxes", query, ...options }), query, options);
-    }
-    /** Stops every live sandbox whose labels all match, eight at a time, and
-     * says which stopped and which failed; one failure does not stop the rest.
-     * Needs at least one label, so stopping everything is never one call. */
-    async stopAll(filter, options = {}) {
-        if (!filter?.labels || Object.keys(filter.labels).length === 0)
-            throw new RuntimeError({
-                message: "stopAll needs at least one label to match.",
-                code: "invalid_request",
-                status: 0,
-                hint: "Stop one sandbox with sandbox.stop(), or label the ones to stop together.",
-            });
-        const live = await (await this.list({ labels: filter.labels, limit: 100 }, options)).toArray(Infinity);
-        // One key cannot name several stops: each stop makes its own.
-        const { idempotencyKey: _one, ...each } = options;
-        // In list order, oldest first, whichever finishes first.
-        const errors = new Array(live.length);
-        let next = 0;
-        const worker = async () => {
-            for (let at = next++; at < live.length; at = next++)
-                await live[at].stop(each).catch((error) => (errors[at] = error ?? "failed"));
-        };
-        await Promise.all(Array.from({ length: Math.min(8, live.length) }, worker));
-        return {
-            stopped: live.filter((_, at) => errors[at] === undefined).map((sbx) => sbx.id),
-            failed: live.flatMap((sbx, at) => errors[at] === undefined ? [] : [{ id: sbx.id, error: errors[at] }]),
-        };
+        super(SANDBOXES, t, (transport, info) => new Sandbox(transport, info));
     }
 }
 export class FeedbackApi {

package/dist/cloudflare/errors.d.ts

@@ -0,0 +1,143 @@
+/** Cloudflare's exported error classes, with its fields, so a caller's
+ * `instanceof` and `error.code` keep working. The adapter throws them where
+ * Cloudflare would: a process that never becomes ready, a bucket that will
+ * not mount or unmount. */
+export type ErrorResponse<TContext = Record<string, unknown>> = {
+    code: string;
+    message: string;
+    operation?: string;
+    context: TContext;
+    httpStatus: number;
+    timestamp: string;
+    suggestion?: string;
+    documentation?: string;
+};
+declare class SandboxError<TContext = Record<string, unknown>> extends Error {
+    readonly errorResponse: ErrorResponse<TContext>;
+    constructor(errorResponse: ErrorResponse<TContext>, options?: {
+        cause?: unknown;
+    });
+    get code(): string;
+    get context(): TContext;
+    get httpStatus(): number;
+    get operation(): string | undefined;
+    get suggestion(): string | undefined;
+    get timestamp(): string;
+    get documentation(): string | undefined;
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        context: TContext;
+        httpStatus: number;
+        operation: string | undefined;
+        suggestion: string | undefined;
+        timestamp: string;
+        documentation: string | undefined;
+        stack: string | undefined;
+    };
+}
+export { SandboxError };
+export declare class SessionTerminatedError extends SandboxError<{
+    sessionId: string;
+    exitCode: number | null;
+}> {
+    get sessionId(): string;
+    get exitCode(): number | null;
+}
+type ReadyContext = {
+    processId: string;
+    command: string;
+    condition: string;
+};
+export declare class ProcessReadyTimeoutError extends SandboxError<ReadyContext & {
+    timeout: number;
+}> {
+    get processId(): string;
+    get command(): string;
+    get condition(): string;
+    get timeout(): number;
+}
+export declare class ProcessExitedBeforeReadyError extends SandboxError<ReadyContext & {
+    exitCode: number;
+}> {
+    get processId(): string;
+    get command(): string;
+    get condition(): string;
+    get exitCode(): number;
+}
+export declare class BackupNotFoundError extends SandboxError<{
+    backupId: string;
+}> {
+    get backupId(): string;
+}
+export declare class BackupExpiredError extends SandboxError<{
+    backupId: string;
+    expiredAt?: string;
+}> {
+    get backupId(): string;
+    get expiredAt(): string | undefined;
+}
+export declare class InvalidBackupConfigError extends SandboxError<{
+    reason: string;
+}> {
+    get reason(): string;
+}
+export declare class BackupCreateError extends SandboxError<{
+    dir: string;
+    backupId?: string;
+    stderr?: string;
+    exitCode?: number;
+}> {
+    get dir(): string;
+    get backupId(): string | undefined;
+}
+export declare class BackupRestoreError extends SandboxError<{
+    dir: string;
+    backupId: string;
+    stderr?: string;
+    exitCode?: number;
+}> {
+    get dir(): string;
+    get backupId(): string;
+}
+export declare class ContainerUnavailableError extends SandboxError<{
+    reason: string;
+    retryable: true;
+    retryAfterMs?: number;
+    originalMessage?: string;
+}> {
+    get reason(): string;
+    get retryAfterMs(): number | undefined;
+}
+export declare class OperationInterruptedError extends SandboxError<{
+    reason: string;
+    operation: string;
+    phase: string;
+    admitted: boolean | "unknown";
+    retryable: boolean;
+}> {
+    get reason(): string;
+}
+export declare class BucketMountError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+export declare class S3FSMountError extends BucketMountError {
+    constructor(message: string);
+}
+export declare class BucketUnmountError extends BucketMountError {
+    constructor(message: string);
+}
+export declare class MissingCredentialsError extends BucketMountError {
+    constructor(message: string);
+}
+export declare class InvalidMountConfigError extends BucketMountError {
+    constructor(message: string);
+}
+/** An ErrorResponse as the container would send it. */
+export declare function response<TContext>(code: string, message: string, context: TContext, extra?: {
+    httpStatus?: number;
+    operation?: string;
+    suggestion?: string;
+}): ErrorResponse<TContext>;

package/dist/cloudflare/errors.js

@@ -0,0 +1,167 @@
+class SandboxError extends Error {
+    errorResponse;
+    constructor(errorResponse, options) {
+        super(errorResponse.message, options);
+        this.name = new.target.name;
+        this.errorResponse = errorResponse;
+    }
+    get code() {
+        return this.errorResponse.code;
+    }
+    get context() {
+        return this.errorResponse.context;
+    }
+    get httpStatus() {
+        return this.errorResponse.httpStatus;
+    }
+    get operation() {
+        return this.errorResponse.operation;
+    }
+    get suggestion() {
+        return this.errorResponse.suggestion;
+    }
+    get timestamp() {
+        return this.errorResponse.timestamp;
+    }
+    get documentation() {
+        return this.errorResponse.documentation;
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            context: this.context,
+            httpStatus: this.httpStatus,
+            operation: this.operation,
+            suggestion: this.suggestion,
+            timestamp: this.timestamp,
+            documentation: this.documentation,
+            stack: this.stack,
+        };
+    }
+}
+export { SandboxError };
+export class SessionTerminatedError extends SandboxError {
+    get sessionId() {
+        return this.context.sessionId;
+    }
+    get exitCode() {
+        return this.context.exitCode;
+    }
+}
+export class ProcessReadyTimeoutError extends SandboxError {
+    get processId() {
+        return this.context.processId;
+    }
+    get command() {
+        return this.context.command;
+    }
+    get condition() {
+        return this.context.condition;
+    }
+    get timeout() {
+        return this.context.timeout;
+    }
+}
+export class ProcessExitedBeforeReadyError extends SandboxError {
+    get processId() {
+        return this.context.processId;
+    }
+    get command() {
+        return this.context.command;
+    }
+    get condition() {
+        return this.context.condition;
+    }
+    get exitCode() {
+        return this.context.exitCode;
+    }
+}
+export class BackupNotFoundError extends SandboxError {
+    get backupId() {
+        return this.context.backupId;
+    }
+}
+export class BackupExpiredError extends SandboxError {
+    get backupId() {
+        return this.context.backupId;
+    }
+    get expiredAt() {
+        return this.context.expiredAt;
+    }
+}
+export class InvalidBackupConfigError extends SandboxError {
+    get reason() {
+        return this.context.reason;
+    }
+}
+export class BackupCreateError extends SandboxError {
+    get dir() {
+        return this.context.dir;
+    }
+    get backupId() {
+        return this.context.backupId;
+    }
+}
+export class BackupRestoreError extends SandboxError {
+    get dir() {
+        return this.context.dir;
+    }
+    get backupId() {
+        return this.context.backupId;
+    }
+}
+export class ContainerUnavailableError extends SandboxError {
+    get reason() {
+        return this.context.reason;
+    }
+    get retryAfterMs() {
+        return this.context.retryAfterMs;
+    }
+}
+export class OperationInterruptedError extends SandboxError {
+    get reason() {
+        return this.context.reason;
+    }
+}
+export class BucketMountError extends Error {
+    code;
+    constructor(message, code = "BUCKET_MOUNT_ERROR") {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+    }
+}
+export class S3FSMountError extends BucketMountError {
+    constructor(message) {
+        super(message, "S3FS_MOUNT_ERROR");
+    }
+}
+export class BucketUnmountError extends BucketMountError {
+    constructor(message) {
+        super(message, "BUCKET_UNMOUNT_ERROR");
+    }
+}
+export class MissingCredentialsError extends BucketMountError {
+    constructor(message) {
+        super(message, "MISSING_CREDENTIALS");
+    }
+}
+export class InvalidMountConfigError extends BucketMountError {
+    constructor(message) {
+        super(message, "INVALID_MOUNT_CONFIG");
+    }
+}
+/** An ErrorResponse as the container would send it. */
+export function response(code, message, context, extra = {}) {
+    return {
+        code,
+        message,
+        context,
+        httpStatus: extra.httpStatus ?? 500,
+        timestamp: new Date().toISOString(),
+        ...(extra.operation ? { operation: extra.operation } : {}),
+        ...(extra.suggestion ? { suggestion: extra.suggestion } : {}),
+    };
+}