smolmachines 1.22.1 → 1.24.0

package/dist/binding.d.ts

@@ -265,12 +265,12 @@ export declare class NapiMachine {
    * live RAM + disks (same host). `ports` are `{ host, guest }` inbound
    * forwards for the clone. Returns a handle to the running clone.
    */
-  fork(name: string, ports?: Array<PortMappingConfig> | undefined | null, checkpointable?: boolean | undefined | null): Promise<NapiMachine>
+  fork(name: string, ports?: Array<PortMappingConfig> | undefined | null, checkpointable?: boolean | undefined | null, freezeSource?: boolean | undefined | null): Promise<NapiMachine>
   /**
    * Fork many clones from one retained snapshot and boot them in bounded
    * parallel waves. Transactional: an error removes every clone in this call.
    */
-  forkBatch(names: Array<string>, ports?: Array<PortMappingConfig> | undefined | null, parallel?: number | undefined | null): Promise<Array<NapiMachine>>
+  forkBatch(names: Array<string>, ports?: Array<PortMappingConfig> | undefined | null, parallel?: number | undefined | null, freezeSource?: boolean | undefined | null): Promise<Array<NapiMachine>>
   /** Execute a command directly in the VM (not in a container). */
   exec(command: Array<string>, options?: ExecOptions | undefined | null): Promise<ExecResult>
   /**

package/dist/index.d.ts

@@ -20,5 +20,6 @@ export { Machine, Episode } from './machine';
 export { RolloutClient, RolloutError, adapterSha256 } from './rollout';
 export type { BuildRolloutJobOptions, EnsureRolloutExecutorOptions, RolloutBatchItem, RolloutClientOptions, RolloutCompletion, RolloutExecutorInfo, RolloutGenerateResponse, RolloutJob, RolloutPolicyInfo, RolloutPrompt, RolloutSampling, } from './rollout';
 export { SmolError, NotSupportedError, InvalidConfigError, ExecutionError } from './errors';
+export type { CloudCheckpointInfo } from './transport';
 export type { LocalAvailability, LocalUnavailableCode } from './availability';
 export type { MachineConfig, NetworkPolicy, RestoreCheckpointOptions, MachineState, ResourceSpec, MountSpec, PortSpec, BranchOptions, BranchBatchOptions, CheckpointOptions, ResizeOptions, MachineResources, ForkOptions, ForkBatchOptions, AssignOptions, ExecOptions, ExecResult, MachineUsageReport, ShareLink, PortableCheckpointInfo, MachineUsageTotals, MachineCostBreakdown, ImageInfo, MachineSummary, ListOptions, ExecEvent, ConnectOptions, EgressInterceptor, StartOptions, WaitReadyOptions, PortEndpoint, } from './types';

package/dist/machine.d.ts

@@ -8,7 +8,7 @@
  *  a given backend lacks throw `NotSupportedError`.
  */
 import { type LocalAvailability } from "./availability";
-import { type Transport } from "./transport";
+import { type CloudCheckpointInfo, type Transport } from "./transport";
 import type { MachineResources, ResizeOptions, AssignOptions, BranchBatchOptions, BranchOptions, CheckpointOptions, ConnectOptions, ExecEvent, ExecOptions, ExecResult, ForkBatchOptions, ForkOptions, ImageInfo, ListOptions, MachineConfig, MachineSummary, NetworkPolicy, RestoreCheckpointOptions, StartOptions, MachineUsageReport, ShareLink, PortableCheckpointInfo, PortEndpoint, PortSpec, WaitReadyOptions } from "./types";
 export declare class Machine {
     private readonly transport;
@@ -48,8 +48,13 @@ export declare class Machine {
      * @param options  `labels`: keep machines carrying every one of these
      */
     static list(conn?: ConnectOptions, options?: ListOptions): Promise<MachineSummary[]>;
+    /** Upload a `.checkpoint` file taken on this computer to the cloud, so it
+     *  can be restored there by the returned id. Restoring the file with a cloud
+     *  target uploads it for you. */
+    static uploadCheckpoint(path: string, conn?: ConnectOptions, onProgress?: (sent: number, total: number) => void): Promise<CloudCheckpointInfo>;
     /** Restore a local `.smolcheckpoint` path or durable cloud checkpoint id into
-     * a ready, immediately forkable machine. */
+     * a ready, immediately forkable machine. With a cloud target, a local file is
+     * uploaded first, so a machine checkpointed here resumes in the cloud. */
     static restoreCheckpoint(checkpointId: string, name: string, conn?: ConnectOptions, options?: RestoreCheckpointOptions): Promise<Machine>;
     /** Export a local stored checkpoint directory as one portable file. */
     static exportCheckpoint(source: string, output: string): number;

package/dist/machine.js

@@ -100,8 +100,15 @@ class Machine {
     static async list(conn = {}, options = {}) {
         return (0, transport_1.listMachines)(conn, options);
     }
+    /** Upload a `.checkpoint` file taken on this computer to the cloud, so it
+     *  can be restored there by the returned id. Restoring the file with a cloud
+     *  target uploads it for you. */
+    static async uploadCheckpoint(path, conn = {}, onProgress) {
+        return (0, transport_1.uploadCheckpoint)(path, conn, onProgress);
+    }
     /** Restore a local `.smolcheckpoint` path or durable cloud checkpoint id into
-     * a ready, immediately forkable machine. */
+     * a ready, immediately forkable machine. With a cloud target, a local file is
+     * uploaded first, so a machine checkpointed here resumes in the cloud. */
     static async restoreCheckpoint(checkpointId, name, conn, options) {
         return new Machine(await (0, transport_1.restoreCheckpointTransport)(checkpointId, name, conn, options));
     }

package/dist/native.d.ts

@@ -118,8 +118,8 @@ export interface NapiMachine {
     startForkable(): Promise<void>;
     checkpoint(output: string, store?: string): Promise<NativeCheckpointResult>;
     resize(spec: NativeResizeConfig): Promise<NativeMachineResources>;
-    fork(name: string, ports?: NativePortMapping[], checkpointable?: boolean): Promise<NapiMachine>;
-    forkBatch(names: string[], ports?: NativePortMapping[], parallel?: number): Promise<NapiMachine[]>;
+    fork(name: string, ports?: NativePortMapping[], checkpointable?: boolean, freezeSource?: boolean): Promise<NapiMachine>;
+    forkBatch(names: string[], ports?: NativePortMapping[], parallel?: number, freezeSource?: boolean): Promise<NapiMachine[]>;
     exec(command: string[], options?: NativeExecOptions): Promise<NativeExecResult>;
     run(image: string, command: string[], options?: NativeExecOptions): Promise<NativeExecResult>;
     pullImage(image: string): Promise<NativeImageInfo>;

package/dist/transport.d.ts

@@ -90,6 +90,12 @@ export declare function networkMode(network: boolean | undefined): {
         mode: "open" | "blocked";
     };
 } | Record<string, never>;
+/** The cloud API's form of a {@link NetworkPolicy}. */
+export declare function cloudNetwork(policy: NetworkPolicy): {
+    mode: "open" | "blocked" | "allowCidrs";
+    cidrs?: string[];
+    hosts?: string[];
+};
 /** The engine's form of a {@link NetworkPolicy}. */
 export declare function egressPolicy(policy: NetworkPolicy): {
     network: boolean;
@@ -99,6 +105,16 @@ export declare function egressPolicy(policy: NetworkPolicy): {
 /** Resolve the primary branch lifecycle name and its compatibility aliases. */
 export declare function resolveBranchable(config: MachineConfig): boolean | undefined;
 export declare function toNativeConfig(name: string, config: MachineConfig): NativeMachineConfig;
+interface CloudConn {
+    baseUrl: string;
+    apiKey: string;
+}
+/** The sentence a person should read from a failed response's body. The
+ *  control plane answers errors as RFC 9457 problem+json, whose `detail` is the
+ *  sentence; older builds sent `{"error": …}` or plain text. A JSON object
+ *  yields its first string among detail, error, message and title, so a message
+ *  never pastes JSON; anything else is returned trimmed, as before. */
+export declare function errorSentence(body: string): string;
 /** Percent-encode each path segment but keep the `/` separators — the smolfleet
  *  files route is a wildcard (`/files/<path>`), so slashes are meaningful while
  *  spaces/?/#/% in a filename must be escaped. */
@@ -130,3 +146,18 @@ export declare function connectTransport(id: string, conn: ConnectOptions): Prom
 /** Restore a durable cloud checkpoint into a new machine, then return only once
  * the restored guest is ready. */
 export declare function restoreCheckpointTransport(checkpointId: string, name: string, conn?: ConnectOptions, options?: RestoreCheckpointOptions): Promise<Transport>;
+/** Upload a checkpoint file to the cloud; see {@link uploadCheckpointFile}. */
+export declare function uploadCheckpoint(path: string, conn?: ConnectOptions, onProgress?: (sent: number, total: number) => void): Promise<CloudCheckpointInfo>;
+/** A checkpoint as the cloud describes it. */
+export interface CloudCheckpointInfo {
+    id: string;
+    status: string;
+    sizeBytes: number;
+    arch: string;
+    createdAt: string;
+}
+/** Upload a `.checkpoint` file captured on this computer so it can be
+ *  restored in the cloud. The bytes go straight to object storage in parallel
+ *  parts; the cloud then reads the checkpoint's own manifest. */
+export declare function uploadCheckpointFile(conn: CloudConn, path: string, onProgress?: (sent: number, total: number) => void): Promise<CloudCheckpointInfo>;
+export {};

package/dist/transport.js

@@ -11,16 +11,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.cliConfigApiKey = cliConfigApiKey;
 exports.resolveNetwork = resolveNetwork;
 exports.networkMode = networkMode;
+exports.cloudNetwork = cloudNetwork;
 exports.egressPolicy = egressPolicy;
 exports.resolveBranchable = resolveBranchable;
 exports.toNativeConfig = toNativeConfig;
+exports.errorSentence = errorSentence;
 exports.encodePath = encodePath;
 exports.selectsCloud = selectsCloud;
 exports.makeTransport = makeTransport;
 exports.listMachines = listMachines;
 exports.connectTransport = connectTransport;
 exports.restoreCheckpointTransport = restoreCheckpointTransport;
+exports.uploadCheckpoint = uploadCheckpoint;
+exports.uploadCheckpointFile = uploadCheckpointFile;
 const node_fs_1 = require("node:fs");
+const node_http_1 = require("node:http");
+const node_https_1 = require("node:https");
 const node_net_1 = require("node:net");
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
@@ -176,6 +182,15 @@ function networkMode(network) {
         return { network: { mode: "blocked" } };
     return {};
 }
+/** The cloud API's form of a {@link NetworkPolicy}. */
+function cloudNetwork(policy) {
+    if (policy === "allow-all")
+        return { mode: "open" };
+    if (policy === "deny-all")
+        return { mode: "blocked" };
+    const { cidrs, hosts } = egressPolicy(policy);
+    return { mode: "allowCidrs", cidrs, hosts };
+}
 /** The engine's form of a {@link NetworkPolicy}. */
 function egressPolicy(policy) {
     if (policy === "allow-all")
@@ -585,7 +600,7 @@ class LocalTransport {
         }));
         let clone;
         try {
-            clone = new LocalTransport(await this.inner.fork(name, nativePorts, opts.branchable ?? opts.checkpointable ?? false), this.handleSignals, undefined, this.handleSignals);
+            clone = new LocalTransport(await this.inner.fork(name, nativePorts, opts.branchable ?? opts.checkpointable ?? false, opts.freezeSource ?? false), this.handleSignals, undefined, this.handleSignals);
             await clone.waitUntilReady();
             return clone; // ctor registers for cleanup
         }
@@ -602,7 +617,7 @@ class LocalTransport {
         }));
         const branches = [];
         try {
-            const inners = await this.inner.forkBatch(names, nativePorts, Math.min(8, names.length));
+            const inners = await this.inner.forkBatch(names, nativePorts, Math.min(8, names.length), opts.freezeSource ?? false);
             branches.push(...inners.map((inner) => new LocalTransport(inner, this.handleSignals, undefined, this.handleSignals)));
             for (const branch of branches) {
                 await branch.waitUntilReady();
@@ -644,6 +659,29 @@ const NO_PORT_READY_PROBE_GRACE_MS = 2_000;
  *  request timeout (ms), covering network round-trip and server-side overhead so
  *  the client never aborts before the server has had a chance to finish. */
 const CLOUD_EXEC_TIMEOUT_HEADROOM_MS = 30_000;
+/** The sentence a person should read from a failed response's body. The
+ *  control plane answers errors as RFC 9457 problem+json, whose `detail` is the
+ *  sentence; older builds sent `{"error": …}` or plain text. A JSON object
+ *  yields its first string among detail, error, message and title, so a message
+ *  never pastes JSON; anything else is returned trimmed, as before. */
+function errorSentence(body) {
+    const trimmed = body.trim();
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const fields = parsed;
+            for (const key of ["detail", "error", "message", "title"]) {
+                const value = fields[key];
+                if (typeof value === "string")
+                    return value.trim();
+            }
+        }
+    }
+    catch {
+        // Not JSON: the text is the message.
+    }
+    return trimmed;
+}
 /** Percent-encode each path segment but keep the `/` separators — the smolfleet
  *  files route is a wildcard (`/files/<path>`), so slashes are meaningful while
  *  spaces/?/#/% in a filename must be escaped. */
@@ -691,7 +729,7 @@ async function cloudFetch(conn, method, path, opts = {}) {
         opts.signal?.removeEventListener("abort", onAbort);
     }
     if (!res.ok) {
-        const text = await res.text().catch(() => "");
+        const text = errorSentence(await res.text().catch(() => ""));
         // Surface the server's correlation id (every response carries `x-request-id`)
         // in the error message — clients see the error body but not headers, so
         // without this the id is invisible and support can't correlate the call.
@@ -940,7 +978,7 @@ class CloudTransport {
             throw new errors_1.SmolError("CONNECTION", `cloud exec/stream failed: ${e.message}`);
         }
         if (!res.ok) {
-            const text = await res.text().catch(() => "");
+            const text = errorSentence(await res.text().catch(() => ""));
             const rid = res.headers.get("x-request-id");
             throw new errors_1.SmolError(res.status === 404
                 ? "NOT_FOUND"
@@ -1123,6 +1161,7 @@ class CloudTransport {
                     name,
                     ports: portBody,
                     ...(branchable ? { branchable: true } : {}),
+                    ...(opts.freezeSource ? { freezeSource: true } : {}),
                 },
             });
         }
@@ -1136,6 +1175,7 @@ class CloudTransport {
                     name,
                     ports: portBody,
                     ...(branchable ? { forkable: true } : {}),
+                    ...(opts.freezeSource ? { freezeSource: true } : {}),
                 },
             });
         }
@@ -1158,6 +1198,8 @@ class CloudTransport {
             body.count = opts.count;
         if (opts.namePrefix !== undefined)
             body.namePrefix = opts.namePrefix;
+        if (opts.freezeSource)
+            body.freezeSource = true;
         let resp;
         try {
             resp = await cloudFetch(this.conn, "POST", `/v1/machines/${this.id}/branches/batch`, { json: body });
@@ -1605,18 +1647,19 @@ async function restoreCheckpointTransport(checkpointId, name, conn, options) {
     if (options?.keepIdentity) {
         throw new errors_1.InvalidConfigError("keepIdentity is local-only: a cloud restore always gives the new machine its own identity.");
     }
-    const explicitKey = conn.apiKey ?? process.env.SMOL_CLOUD_TOKEN;
-    const { apiKey: cliKey, endpoint: cliUrl } = cliSession(conn.target);
-    const key = explicitKey ?? cliKey ?? cliConfigApiKey();
-    if (!key) {
-        throw new errors_1.InvalidConfigError(`restoreCheckpoint requires an API key — ${NO_KEY_HINT}.`);
-    }
-    const baseUrl = (conn.baseUrl ??
-        process.env.SMOL_CLOUD_URL ??
-        cliUrl ??
-        DEFAULT_CLOUD_URL).replace(/\/+$/, "");
-    const cloudConn = { baseUrl, apiKey: key };
-    const created = await cloudFetch(cloudConn, "POST", `/v1/checkpoints/${encodeURIComponent(checkpointId)}/restore`, { json: { name } });
+    const cloudConn = cloudConnFor(conn, "restoreCheckpoint");
+    // A checkpoint file taken on this computer is uploaded first.
+    const checkpoint = isCheckpointFile(checkpointId)
+        ? (await uploadCheckpointFile(cloudConn, (0, node_path_1.resolve)(checkpointId))).id
+        : checkpointId;
+    const created = await cloudFetch(cloudConn, "POST", `/v1/checkpoints/${encodeURIComponent(checkpoint)}/restore`, {
+        json: {
+            name,
+            ...(options?.networkPolicy !== undefined
+                ? { network: cloudNetwork(options.networkPolicy) }
+                : {}),
+        },
+    });
     const id = created.id;
     try {
         await cloudFetch(cloudConn, "POST", `/v1/machines/${id}/start`, {
@@ -1630,6 +1673,105 @@ async function restoreCheckpointTransport(checkpointId, name, conn, options) {
     }
     return new CloudTransport(cloudConn, created.name ?? name, id);
 }
+/** The control plane and key a cloud operation uses: explicit options, then
+ *  the environment, then the CLI session. */
+function cloudConnFor(conn, operation) {
+    const explicitKey = conn.apiKey ?? process.env.SMOL_CLOUD_TOKEN;
+    const { apiKey: cliKey, endpoint: cliUrl } = cliSession(conn.target);
+    const key = explicitKey ?? cliKey ?? cliConfigApiKey();
+    if (!key) {
+        throw new errors_1.InvalidConfigError(`${operation} requires an API key — ${NO_KEY_HINT}.`);
+    }
+    const baseUrl = (conn.baseUrl ??
+        process.env.SMOL_CLOUD_URL ??
+        cliUrl ??
+        DEFAULT_CLOUD_URL).replace(/\/+$/, "");
+    return { baseUrl, apiKey: key };
+}
+/** Upload a checkpoint file to the cloud; see {@link uploadCheckpointFile}. */
+function uploadCheckpoint(path, conn = {}, onProgress) {
+    return uploadCheckpointFile(cloudConnFor(conn, "uploadCheckpoint"), (0, node_path_1.resolve)(path), onProgress);
+}
+function isCheckpointFile(checkpoint) {
+    try {
+        return (0, node_fs_1.statSync)(checkpoint).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+const UPLOAD_PARALLELISM = 4;
+const UPLOAD_PART_ATTEMPTS = 4;
+/** Upload a `.checkpoint` file captured on this computer so it can be
+ *  restored in the cloud. The bytes go straight to object storage in parallel
+ *  parts; the cloud then reads the checkpoint's own manifest. */
+async function uploadCheckpointFile(conn, path, onProgress) {
+    const size = (0, node_fs_1.statSync)(path).size;
+    const upload = await cloudFetch(conn, "POST", "/v1/checkpoints", { json: { sizeBytes: size } });
+    const sent = new Array(upload.uploadUrls.length).fill(0);
+    const report = () => onProgress?.(sent.reduce((a, b) => a + b, 0), size);
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const part = next++;
+            if (part >= upload.uploadUrls.length)
+                return;
+            const start = part * upload.partSizeBytes;
+            const length = Math.min(upload.partSizeBytes, size - start);
+            for (let attempt = 0;; attempt++) {
+                try {
+                    await putPart(upload.uploadUrls[part], path, start, length, (n) => {
+                        sent[part] = n;
+                        report();
+                    });
+                    break;
+                }
+                catch (error) {
+                    sent[part] = 0;
+                    if (attempt + 1 >= UPLOAD_PART_ATTEMPTS)
+                        throw error;
+                    await new Promise((r) => setTimeout(r, 2_000 * 2 ** attempt));
+                }
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(UPLOAD_PARALLELISM, upload.uploadUrls.length) }, worker));
+    return cloudFetch(conn, "POST", `/v1/checkpoints/${encodeURIComponent(upload.checkpoint.id)}/complete`, { timeoutMs: 30 * 60 * 1_000 });
+}
+/** PUT one slice of a file to a pre-signed URL. */
+function putPart(url, path, start, length, onSent) {
+    return new Promise((resolve, reject) => {
+        const send = url.startsWith("http://") ? node_http_1.request : node_https_1.request;
+        const request = send(url, {
+            method: "PUT",
+            headers: { "content-length": String(length) },
+        });
+        request.on("response", (response) => {
+            const chunks = [];
+            response.on("data", (chunk) => chunks.push(chunk));
+            response.on("end", () => {
+                const status = response.statusCode ?? 0;
+                if (status >= 200 && status < 300)
+                    resolve();
+                else
+                    reject(new errors_1.SmolError("CONNECTION", `upload part at byte ${start} failed: ${status} ${Buffer.concat(chunks).toString().slice(0, 300)}`));
+            });
+        });
+        request.on("error", reject);
+        if (length === 0) {
+            request.end();
+            return;
+        }
+        let sentBytes = 0;
+        const stream = (0, node_fs_1.createReadStream)(path, { start, end: start + length - 1 });
+        stream.on("data", (chunk) => {
+            sentBytes += chunk.length;
+            onSent(sentBytes);
+        });
+        stream.on("error", reject);
+        stream.pipe(request);
+    });
+}
 function looksLikeLocalCheckpoint(checkpoint) {
     return ((0, node_fs_1.existsSync)(checkpoint) ||
         checkpoint.endsWith(".smolcheckpoint") ||

package/dist/types.d.ts

@@ -88,6 +88,11 @@ export interface BranchOptions {
     branchable?: boolean;
     /** @deprecated Use `branchable`. */
     checkpointable?: boolean;
+    /** Keep the source paused as a reusable branch base instead of resuming it.
+     *  Later branches start from that same state, and a frozen source no longer
+     *  counts toward the concurrency cap. The source cannot run commands again;
+     *  work in its branches, or stop it. */
+    freezeSource?: boolean;
 }
 /** Backwards-compatible name for {@link BranchOptions}. */
 export type ForkOptions = BranchOptions;
@@ -104,6 +109,11 @@ export interface BranchBatchOptions {
     /** Inbound port forwards applied to every child. Empty = each child gets fresh
      *  host ports so children don't collide. */
     ports?: PortSpec[];
+    /** Keep the source paused as a reusable branch base instead of resuming it.
+     *  Later branches start from that same state, and a frozen source no longer
+     *  counts toward the concurrency cap. The source cannot run commands again;
+     *  work in its branches, or stop it. */
+    freezeSource?: boolean;
 }
 /** Backwards-compatible name for {@link BranchBatchOptions}. */
 export type ForkBatchOptions = BranchBatchOptions;
@@ -264,8 +274,9 @@ export type NetworkPolicy = "allow-all" | "deny-all" | {
 /** Options for `Machine.restoreCheckpoint`. */
 export interface RestoreCheckpointOptions {
     /** Apply this network policy to the restored machine before it boots.
-     *  The checkpoint must have been taken on the `"virtio-net"` backend for an
-     *  allow list or `deny-all`. Local target only. */
+     *  Locally, the checkpoint must have been taken on the `"virtio-net"`
+     *  backend for an allow list or `deny-all`. A cloud restore without one has
+     *  networking blocked. */
     networkPolicy?: NetworkPolicy;
     /** Restore the machine as itself going back in time rather than as a clone:
      *  it keeps the hostname and machine ID it was saved with, which skips about

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smolmachines",
-  "version": "1.22.1",
+  "version": "1.24.0",
   "description": "Embed isolated microVM sandboxes directly in your code — no server to run.",
   "license": "Apache-2.0",
   "author": "smol-machines",
@@ -62,8 +62,8 @@
     "typescript": "^5.6.0"
   },
   "optionalDependencies": {
-    "smolmachines-darwin-arm64": "1.22.1",
-    "smolmachines-linux-x64-gnu": "1.22.1",
-    "smolmachines-linux-arm64-gnu": "1.22.1"
+    "smolmachines-darwin-arm64": "1.24.0",
+    "smolmachines-linux-x64-gnu": "1.24.0",
+    "smolmachines-linux-arm64-gnu": "1.24.0"
   }
 }