@aerol-ai/aerolvm-sdk 0.7.0 → 0.8.0

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";

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

@@ -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

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));
     }
     /**
@@ -764,12 +784,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) {
@@ -1432,16 +1450,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

@@ -135,6 +135,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.0",
   "private": false,
   "repository": {
     "type": "git",