@lizard-build/sdk 0.1.57 → 0.1.59

package/dist/index.d.mts

@@ -23,9 +23,10 @@ declare class PlatformClient {
     readonly config: ConnectionConfig;
     constructor(opts: ConnectionOpts);
     private json;
-    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** `timeoutMs` overrides the connection's requestTimeoutMs for a call known to be slow, never shortening it. */
+    request<T>(method: string, path: string, body?: unknown, timeoutMs?: number): Promise<T>;
     get<T>(path: string): Promise<T>;
-    post<T>(path: string, body?: unknown): Promise<T>;
+    post<T>(path: string, body?: unknown, timeoutMs?: number): Promise<T>;
     put<T>(path: string, body: unknown): Promise<T>;
     patch<T>(path: string, body: unknown): Promise<T>;
     delete<T = void>(path: string, body?: unknown): Promise<T>;
@@ -920,6 +921,8 @@ interface SandboxSnapshot {
     createdAt: number;
     /** Where it may be restored; see {@link SnapshotScope}. */
     scope: SnapshotScope;
+    /** Whether the source had a volume attached (a restore then cannot attach another); `null` for older snapshots, which cannot take one. */
+    sourceVolume: boolean | null;
     /** The user who took it; `null` for snapshots from before snapshots belonged to a user. */
     createdBy: string | null;
 }
@@ -1173,9 +1176,10 @@ declare class Sandbox extends SandboxClient {
     }): Promise<ForkResult<this>[]>;
     /**
      * Save this sandbox -- memory, running processes and files -- as a private
-     * snapshot. A Firecracker snapshot is `ready` as soon as this returns (about 2 s);
-     * start copies of it with {@link Sandbox.restore} (about 0.4 s each). The source
-     * keeps running. `poolSize` applies to container sandboxes only.
+     * snapshot. A Firecracker snapshot is `ready` as soon as this returns: about 2 s, up to
+     * a few minutes for a sandbox that filled most of its memory (its memory is uploaded
+     * first), so the call waits up to 11 minutes. Start copies of it with {@link Sandbox.restore}
+     * (about 0.4 s each). The source keeps running. `poolSize` applies to container sandboxes only.
      */
     snapshot(name?: string, opts?: SnapshotOpts): Promise<SandboxSnapshot>;
     unexpose(port: number): Promise<void>;
@@ -1190,11 +1194,14 @@ declare class Sandbox extends SandboxClient {
     static getSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
     /**
      * Start a new sandbox from a snapshot, in its region. `projectId` puts it in another project,
-     * in any of your workspaces, as the snapshot's scope allows; default: the snapshot's own project.
+     * in any of your workspaces, as the snapshot's scope allows; default: the volume's project, else
+     * the snapshot's own. `volumeId` mounts that volume at `/workspace` (a Firecracker snapshot of a
+     * sandbox that had no volume attached; the volume must be in the snapshot's region).
      */
     static restore(snapshotId: string, opts?: ConnectionOpts & {
         timeoutMs?: number;
         projectId?: string;
+        volumeId?: string;
     }): Promise<Sandbox>;
     /** Change where a snapshot you took may be restored. */
     static setSnapshotScope(snapshotId: string, scope: SnapshotScope, opts?: ConnectionOpts): Promise<SandboxSnapshot>;

package/dist/index.d.ts

@@ -23,9 +23,10 @@ declare class PlatformClient {
     readonly config: ConnectionConfig;
     constructor(opts: ConnectionOpts);
     private json;
-    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** `timeoutMs` overrides the connection's requestTimeoutMs for a call known to be slow, never shortening it. */
+    request<T>(method: string, path: string, body?: unknown, timeoutMs?: number): Promise<T>;
     get<T>(path: string): Promise<T>;
-    post<T>(path: string, body?: unknown): Promise<T>;
+    post<T>(path: string, body?: unknown, timeoutMs?: number): Promise<T>;
     put<T>(path: string, body: unknown): Promise<T>;
     patch<T>(path: string, body: unknown): Promise<T>;
     delete<T = void>(path: string, body?: unknown): Promise<T>;
@@ -920,6 +921,8 @@ interface SandboxSnapshot {
     createdAt: number;
     /** Where it may be restored; see {@link SnapshotScope}. */
     scope: SnapshotScope;
+    /** Whether the source had a volume attached (a restore then cannot attach another); `null` for older snapshots, which cannot take one. */
+    sourceVolume: boolean | null;
     /** The user who took it; `null` for snapshots from before snapshots belonged to a user. */
     createdBy: string | null;
 }
@@ -1173,9 +1176,10 @@ declare class Sandbox extends SandboxClient {
     }): Promise<ForkResult<this>[]>;
     /**
      * Save this sandbox -- memory, running processes and files -- as a private
-     * snapshot. A Firecracker snapshot is `ready` as soon as this returns (about 2 s);
-     * start copies of it with {@link Sandbox.restore} (about 0.4 s each). The source
-     * keeps running. `poolSize` applies to container sandboxes only.
+     * snapshot. A Firecracker snapshot is `ready` as soon as this returns: about 2 s, up to
+     * a few minutes for a sandbox that filled most of its memory (its memory is uploaded
+     * first), so the call waits up to 11 minutes. Start copies of it with {@link Sandbox.restore}
+     * (about 0.4 s each). The source keeps running. `poolSize` applies to container sandboxes only.
      */
     snapshot(name?: string, opts?: SnapshotOpts): Promise<SandboxSnapshot>;
     unexpose(port: number): Promise<void>;
@@ -1190,11 +1194,14 @@ declare class Sandbox extends SandboxClient {
     static getSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<SandboxSnapshot>;
     /**
      * Start a new sandbox from a snapshot, in its region. `projectId` puts it in another project,
-     * in any of your workspaces, as the snapshot's scope allows; default: the snapshot's own project.
+     * in any of your workspaces, as the snapshot's scope allows; default: the volume's project, else
+     * the snapshot's own. `volumeId` mounts that volume at `/workspace` (a Firecracker snapshot of a
+     * sandbox that had no volume attached; the volume must be in the snapshot's region).
      */
     static restore(snapshotId: string, opts?: ConnectionOpts & {
         timeoutMs?: number;
         projectId?: string;
+        volumeId?: string;
     }): Promise<Sandbox>;
     /** Change where a snapshot you took may be restored. */
     static setSnapshotScope(snapshotId: string, scope: SnapshotScope, opts?: ConnectionOpts): Promise<SandboxSnapshot>;

package/dist/index.js

@@ -176,19 +176,20 @@ var PlatformClient = class {
     const text = await res.text();
     return text ? JSON.parse(text) : void 0;
   }
-  request(method, path, body) {
+  /** `timeoutMs` overrides the connection's requestTimeoutMs for a call known to be slow, never shortening it. */
+  request(method, path, body, timeoutMs) {
     return fetch(`${this.config.apiUrl}${path}`, {
       method,
       headers: this.config.headers,
       body: body === void 0 ? void 0 : JSON.stringify(body),
-      signal: AbortSignal.timeout(this.config.requestTimeoutMs)
+      signal: AbortSignal.timeout(Math.max(this.config.requestTimeoutMs, timeoutMs ?? 0))
     }).then((res) => this.json(res));
   }
   get(path) {
     return this.request("GET", path);
   }
-  post(path, body) {
-    return this.request("POST", path, body);
+  post(path, body, timeoutMs) {
+    return this.request("POST", path, body, timeoutMs);
   }
   put(path, body) {
     return this.request("PUT", path, body);
@@ -1126,6 +1127,7 @@ var SandboxClient = class {
 };
 
 // src/sandbox/index.ts
+var SNAPSHOT_TIMEOUT_MS = 11 * 6e4;
 var Sandbox = class extends SandboxClient {
   constructor(opts) {
     super();
@@ -1286,12 +1288,13 @@ var Sandbox = class extends SandboxClient {
   }
   /**
    * Save this sandbox -- memory, running processes and files -- as a private
-   * snapshot. A Firecracker snapshot is `ready` as soon as this returns (about 2 s);
-   * start copies of it with {@link Sandbox.restore} (about 0.4 s each). The source
-   * keeps running. `poolSize` applies to container sandboxes only.
+   * snapshot. A Firecracker snapshot is `ready` as soon as this returns: about 2 s, up to
+   * a few minutes for a sandbox that filled most of its memory (its memory is uploaded
+   * first), so the call waits up to 11 minutes. Start copies of it with {@link Sandbox.restore}
+   * (about 0.4 s each). The source keeps running. `poolSize` applies to container sandboxes only.
    */
   snapshot(name = `Snapshot ${this.sandboxId}`, opts = {}) {
-    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name, poolSize: opts.poolSize ?? 5, scope: opts.scope });
+    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name, poolSize: opts.poolSize ?? 5, scope: opts.scope }, SNAPSHOT_TIMEOUT_MS);
   }
   unexpose(port) {
     return new PlatformClient(this.resolveOpts()).delete(`/api/sandboxes/${this.sandboxId}/expose/${port}`);
@@ -1312,15 +1315,18 @@ var Sandbox = class extends SandboxClient {
   }
   /**
    * Start a new sandbox from a snapshot, in its region. `projectId` puts it in another project,
-   * in any of your workspaces, as the snapshot's scope allows; default: the snapshot's own project.
+   * in any of your workspaces, as the snapshot's scope allows; default: the volume's project, else
+   * the snapshot's own. `volumeId` mounts that volume at `/workspace` (a Firecracker snapshot of a
+   * sandbox that had no volume attached; the volume must be in the snapshot's region).
    */
   static async restore(snapshotId, opts) {
     const client = new PlatformClient(opts ?? {});
     const snapshot = await this.getSnapshot(snapshotId, opts);
     const result = await client.post("/api/sandboxes", {
       snapshotId,
-      projectId: opts?.projectId ?? snapshot.projectId,
+      projectId: opts?.projectId ?? (opts?.volumeId ? void 0 : snapshot.projectId),
       region: snapshot.region,
+      volumeId: opts?.volumeId,
       timeoutMs: opts?.timeoutMs ?? DEFAULT_SANDBOX_TIMEOUT_MS
     });
     return new this({ ...opts, sandboxId: result.sandboxId ?? result.id });

package/dist/index.mjs

@@ -123,19 +123,20 @@ var PlatformClient = class {
     const text = await res.text();
     return text ? JSON.parse(text) : void 0;
   }
-  request(method, path, body) {
+  /** `timeoutMs` overrides the connection's requestTimeoutMs for a call known to be slow, never shortening it. */
+  request(method, path, body, timeoutMs) {
     return fetch(`${this.config.apiUrl}${path}`, {
       method,
       headers: this.config.headers,
       body: body === void 0 ? void 0 : JSON.stringify(body),
-      signal: AbortSignal.timeout(this.config.requestTimeoutMs)
+      signal: AbortSignal.timeout(Math.max(this.config.requestTimeoutMs, timeoutMs ?? 0))
     }).then((res) => this.json(res));
   }
   get(path) {
     return this.request("GET", path);
   }
-  post(path, body) {
-    return this.request("POST", path, body);
+  post(path, body, timeoutMs) {
+    return this.request("POST", path, body, timeoutMs);
   }
   put(path, body) {
     return this.request("PUT", path, body);
@@ -1073,6 +1074,7 @@ var SandboxClient = class {
 };
 
 // src/sandbox/index.ts
+var SNAPSHOT_TIMEOUT_MS = 11 * 6e4;
 var Sandbox = class extends SandboxClient {
   constructor(opts) {
     super();
@@ -1233,12 +1235,13 @@ var Sandbox = class extends SandboxClient {
   }
   /**
    * Save this sandbox -- memory, running processes and files -- as a private
-   * snapshot. A Firecracker snapshot is `ready` as soon as this returns (about 2 s);
-   * start copies of it with {@link Sandbox.restore} (about 0.4 s each). The source
-   * keeps running. `poolSize` applies to container sandboxes only.
+   * snapshot. A Firecracker snapshot is `ready` as soon as this returns: about 2 s, up to
+   * a few minutes for a sandbox that filled most of its memory (its memory is uploaded
+   * first), so the call waits up to 11 minutes. Start copies of it with {@link Sandbox.restore}
+   * (about 0.4 s each). The source keeps running. `poolSize` applies to container sandboxes only.
    */
   snapshot(name = `Snapshot ${this.sandboxId}`, opts = {}) {
-    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name, poolSize: opts.poolSize ?? 5, scope: opts.scope });
+    return new PlatformClient(this.resolveOpts()).post(`/api/sandboxes/${this.sandboxId}/snapshot`, { name, poolSize: opts.poolSize ?? 5, scope: opts.scope }, SNAPSHOT_TIMEOUT_MS);
   }
   unexpose(port) {
     return new PlatformClient(this.resolveOpts()).delete(`/api/sandboxes/${this.sandboxId}/expose/${port}`);
@@ -1259,15 +1262,18 @@ var Sandbox = class extends SandboxClient {
   }
   /**
    * Start a new sandbox from a snapshot, in its region. `projectId` puts it in another project,
-   * in any of your workspaces, as the snapshot's scope allows; default: the snapshot's own project.
+   * in any of your workspaces, as the snapshot's scope allows; default: the volume's project, else
+   * the snapshot's own. `volumeId` mounts that volume at `/workspace` (a Firecracker snapshot of a
+   * sandbox that had no volume attached; the volume must be in the snapshot's region).
    */
   static async restore(snapshotId, opts) {
     const client = new PlatformClient(opts ?? {});
     const snapshot = await this.getSnapshot(snapshotId, opts);
     const result = await client.post("/api/sandboxes", {
       snapshotId,
-      projectId: opts?.projectId ?? snapshot.projectId,
+      projectId: opts?.projectId ?? (opts?.volumeId ? void 0 : snapshot.projectId),
       region: snapshot.region,
+      volumeId: opts?.volumeId,
       timeoutMs: opts?.timeoutMs ?? DEFAULT_SANDBOX_TIMEOUT_MS
     });
     return new this({ ...opts, sandboxId: result.sandboxId ?? result.id });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lizard-build/sdk",
-  "version": "0.1.57",
+  "version": "0.1.59",
   "description": "TypeScript SDK for Lizard: Firecracker microVM sandboxes, code execution and cloud apps.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",