@aerol-ai/aerolvm-sdk 0.7.0 → 0.8.1

package/dist/MicroVM.d.ts

@@ -1,7 +1,7 @@
 import { type APIVersion, type RetryConfig } from "./internal/client.js";
 import { Sandbox } from "./Sandbox.js";
 import { Image } from "./Image.js";
-import type { APITokenList, BuildImageOptions, BuildImageResult, CloneGeneration, CreateAPITokenOptions, CreatedAPIToken, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, ExecStreamHandle, ExecStreamOptions, HealthStatus, EgressProfile, EgressProfileList, EgressProfileOptions, ListEgressProfilesOptions, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, IngressTarget, Lifecycle, GetOptions, ListOptions, MountSpecRedacted, RegisterSnapshotOptions, ListSnapshotsOptions, SnapshotList, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule, WhoAmI } from "./types.js";
+import type { APITokenList, BuildImageOptions, BuildImageResult, CloneGeneration, CreateAPITokenOptions, CreatedAPIToken, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, ExecStreamHandle, ExecStreamOptions, HealthStatus, EgressProfile, EgressProfileList, EgressProfileOptions, ListEgressProfilesOptions, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, IngressTarget, Lifecycle, GetOptions, ListOptions, MountSpecRedacted, CreateSnapshotOptions, RegisterSnapshotOptions, ListSnapshotsOptions, SnapshotList, ResizeOptions, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule, WhoAmI } from "./types.js";
 type FetchLike = typeof fetch;
 /** Scoped API token calls, reached as `microvm.tokens`. */
 export interface Tokens {
@@ -85,7 +85,7 @@ export declare class MicroVM {
     getByName(name: string, options?: GetOptions): Promise<Sandbox | null>;
     start(id: string): Promise<Sandbox>;
     stop(id: string): Promise<Sandbox>;
-    createSnapshot(id: string, name: string): Promise<SandboxSnapshot>;
+    createSnapshot(id: string, name: string, options?: CreateSnapshotOptions): Promise<SandboxSnapshot>;
     registerSnapshot(options: RegisterSnapshotOptions): Promise<SandboxSnapshot>;
     registerSnapshotFromImage(name: string, image: Image, options?: Omit<RegisterSnapshotOptions, "name" | "image" | "dockerfileContent">): Promise<SandboxSnapshot>;
     /** Look a snapshot up by name. In a cluster the request is routed to the node holding the image. */

package/dist/MicroVM.js

@@ -66,8 +66,8 @@ export class MicroVM {
         const sandbox = await this.client.stop(id);
         return this.wrap(sandbox.toJSON());
     }
-    async createSnapshot(id, name) {
-        return this.client.createSnapshot(id, name);
+    async createSnapshot(id, name, options = {}) {
+        return this.client.createSnapshot(id, name, options);
     }
     async registerSnapshot(options) {
         return this.client.registerSnapshot(options);

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * An HTTP error response from the AerolVM server. `message` is the server's
+ * message, or `request failed with status N` when the body carries none (a
+ * proxy's HTML error page, say): the same text the SDK threw before this
+ * class existed, so code that printed or matched it sees no change.
+ *
+ * Branch on `code`, not on `message`: the code is a stable identifier, the
+ * message is wording for a person.
+ */
+export declare class MicroVMApiError extends Error {
+    /** The HTTP status of the final attempt, such as 422 or 503. */
+    readonly status: number;
+    /**
+     * The server's stable error code, such as `"idempotency_key_reused"` or
+     * `"overloaded"`. Undefined when the response has none: many errors are
+     * only ever shown to a person, and a proxy's error page has no code.
+     */
+    readonly code: string | undefined;
+    /**
+     * How long the response's `Retry-After` header asked the caller to wait,
+     * in milliseconds. Undefined without a usable header.
+     */
+    readonly retryAfterMs: number | undefined;
+    constructor(status: number, message: string, options?: {
+        code?: string;
+        retryAfterMs?: number;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,31 @@
+/**
+ * An HTTP error response from the AerolVM server. `message` is the server's
+ * message, or `request failed with status N` when the body carries none (a
+ * proxy's HTML error page, say): the same text the SDK threw before this
+ * class existed, so code that printed or matched it sees no change.
+ *
+ * Branch on `code`, not on `message`: the code is a stable identifier, the
+ * message is wording for a person.
+ */
+export class MicroVMApiError extends Error {
+    /** The HTTP status of the final attempt, such as 422 or 503. */
+    status;
+    /**
+     * The server's stable error code, such as `"idempotency_key_reused"` or
+     * `"overloaded"`. Undefined when the response has none: many errors are
+     * only ever shown to a person, and a proxy's error page has no code.
+     */
+    code;
+    /**
+     * How long the response's `Retry-After` header asked the caller to wait,
+     * in milliseconds. Undefined without a usable header.
+     */
+    retryAfterMs;
+    constructor(status, message, options = {}) {
+        super(message);
+        this.name = "MicroVMApiError";
+        this.status = status;
+        this.code = options.code;
+        this.retryAfterMs = options.retryAfterMs;
+    }
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { MicroVM } from "./MicroVM.js";
 export { Sandbox } from "./Sandbox.js";
 export { Image } from "./Image.js";
+export { MicroVMApiError } from "./errors.js";
 export type { MicroVMConfig, Tokens } from "./MicroVM.js";
 export type { RetryConfig } from "./internal/client.js";
-export type { AddCustomDomainOptions, APIToken, APITokenList, CreateAPITokenOptions, CreatedAPIToken, WhoAmI, WhoAmIPrincipal, AuditEvent, AuditOptions, AuditPage, EgressProfile, EgressProfileList, EgressProfileOptions, EgressProfileRef, EgressInject, EgressRule, ListEgressProfilesOptions, NetworkLearned, NetworkLearnedEntry, NetworkPolicy, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, NetworkPolicyOptions, BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CloneGeneration, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, CustomDomain, CustomDomainDNSRecords, CustomDomainStatus, DNSRecord, DNSRecordType, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, Failover, FailoverPolicy, GetOptions, HealthStatus, IngressTarget, IngressTargetSource, Lifecycle, ListOptions, MountSpec, MountSpecRedacted, MountType, PlatformVolumeMount, RegisterSnapshotOptions, ListSnapshotsOptions, SnapshotList, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, Template, TemplatePushState, TemplateStatus, WasmModule, WasmModuleStatus, PushWasmModuleOptions, PushWasmModuleResult, UpdateLifecycleOptions, } from "./types.js";
+export type { AddCustomDomainOptions, APIToken, APITokenList, CreateAPITokenOptions, CreatedAPIToken, WhoAmI, WhoAmIPrincipal, AuditEvent, AuditOptions, AuditPage, EgressProfile, EgressProfileList, EgressProfileOptions, EgressProfileRef, EgressInject, EgressRule, ListEgressProfilesOptions, NetworkLearned, NetworkLearnedEntry, NetworkPolicy, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, NetworkPolicyOptions, BinaryLike, BuildImageOptions, BuildImagePushOptions, BuildImageResult, CloneGeneration, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, CustomDomain, CustomDomainDNSRecords, CustomDomainStatus, DNSRecord, DNSRecordType, ExecRequest, ExecResult, ExecExitInfo, ExposedPort, ExposePortOptions, ExposeProtocol, ExposeResult, Failover, FailoverPolicy, GetOptions, HealthStatus, IngressTarget, IngressTargetSource, Lifecycle, ListOptions, MountSpec, MountSpecRedacted, MountType, PlatformVolumeMount, CreateSnapshotOptions, RegisterSnapshotOptions, ListSnapshotsOptions, SnapshotList, RegistryAuth, ResizeOptions, Sandbox as SandboxData, SandboxSnapshot, SandboxStatus, Session, SessionAttachHandle, SessionAttachOptions, SessionStatus, Template, TemplatePushState, TemplateStatus, WasmModule, WasmModuleStatus, PushWasmModuleOptions, PushWasmModuleResult, UpdateLifecycleOptions, } from "./types.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { MicroVM } from "./MicroVM.js";
 export { Sandbox } from "./Sandbox.js";
 export { Image } from "./Image.js";
+export { MicroVMApiError } from "./errors.js";

package/dist/internal/client.d.ts

@@ -1,5 +1,5 @@
 import { Image } from "../Image.js";
-import type { AddCustomDomainOptions, APITokenList, BinaryLike, BuildImageOptions, BuildImageResult, CreateAPITokenOptions, CreatedAPIToken, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, CustomDomain, CloneGeneration, CustomDomainDNSRecords, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, IngressTarget, Lifecycle, GetOptions, ListOptions, MountSpecRedacted, NetworkUsage, AuditOptions, AuditPage, EgressProfile, EgressProfileList, EgressProfileOptions, EgressProfileRef, EgressRule, ListEgressProfilesOptions, NetworkLearned, NetworkPolicy, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, NetworkPolicyOptions, ListSnapshotsOptions, RegisterSnapshotOptions, SnapshotList, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule, WhoAmI } from "../types.js";
+import type { AddCustomDomainOptions, APITokenList, BinaryLike, BuildImageOptions, BuildImageResult, CreateAPITokenOptions, CreatedAPIToken, CreateOptions, CreateSessionOptions, CreateTemplateOptions, CreateWasmModuleOptions, PushWasmModuleOptions, PushWasmModuleResult, CustomDomain, CloneGeneration, CustomDomainDNSRecords, ExecRequest, ExecResult, ExecStreamHandle, ExecStreamOptions, ExposedPort, ExposePortOptions, ExposeResult, Failover, HealthStatus, IngressTarget, Lifecycle, GetOptions, ListOptions, MountSpecRedacted, NetworkUsage, AuditOptions, AuditPage, EgressProfile, EgressProfileList, EgressProfileOptions, EgressProfileRef, EgressRule, ListEgressProfilesOptions, NetworkLearned, NetworkPolicy, NetworkPolicyCheckOptions, NetworkPolicyCheckResult, NetworkPolicyOptions, ListSnapshotsOptions, CreateSnapshotOptions, RegisterSnapshotOptions, SnapshotList, SetNetworkLimitsOptions, ResizeOptions, Sandbox, SandboxSnapshot, Session, SessionAttachHandle, SessionAttachOptions, Template, WasmModule, WhoAmI } from "../types.js";
 type FetchLike = typeof fetch;
 /**
  * The request header that selects which of a credential's teams a request
@@ -81,6 +81,13 @@ export interface APIClientConfig {
      */
     signal?: AbortSignal;
 }
+/**
+ * The header a sandbox create carries so the server can recognise a retry of
+ * it. Keep in sync with clustercreate.HeaderIdempotencyKey on the server.
+ */
+export declare const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+/** A fresh create key: 128 random bits as 32 lowercase hex characters. */
+export declare function newIdempotencyKey(): string;
 /**
  * Reads a `Retry-After` value in either form RFC 9110 allows: delta-seconds
  * (`"120"`) or an HTTP date. Returns the wait in milliseconds (0 for a date
@@ -150,7 +157,7 @@ export declare class APIClient {
     get(id: string, options?: GetOptions): Promise<SandboxResource>;
     start(id: string): Promise<SandboxResource>;
     stop(id: string): Promise<SandboxResource>;
-    createSnapshot(id: string, name: string): Promise<SandboxSnapshot>;
+    createSnapshot(id: string, name: string, options?: CreateSnapshotOptions): Promise<SandboxSnapshot>;
     registerSnapshot(options: RegisterSnapshotOptions): Promise<SandboxSnapshot>;
     registerSnapshotFromImage(name: string, image: Image, options?: Omit<RegisterSnapshotOptions, "name" | "image" | "dockerfileContent">): Promise<SandboxSnapshot>;
     getSnapshot(name: string): Promise<SandboxSnapshot>;
@@ -330,7 +337,7 @@ export declare class SandboxResource implements Sandbox {
         list(): Promise<CustomDomain[]>;
         dns(): Promise<CustomDomainDNSRecords>;
     };
-    createSnapshot(name: string): Promise<SandboxSnapshot>;
+    createSnapshot(name: string, options?: CreateSnapshotOptions): Promise<SandboxSnapshot>;
     start(): Promise<this>;
     stop(): Promise<this>;
     destroy(): Promise<void>;

package/dist/internal/client.js

@@ -1,5 +1,6 @@
 import { basename } from "node:path";
 import { PATH_PREFIX as V1_PATH_PREFIX, ingressDNSPath as v1IngressDNSPath, sandboxCustomDomainDNSPath as v1SandboxCustomDomainDNSPath, sandboxCustomDomainPath as v1SandboxCustomDomainPath, sandboxCustomDomainsPath as v1SandboxCustomDomainsPath, } from "./api/v1/paths.js";
+import { MicroVMApiError } from "../errors.js";
 import { Image } from "../Image.js";
 /**
  * The request header that selects which of a credential's teams a request
@@ -67,6 +68,19 @@ const RETRYABLE_STATUS_CODES = new Set([421, 429, 502, 503, 504]);
 // over its share, 503 when the node sheds load. A Retry-After on a 421, 502 or
 // 504 is a hop's, not the server's, so those use the normal backoff.
 const REFUSED_STATUS_CODES = new Set([429, 503]);
+/**
+ * The header a sandbox create carries so the server can recognise a retry of
+ * it. Keep in sync with clustercreate.HeaderIdempotencyKey on the server.
+ */
+export const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+/** A fresh create key: 128 random bits as 32 lowercase hex characters. */
+export function newIdempotencyKey() {
+    // getRandomValues, unlike randomUUID, also works on a page served over
+    // plain http.
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
 /** Default retry settings when the caller doesn't supply a RetryConfig. */
 const DEFAULT_RETRY = {
     maxRetries: 3,
@@ -262,7 +276,13 @@ export class APIClient {
     }
     async create(options) {
         const resolved = await this.resolveImage(options);
-        const response = await this.doJSON("POST", this.versioned("/sandboxes"), toApiCreateOptions(resolved));
+        // One key per call, sent unchanged on each of its automatic retries: a
+        // create retried after a timeout gets back the sandbox the first attempt
+        // made instead of making a second one.
+        const key = options.idempotencyKey?.trim() || newIdempotencyKey();
+        const response = await this.doJSON("POST", this.versioned("/sandboxes"), toApiCreateOptions(resolved), {
+            headers: { [IDEMPOTENCY_KEY_HEADER]: key },
+        });
         return new SandboxResource(this, fromApiCreateSandboxResponse(response));
     }
     /**
@@ -385,8 +405,12 @@ export class APIClient {
         const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/stop`);
         return this.wrap(response);
     }
-    async createSnapshot(id, name) {
-        const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/snapshot`, { name });
+    async createSnapshot(id, name, options = {}) {
+        const body = { name };
+        if (options.allowPause !== undefined) {
+            body.allow_pause = options.allowPause;
+        }
+        const response = await this.doJSON("POST", `${this.versionPrefix}/sandboxes/${id}/snapshot`, body);
         return fromApiSandboxSnapshot(response);
     }
     async registerSnapshot(options) {
@@ -764,12 +788,10 @@ export class APIClient {
         return new SandboxResource(this, fromApiSandbox(sandbox));
     }
     async doJSON(method, path, body, options) {
-        const init = {};
+        const init = { headers: { ...options?.headers } };
         if (body !== undefined) {
             init.body = JSON.stringify(body);
-            init.headers = {
-                "Content-Type": "application/json",
-            };
+            init.headers = { ...init.headers, "Content-Type": "application/json" };
         }
         const response = await this.request(method, path, init, options);
         if (!response.ok) {
@@ -928,8 +950,8 @@ export class SandboxResource {
             dns: () => client.customDomainDNS(id),
         };
     }
-    async createSnapshot(name) {
-        return this.client.createSnapshot(this.id, name);
+    async createSnapshot(name, options = {}) {
+        return this.client.createSnapshot(this.id, name, options);
     }
     async start() {
         const updated = await this.client.start(this.id);
@@ -1432,16 +1454,19 @@ function toBlob(data) {
     return new Blob([Uint8Array.from(data)]);
 }
 async function decodeError(response) {
+    const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"), Date.now());
     try {
         const payload = (await response.json());
         if (typeof payload.error === "string" && payload.error !== "") {
-            return new Error(payload.error);
+            const code = typeof payload.code === "string" && payload.code !== "" ? payload.code : undefined;
+            return new MicroVMApiError(response.status, payload.error, { code, retryAfterMs });
         }
     }
     catch {
-        // Fall through to status-based error.
+        // Not JSON (a proxy's error page) or no body: fall through to the
+        // status-based message, with no code.
     }
-    return new Error(`request failed with status ${response.status}`);
+    return new MicroVMApiError(response.status, `request failed with status ${response.status}`, { retryAfterMs });
 }
 const STREAM_PREFIX_STDOUT = 0x01;
 const STREAM_PREFIX_STDERR = 0x02;

package/dist/types.d.ts

@@ -29,6 +29,16 @@ export interface BuildImageResult {
     /** Pushed reference, e.g. "ghcr.io/my-org/my-image:v1.2.3". */
     pushed?: string;
 }
+export interface CreateSnapshotOptions {
+    /**
+     * Whether the snapshot may pause a running sandbox. Defaults to true: a
+     * running sandbox is paused while it is copied (its disk writes wait;
+     * Docker pauses the container) and keeps running afterwards. Set false to
+     * have a sandbox that is not stopped refused with HTTP 409 instead, for a
+     * workload that must never stall. A stopped sandbox needs no pause.
+     */
+    allowPause?: boolean;
+}
 export interface RegisterSnapshotOptions {
     /** Human-readable identifier other callers use in `CreateOptions.snapshot`. */
     name: string;
@@ -135,6 +145,19 @@ export interface GPUOptions {
 }
 import type { Image } from "./Image.js";
 export interface CreateOptions {
+    /**
+     * Sent as the create's `Idempotency-Key` header, never in the body. A create
+     * sent again with the same key and the same options returns the sandbox the
+     * first one made instead of making a second; the same key with different
+     * options fails with a 422 `MicroVMApiError` whose `code` is
+     * `"idempotency_key_reused"`. Keys are scoped to the caller's account.
+     *
+     * Leave it unset and the SDK makes a random key for each `create` call and
+     * reuses it on that call's automatic retries, so a retry after a timeout
+     * cannot make a second sandbox. Set your own to make your own retries of
+     * the whole call safe too, such as after your process restarts.
+     */
+    idempotencyKey?: string;
     /**
      * Optional name, unique among the caller's sandboxes (another account may
      * use the same name). A repeat create with a name the caller already holds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aerol-ai/aerolvm-sdk",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "private": false,
   "repository": {
     "type": "git",