@solarisdk/core 0.4.0 → 0.4.2

package/README.md

@@ -18,7 +18,7 @@ npm install @solarisdk/sdk       # unified client + `solari` CLI
 
 ## Requirements
 
-Node 18+ (or a browser with `WebSocket` and `fetch`). The type declarations need TypeScript 5.0 or newer; `await using` needs TypeScript 5.2+ and a runtime with `Symbol.asyncDispose` (Node 24, or a polyfill).
+Node 18+ (or a browser with `WebSocket` and `fetch`). The type declarations need TypeScript 5.0 or newer; `await using` works in compiled TypeScript 5.2+ on Node 18.18+ (which provide `Symbol.asyncDispose`); running the syntax uncompiled needs Node 24.
 
 ## License
 

package/dist/errors.d.ts

@@ -10,6 +10,12 @@ export declare class GatewayError extends SolariError {
     readonly body?: GatewayErrorBody;
     /** The gateway's hint that retrying may help (`body.retryable`), on every gateway error. */
     readonly retryable?: boolean;
+    /** The gateway's request id (`x-request-id`); include it when reporting a problem. */
+    readonly requestId?: string;
+    /** On a `429`: `"rate_limited"` (transient, honour {@link retryAfterMs}) or `"quota_exceeded"` (a cap; do not retry). */
+    readonly errorType?: "rate_limited" | "quota_exceeded";
+    /** How long the gateway asked callers to wait (`Retry-After`), in ms; only set on retryable errors. */
+    readonly retryAfterMs?: number;
     constructor(status: number, message: string, body?: GatewayErrorBody);
 }
 /** `404` — the sandbox, desktop, snapshot, template or volume does not exist (or is not yours). */
@@ -60,6 +66,20 @@ export declare class SandboxNotStoppedError extends GatewayError {
     readonly state?: string;
     constructor(message?: string, body?: GatewayErrorBody);
 }
+/**
+ * `409 {code:"SnapshotNotRestorable"}` — a restore (create from a snapshot, resume of a paused sandbox, revert)
+ * the platform knows cannot succeed, so it is refused at once instead of timing out as a capacity error.
+ * Never retryable (`retryable === false`). `reason` says why when known: `"golden_mismatch"` means the snapshot
+ * was taken on a different template build (`golden.imageKey`) than the fleet runs, and `snapshotImageKey` /
+ * `hostImageKey` name the two. Take a fresh snapshot from a new sandbox instead.
+ */
+export declare class SnapshotNotRestorableError extends GatewayError {
+    /** Why it cannot be restored, when the gateway says (`"golden_mismatch"`). */
+    readonly reason?: string;
+    readonly snapshotImageKey?: string;
+    readonly hostImageKey?: string;
+    constructor(message?: string, body?: GatewayErrorBody);
+}
 /** A computer-use RPC returned `{ok:false}`. */
 export declare class ActionError extends SolariError {
     readonly method: string;

package/dist/errors.js

@@ -9,12 +9,20 @@ export class GatewayError extends SolariError {
     code;
     body;
     retryable;
+    requestId;
+    errorType;
+    retryAfterMs;
     constructor(status, message, body) {
         super(message);
         this.status = status;
         this.code = body?.code;
         this.body = body;
         this.retryable = body?.retryable;
+        this.requestId = body?.requestId;
+        this.errorType = body?.errorType;
+        if (body?.retryable === true && typeof body.retryAfterSeconds === "number" && body.retryAfterSeconds >= 0) {
+            this.retryAfterMs = Math.round(body.retryAfterSeconds * 1000);
+        }
     }
 }
 export class NotFoundError extends GatewayError {
@@ -54,6 +62,17 @@ export class SandboxNotStoppedError extends GatewayError {
         this.state = body?.state;
     }
 }
+export class SnapshotNotRestorableError extends GatewayError {
+    reason;
+    snapshotImageKey;
+    hostImageKey;
+    constructor(message = "Snapshot cannot be restored", body) {
+        super(409, message, body);
+        this.reason = body?.reason;
+        this.snapshotImageKey = body?.snapshotImageKey;
+        this.hostImageKey = body?.hostImageKey;
+    }
+}
 export class ActionError extends SolariError {
     method;
     code;
@@ -101,6 +120,8 @@ export function mapGatewayError(status, body) {
             if (code === "NotStopped" || code === "StartInProgress") {
                 return new SandboxNotStoppedError(msg, body);
             }
+            if (code === "SnapshotNotRestorable")
+                return new SnapshotNotRestorableError(msg, body);
             return new GatewayError(409, msg ?? "Conflict", body);
         case 503:
             if (code === undefined || code === "NoCapacity" || code === "StartTimeout")

package/dist/http.d.ts

@@ -5,6 +5,8 @@ export interface HttpTransportOptions {
     fetch?: typeof fetch;
     /** Max retry attempts for idempotent requests. Default 5. */
     maxRetries?: number;
+    /** Longest server-requested `Retry-After` the transport will wait out (default 30 000 ms); a longer one surfaces the error. */
+    maxRetryAfterMs?: number;
     /** Per-request timeout in ms (AbortSignal). Default 300000. */
     requestTimeoutMs?: number;
     /** Fixed retry delay in ms. When unset, uses exponential backoff + jitter.
@@ -24,6 +26,7 @@ export declare class HttpTransport {
     readonly baseUrl: string;
     private readonly fetchImpl;
     private readonly maxRetries;
+    private readonly maxRetryAfterMs;
     private readonly requestTimeoutMs;
     private readonly retryDelayMs;
     constructor(o: HttpTransportOptions);
@@ -34,3 +37,5 @@ export declare class HttpTransport {
     request<T>(method: string, path: string, body?: unknown, opts?: HttpRequestOptions): Promise<T>;
     private backoffMs;
 }
+/** `Retry-After` is delta-seconds or an HTTP date; anything else (or negative) is ignored. */
+export declare function parseRetryAfterSeconds(value: string | null): number | undefined;

package/dist/http.js

@@ -10,6 +10,7 @@ export class HttpTransport {
     baseUrl;
     fetchImpl;
     maxRetries;
+    maxRetryAfterMs;
     requestTimeoutMs;
     retryDelayMs;
     constructor(o) {
@@ -25,6 +26,7 @@ export class HttpTransport {
         }
         this.fetchImpl = f;
         this.maxRetries = o.maxRetries ?? 5;
+        this.maxRetryAfterMs = o.maxRetryAfterMs ?? 30_000;
         this.requestTimeoutMs = o.requestTimeoutMs ?? 300_000;
         this.retryDelayMs = o.retryDelayMs;
     }
@@ -70,10 +72,21 @@ export class HttpTransport {
                 catch {
                     errBody = undefined;
                 }
+                const headerId = res.headers.get("x-request-id");
+                const headerRetryAfter = parseRetryAfterSeconds(res.headers.get("retry-after"));
+                if (headerId || headerRetryAfter !== undefined) {
+                    errBody = {
+                        ...errBody,
+                        ...(headerId && !errBody?.requestId ? { requestId: headerId } : {}),
+                        ...(headerRetryAfter !== undefined ? { retryAfterSeconds: headerRetryAfter } : {}),
+                    };
+                }
                 const RETRYABLE_STATUSES = new Set([502, 503, 504, 507]);
                 const retryable = RETRYABLE_STATUSES.has(res.status) || errBody?.retryable === true;
-                if (idempotent && retryable && attempt < this.maxRetries) {
-                    await sleep(this.backoffMs(attempt++));
+                const retryAfterMs = retryable && typeof errBody?.retryAfterSeconds === "number" ? errBody.retryAfterSeconds * 1000 : undefined;
+                const tooLong = retryAfterMs !== undefined && retryAfterMs > this.maxRetryAfterMs;
+                if (idempotent && retryable && !tooLong && attempt < this.maxRetries) {
+                    await sleep(Math.max(this.backoffMs(attempt++), retryAfterMs ?? 0));
                     continue;
                 }
                 throw mapGatewayError(res.status, errBody);
@@ -90,3 +103,14 @@ export class HttpTransport {
         return Math.min(150 * 2 ** attempt, 8000) + Math.floor(Math.random() * 250);
     }
 }
+export function parseRetryAfterSeconds(value) {
+    if (value === null)
+        return undefined;
+    const v = value.trim();
+    if (/^\d+$/.test(v))
+        return Number(v);
+    const t = Date.parse(v);
+    if (Number.isNaN(t))
+        return undefined;
+    return Math.max(0, Math.ceil((t - Date.now()) / 1000));
+}

package/dist/idle-policy.d.ts

@@ -0,0 +1,7 @@
+import type { IdlePolicyStages } from "./types.js";
+/**
+ * Build the string form of an idle policy from stages, e.g. `{ pause: "5m", delete: "1d" }` becomes
+ * `"pause@5m,delete@1d"` (the format the gateway echoes back). Stages come out in order: park, hibernate, pause, delete.
+ * A number is milliseconds. The gateway validates the result (ordering, bounds, conflicts); this only formats it.
+ */
+export declare function formatIdlePolicy(stages: IdlePolicyStages): string;

package/dist/idle-policy.js

@@ -0,0 +1,10 @@
+export function formatIdlePolicy(stages) {
+    const order = ["park", "hibernate", "pause", "delete"];
+    return order
+        .filter((k) => stages[k] !== undefined)
+        .map((k) => {
+        const v = stages[k];
+        return `${k}@${typeof v === "number" ? `${v}ms` : v}`;
+    })
+        .join(",");
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { DEFAULT_COMMAND_TIMEOUT_MS, SessionHandle } from "./handle.js";
 export { shortId } from "./ids.js";
+export { formatIdlePolicy } from "./idle-policy.js";
 export type { SessionConfig, SessionHooks } from "./handle.js";
 export { Desktop } from "./desktop.js";
 export type { DesktopConfig } from "./desktop.js";
@@ -11,5 +12,5 @@ export type { TemplateClientOptions } from "./template-client.js";
 export { VolumeClient } from "./volume-client.js";
 export type { VolumeClientOptions } from "./volume-client.js";
 export { DEFAULT_BASE_URL, HttpTransport, newIdempotencyKey } from "./http.js";
-export { ActionError, AuthError, ConcurrencyLimitError, ConnectionError, GatewayError, NoCapacityError, NotFoundError, SandboxNotStoppedError, SolariError, PlanError, TimeoutError, ValidationError, } from "./errors.js";
+export { ActionError, AuthError, ConcurrencyLimitError, ConnectionError, GatewayError, NoCapacityError, NotFoundError, SandboxNotStoppedError, SnapshotNotRestorableError, SolariError, PlanError, TimeoutError, ValidationError, } from "./errors.js";
 export type * from "./types.js";

package/dist/index.js

@@ -1,9 +1,10 @@
 export { DEFAULT_COMMAND_TIMEOUT_MS, SessionHandle } from "./handle.js";
 export { shortId } from "./ids.js";
+export { formatIdlePolicy } from "./idle-policy.js";
 export { Desktop } from "./desktop.js";
 export { Sandbox } from "./sandbox.js";
 export { Image } from "./image.js";
 export { TemplateClient } from "./template-client.js";
 export { VolumeClient } from "./volume-client.js";
 export { DEFAULT_BASE_URL, HttpTransport, newIdempotencyKey } from "./http.js";
-export { ActionError, AuthError, ConcurrencyLimitError, ConnectionError, GatewayError, NoCapacityError, NotFoundError, SandboxNotStoppedError, SolariError, PlanError, TimeoutError, ValidationError, } from "./errors.js";
+export { ActionError, AuthError, ConcurrencyLimitError, ConnectionError, GatewayError, NoCapacityError, NotFoundError, SandboxNotStoppedError, SnapshotNotRestorableError, SolariError, PlanError, TimeoutError, ValidationError, } from "./errors.js";

package/dist/types.d.ts

@@ -1,6 +1,36 @@
 import type { CompiledImage } from "./image.js";
 /** Session lifecycle status reported by `GET /desktops/:sessionId`. */
 export type DesktopStatus = "starting" | "ready" | "paused" | "releasing" | "gone";
+/**
+ * One stage of an {@link IdlePolicy}. All stages are optional and every offset is measured from the sandbox's LAST
+ * ACTIVITY, so the offsets must increase in this order:
+ *
+ *  - `park`: freeze the vCPUs but keep RAM and the slot; the next request wakes it in milliseconds. Parked time is free.
+ *  - `hibernate`: checkpoint to disk and free the slot (needs a `park` stage; a parked sandbox escalates to it).
+ *  - `pause`: snapshot and free the slot; `connect`/resume brings it back. Same as `lifecycle.onTimeout: "pause"`.
+ *  - `delete`: destroy it. After a `pause` it deletes the paused sandbox (at most 27 days after the pause on Solari
+ *    cloud); with no `pause` stage it is `lifecycle.onTimeout: "kill"`.
+ *
+ * Values are a duration string (`"30s"`, `"5m"`, `"1h30m"`, `"1d"`; units ms, s, m, h, d) or a number of milliseconds.
+ */
+export interface IdlePolicyStages {
+    park?: string | number;
+    hibernate?: string | number;
+    pause?: string | number;
+    delete?: string | number;
+}
+/**
+ * Staged idle policy: what happens as a sandbox sits idle, in one setting. Either the string form
+ * (`"park@30s,hibernate@2m,pause@5m,delete@1d"`) or {@link IdlePolicyStages}. Do not combine it with
+ * `idleTimeoutMs`/`timeoutMs`/`ttlSeconds` or `lifecycle.onTimeout`/`parkAfterMs`/`parkMaxMs`/`hibernateAfterParkedMs`;
+ * the gateway answers 400 naming the clashing field. `lifecycle.autoResume` and `lifecycle.checkpointEveryMs` still apply.
+ *
+ * If the policy has a `park` (or `hibernate`) stage but no `pause` or `delete`, the gateway adds `pause` 24 hours after
+ * the last stage so a parked sandbox cannot hold its slot for the plan's whole maximum; the sandbox view's `idlePolicy`
+ * shows the policy as applied. What is billed: running time at the normal rate; parked time is free; hibernated and
+ * paused sandboxes are not billed for compute.
+ */
+export type IdlePolicy = string | IdlePolicyStages;
 /** What the gateway does when a session's idle/ttl timeout fires. */
 export type OnTimeout = "pause" | "kill";
 /**
@@ -105,6 +135,8 @@ export interface CreateDesktopOptions {
     idleTimeoutMs?: number;
     /** Idle lifecycle policy (pause/kill on timeout; optional auto-resume). */
     lifecycle?: SandboxLifecycle;
+    /** Staged idle policy (park, hibernate, pause, delete as the sandbox sits idle); see {@link IdlePolicy}. Replaces `idleTimeoutMs` + most of `lifecycle`. */
+    idlePolicy?: IdlePolicy;
     /** Persistent volumes to mount before the session starts (Part V.4). */
     volumes?: VolumeAttachment[];
 }
@@ -120,6 +152,7 @@ export interface CreateDesktopRequest {
     record?: boolean;
     timeoutMs?: number;
     lifecycle?: SandboxLifecycle;
+    idlePolicy?: IdlePolicy;
     volumes?: VolumeAttachment[];
 }
 /** `201` response from `POST /desktops`. */
@@ -155,10 +188,25 @@ export interface GatewayErrorBody {
     /** Gateway hint that the failure is transient (e.g. 503 "No desktop host
      *  available"). The HTTP transport retries idempotent requests when set. */
     retryable?: boolean;
+    /** The gateway's id for this request (also the `x-request-id` response header). Quote it in support requests. */
+    requestId?: string;
+    /** On every `429`: `"rate_limited"` (retryable, honour `Retry-After`) or `"quota_exceeded"` (a cap; retrying cannot help). */
+    errorType?: "rate_limited" | "quota_exceeded";
+    /** Seconds to wait before retrying, mirrored from the `Retry-After` header by the transport. */
+    retryAfterSeconds?: number;
     /** Current sandbox state, set on `409 NotStopped` / `409 StartInProgress`. */
     state?: string;
     /** Set on `409 HostCapabilityMissing`: capabilities the host pool lacks (e.g. `["start"]`). */
     missingCapabilities?: string[];
+    /** Set on `409 SnapshotNotRestorable`: why. `"golden_mismatch"` = the snapshot was taken on a different
+     *  template build than the fleet runs now. Absent on the older (CPU-platform / pre-migration) refusals. */
+    reason?: string;
+    /** Set on `409 SnapshotNotRestorable`: the snapshot, where the request named one. */
+    snapshotId?: string;
+    /** Set with `reason: "golden_mismatch"`: the `golden.imageKey` the snapshot was taken on (when the host reports it). */
+    snapshotImageKey?: string;
+    /** Set with `reason: "golden_mismatch"`: the `golden.imageKey` of the host that refused. */
+    hostImageKey?: string;
 }
 /** `kind` of a session: headless `sandbox` or GUI `desktop`. */
 export type SandboxKind = "sandbox" | "desktop";
@@ -228,12 +276,22 @@ export interface CreateSandboxOptions {
     isolation?: SandboxIsolation;
     /** Idle lifecycle policy (pause/kill on timeout; optional auto-resume). */
     lifecycle?: SandboxLifecycle;
+    /** Staged idle policy (park, hibernate, pause, delete as the sandbox sits idle); see {@link IdlePolicy}. Replaces `idleTimeoutMs` + most of `lifecycle`. */
+    idlePolicy?: IdlePolicy;
     /**
      * Persistent volumes to mount into the session before it starts (Part V.4).
      * Each `volumeId` must belong to your org (create one via `client.volumes`).
      * The mount appears at the given absolute `path` inside the guest.
      */
     volumes?: VolumeAttachment[];
+    /**
+     * Run commands, code and file operations as this user (created at first boot with passwordless sudo if the image has
+     * no such user); a per-call `user` overrides it. Default: root. Not available on `isolation: "shared"`. The create
+     * response echoes `user` when the gateway honoured it; an older gateway ignores it or answers 400.
+     */
+    user?: string;
+    /** Default working directory (absolute). Default: the user's home. Same availability as {@link user}. */
+    cwd?: string;
 }
 /** One attach-at-create instruction: a persistent volume + its guest path. */
 export interface VolumeAttachment {
@@ -287,7 +345,26 @@ export interface CreateSandboxRequest {
     resolution?: string;
     record?: boolean;
     lifecycle?: SandboxLifecycle;
+    idlePolicy?: IdlePolicy;
     volumes?: VolumeAttachment[];
+    user?: string;
+    cwd?: string;
+}
+/**
+ * What a sandbox (or the sandbox a snapshot was taken from) actually ran on. Goldens are content-
+ * addressed: `imageKey` is `sha256(rootfsSha256 | kernelSha256 | chVersion)`, so equal `imageKey`s
+ * mean byte-identical rootfs, kernel and VMM. `template` is only the name; this is the bits behind it.
+ */
+export interface GoldenInfo {
+    imageKey: string;
+    /** Template name the golden was built for. */
+    template?: string;
+    /** SHA-256 of the root filesystem image. */
+    rootfsSha256?: string;
+    /** SHA-256 of the guest kernel. */
+    kernelSha256?: string;
+    /** Cloud Hypervisor (VMM) version. */
+    chVersion?: string;
 }
 /** `201` response from `POST /sandboxes`. */
 export interface CreateSandboxResponse {
@@ -303,6 +380,13 @@ export interface CreateSandboxResponse {
      * `RecordingRequiresDesktop`) — it has no display to capture.
      */
     recordingUrl?: string;
+    /** The default user and working directory, echoed when the gateway honoured `user` / `cwd` on create. */
+    user?: string;
+    cwd?: string;
+    /** The template the sandbox was created from. */
+    template?: string;
+    /** The golden it runs on (rootfs / kernel / VMM digests); absent when the host did not report one. */
+    golden?: GoldenInfo;
 }
 /** `GET /sandboxes/:id` response. */
 export interface SandboxView {
@@ -328,6 +412,14 @@ export interface SandboxView {
     diskGb?: number;
     /** Presigned playback URL, present for a recorded `kind:"desktop"` session. */
     recordingUrl?: string;
+    /** The staged idle policy as the gateway applies it (including a `pause` stage it added), when one was set. */
+    idlePolicy?: string;
+    /** Set while the sandbox is paused under an `idlePolicy` with a `delete` stage: when it will be deleted (ISO 8601). */
+    deleteAt?: string;
+    /** The template this sandbox was created from. */
+    template?: string;
+    /** The golden it runs on (rootfs / kernel / VMM digests); absent when the host did not report one. */
+    golden?: GoldenInfo;
 }
 /** `GET /sandboxes` response (paginated). */
 export interface ListSandboxesResponse {
@@ -358,6 +450,8 @@ export interface SnapshotView {
     createdAt: string;
     kind: SandboxKind;
     template: string;
+    /** The golden the source sandbox ran on when the snapshot was taken; absent for older snapshots. */
+    golden?: GoldenInfo;
 }
 /** `POST /sandboxes/:id/snapshots` response. */
 export interface CreateSnapshotResponse {
@@ -374,6 +468,8 @@ export interface ListSnapshotsOptions {
     limit?: number;
     /** Take a previous page's `nextCursor` to get the page after it. */
     cursor?: string;
+    /** Only snapshots taken from this sandbox. */
+    sandboxId?: string;
 }
 /** `GET /snapshots` response: newest snapshots first, paged with an opaque cursor. */
 export interface ListSnapshotsResponse {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarisdk/core",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Shared runtime for the Solari SDK \u2014 transport, session handles, images, templates, and types used by @solarisdk/desktop and @solarisdk/sandbox.",
   "type": "module",
   "main": "./dist/index.js",