@slicervm/sdk 0.1.7 → 0.1.8

package/README.md

@@ -2,7 +2,7 @@
 
 TypeScript SDK for the [Slicer](https://slicervm.com) VM control-plane API.
 
-Mirrors the [Go SDK](https://github.com/slicervm/sdk) semantically. The top-level `SlicerClient` exposes `hostGroups`, `vms`, and `secrets` namespaces for control-plane operations; per-VM operations live on a `VM` handle returned from `client.vms.create()` / `client.vms.attach()`.
+Mirrors the [Go SDK](https://github.com/slicervm/sdk) semantically. The top-level `SlicerClient` exposes `hostGroups`, `vms`, `commits`, and `secrets` namespaces for control-plane operations; per-VM operations live on a `VM` handle returned from `client.vms.create()` / `client.vms.attach()`.
 
 Supports Unix socket and HTTP(S) transports.
 
@@ -33,6 +33,34 @@ for await (const f of vm.bg.logs(bg.execId, { follow: true })) {
 await vm.delete();
 ```
 
+## Cold forks
+
+A stopped persistent VM can be committed as an immutable disk parent, then
+forked into cold-booted children. Fork calls always wait until the child agent
+has finalised its guest identity.
+
+```ts
+await vm.shutdown();
+const parent = await vm.commit({
+  tags: ['node-build'],
+  cacheKey: 'node-build-v1',
+});
+
+const child = await parent.fork({
+  waitTimeoutSec: 120,
+  network: { allow: [], drop: ['0.0.0.0/0'] },
+  tags: ['job=node-build'],
+});
+
+const description = await child.describe();
+console.log(description.parentCommitId, description.network.effective);
+
+const cached = await client.commits.list({ cacheKey: 'node-build-v1' });
+await child.delete();
+await vm.delete();
+await client.commits.delete(parent.commitId);
+```
+
 ## Status
 
 Pre-release. See `ts-plan.md`.

package/dist/index.cjs

@@ -284,7 +284,71 @@ function agentHealthFromWire(w) {
     ...w.agent_uptime !== void 0 && { agentUptime: w.agent_uptime },
     ...w.agent_version !== void 0 && { agentVersion: w.agent_version },
     ...w.system_uptime !== void 0 && { systemUptime: w.system_uptime },
-    ...w.userdata_ran !== void 0 && { userdataRan: w.userdata_ran }
+    ...w.userdata_ran !== void 0 && { userdataRan: w.userdata_ran },
+    ...w.userdata_exit_code !== void 0 && { userdataExitCode: w.userdata_exit_code }
+  };
+}
+function vmCommitFromWire(w) {
+  return {
+    hostname: w.hostname,
+    commitId: w.commit_id,
+    status: w.status,
+    ...w.parent_status !== void 0 && { parentStatus: w.parent_status },
+    mode: w.mode ?? "",
+    ...w.tags !== void 0 && { tags: w.tags },
+    ...w.labels !== void 0 && { labels: w.labels },
+    ...w.cache_key !== void 0 && { cacheKey: w.cache_key }
+  };
+}
+function vmCommitInfoFromWire(w) {
+  return {
+    commitId: w.commit_id,
+    sourceHostname: w.source_hostname,
+    sourceHostGroup: w.source_host_group,
+    createdAt: w.created_at,
+    mode: w.mode,
+    ...w.tags !== void 0 && { tags: w.tags },
+    ...w.labels !== void 0 && { labels: w.labels },
+    ...w.cache_key !== void 0 && { cacheKey: w.cache_key }
+  };
+}
+function vmCommitDeleteFromWire(w) {
+  return { commitId: w.commit_id, status: w.status };
+}
+function vmForkFromWire(w) {
+  return {
+    hostname: w.hostname,
+    sourceHostname: w.source_hostname,
+    ...w.commit_id !== void 0 && { commitId: w.commit_id },
+    status: w.status,
+    ...w.parent_status !== void 0 && { parentStatus: w.parent_status },
+    ...w.child_status !== void 0 && { childStatus: w.child_status },
+    mode: w.mode ?? ""
+  };
+}
+function vmDescriptionFromWire(w) {
+  return {
+    hostname: w.hostname,
+    ...w.hostgroup !== void 0 && { hostGroup: w.hostgroup },
+    ...w.ip !== void 0 && { ip: w.ip },
+    ...w.ram_bytes !== void 0 && { ramBytes: w.ram_bytes },
+    ...w.cpus !== void 0 && { cpus: w.cpus },
+    ...w.created_at !== void 0 && { createdAt: w.created_at },
+    ...w.arch !== void 0 && { arch: w.arch },
+    ...w.tags !== void 0 && { tags: w.tags },
+    ...w.status !== void 0 && { status: w.status },
+    ...w.persistent !== void 0 && { persistent: w.persistent },
+    ...w.storage !== void 0 && { storage: w.storage },
+    ...w.image !== void 0 && { image: w.image },
+    ...w.commit_id !== void 0 && { commitId: w.commit_id },
+    ...w.parent_commit_id !== void 0 && { parentCommitId: w.parent_commit_id },
+    network: {
+      ...w.network.mode !== void 0 && { mode: w.network.mode },
+      ...w.network.policy_source !== void 0 && { policySource: w.network.policy_source },
+      hostGroup: w.network.host_group,
+      ...w.network.override !== void 0 && { override: w.network.override },
+      effective: w.network.effective
+    }
   };
 }
 function fsEntryFromWire(w) {
@@ -739,6 +803,48 @@ var VMFileSystem = class {
     );
   }
 };
+var CommittedVM = class {
+  constructor(transport, hostGroup, response) {
+    this.transport = transport;
+    this.hostname = response.hostname;
+    this.hostGroup = hostGroup;
+    this.commitId = response.commitId;
+    this.status = response.status;
+    if (response.parentStatus !== void 0) this.parentStatus = response.parentStatus;
+    this.mode = response.mode;
+    if (response.tags !== void 0) this.tags = response.tags;
+    if (response.labels !== void 0) this.labels = response.labels;
+    if (response.cacheKey !== void 0) this.cacheKey = response.cacheKey;
+  }
+  transport;
+  hostname;
+  hostGroup;
+  commitId;
+  status;
+  parentStatus;
+  mode;
+  tags;
+  labels;
+  cacheKey;
+  async fork(opts = {}) {
+    const res = await forkPath(
+      this.transport,
+      this.commitId,
+      opts
+    );
+    return new VM(this.transport, {
+      hostname: res.hostname,
+      hostGroup: this.hostGroup
+    });
+  }
+  async forkRaw(opts = {}) {
+    return forkPath(
+      this.transport,
+      this.commitId,
+      opts
+    );
+  }
+};
 var VM = class {
   hostname;
   hostGroup;
@@ -778,6 +884,14 @@ var VM = class {
   async logs() {
     return this.transport.request("GET", `/vm/${encodeURIComponent(this.hostname)}/logs`);
   }
+  /** Return configuration, fork lineage, and effective network policy. */
+  async describe() {
+    const wire = await this.transport.request(
+      "GET",
+      `/vm/${encodeURIComponent(this.hostname)}`
+    );
+    return vmDescriptionFromWire(wire);
+  }
   async waitForAgent(opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 12e4;
     const intervalMs = opts.intervalMs ?? 500;
@@ -804,10 +918,15 @@ var VM = class {
     while (Date.now() < deadline) {
       try {
         last = await this.health();
-        if (last.userdataRan) return last;
       } catch (err) {
         lastErr = err;
       }
+      if (last?.userdataRan) {
+        if (last.userdataExitCode !== void 0 && last.userdataExitCode !== 0) {
+          throw new Error(`userdata failed with exit code ${last.userdataExitCode}`);
+        }
+        return last;
+      }
       await sleep(intervalMs);
     }
     throw new Error(
@@ -839,6 +958,25 @@ var VM = class {
   async restore() {
     await this.transport.request("POST", `/vm/${encodeURIComponent(this.hostname)}/restore`);
   }
+  /**
+   * Commit a stopped persistent VM disk into an immutable parent.
+   */
+  async commit(opts = {}) {
+    const cacheKey = opts.cacheKey?.trim();
+    const tags = opts.tags && opts.tags.length > 0 ? opts.tags : void 0;
+    const labels = opts.labels && Object.keys(opts.labels).length > 0 ? opts.labels : void 0;
+    const body = tags !== void 0 || labels !== void 0 || cacheKey ? {
+      ...tags !== void 0 && { tags },
+      ...labels !== void 0 && { labels },
+      ...cacheKey && { cache_key: cacheKey }
+    } : void 0;
+    const wire = await this.transport.request(
+      "POST",
+      `/vm/${encodeURIComponent(this.hostname)}/commit`,
+      body
+    );
+    return new CommittedVM(this.transport, this.hostGroup, vmCommitFromWire(wire));
+  }
   // --- port forwarding ---------------------------------------------------
   /**
    * Open one or more port forwards from the host to this VM. Each spec follows
@@ -958,6 +1096,32 @@ function sleep(ms) {
 function errMsg(e) {
   return e instanceof Error ? e.message : String(e);
 }
+async function forkPath(transport, commitId, opts) {
+  const id = validateCommitId(commitId);
+  const q = new URLSearchParams();
+  q.set("wait", "agent");
+  if (opts.waitTimeoutSec !== void 0 && opts.waitTimeoutSec > 0) {
+    q.set("timeout", `${opts.waitTimeoutSec}s`);
+  }
+  const query = q.toString() ? `?${q.toString()}` : "";
+  const body = opts.network !== void 0 || (opts.tags?.length ?? 0) > 0 ? {
+    ...opts.network !== void 0 && { network: opts.network },
+    ...(opts.tags?.length ?? 0) > 0 && { tags: opts.tags }
+  } : void 0;
+  const wire = await transport.request(
+    "POST",
+    `/vm/commits/${encodeURIComponent(id)}/fork${query}`,
+    body
+  );
+  return vmForkFromWire(wire);
+}
+function validateCommitId(commitId) {
+  const value = commitId.trim();
+  if (!value || value === "." || value === ".." || value.includes("..") || value.includes("/") || value.includes("\\") || value.includes("\0")) {
+    throw new Error(`invalid commit ID ${JSON.stringify(value)}`);
+  }
+  return value;
+}
 var VMBg = class {
   constructor(transport, hostname) {
     this.transport = transport;
@@ -1216,6 +1380,54 @@ var VMsAPI = class {
     return createVMResFromWire(wire);
   }
 };
+var CommitsAPI = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  async list(opts = {}) {
+    const qs = new URLSearchParams();
+    for (const tag of opts.tags ?? []) {
+      const value = tag.trim();
+      if (value) qs.append("tag", value);
+    }
+    const cacheKey = opts.cacheKey?.trim();
+    const source = opts.source?.trim();
+    const mode = opts.mode?.trim();
+    if (cacheKey) qs.set("cache_key", cacheKey);
+    if (source) qs.set("source", source);
+    if (mode) qs.set("mode", mode);
+    const encoded = qs.toString();
+    const query = encoded ? `?${encoded}` : "";
+    const wire = await this.transport.request("GET", `/vm/commits${query}`);
+    return (wire ?? []).map(vmCommitInfoFromWire);
+  }
+  async delete(commitId) {
+    const id = validateCommitId2(commitId);
+    const wire = await this.transport.request(
+      "DELETE",
+      `/vm/commits/${encodeURIComponent(id)}`
+    );
+    return vmCommitDeleteFromWire(wire);
+  }
+  async fork(commitId, opts = {}) {
+    const id = validateCommitId2(commitId);
+    const qs = new URLSearchParams({ wait: "agent" });
+    if (opts.waitTimeoutSec !== void 0 && opts.waitTimeoutSec > 0) {
+      qs.set("timeout", `${opts.waitTimeoutSec}s`);
+    }
+    const body = opts.network !== void 0 || (opts.tags?.length ?? 0) > 0 ? {
+      ...opts.network !== void 0 && { network: opts.network },
+      ...(opts.tags?.length ?? 0) > 0 && { tags: opts.tags }
+    } : void 0;
+    const wire = await this.transport.request(
+      "POST",
+      `/vm/commits/${encodeURIComponent(id)}/fork?${qs.toString()}`,
+      body
+    );
+    return vmForkFromWire(wire);
+  }
+};
 var SecretsAPI = class {
   constructor(transport) {
     this.transport = transport;
@@ -1262,10 +1474,18 @@ function buildListQuery(opts) {
   const s = qs.toString();
   return s ? `?${s}` : "";
 }
+function validateCommitId2(commitId) {
+  const value = commitId.trim();
+  if (!value || value === "." || value === ".." || value.includes("..") || value.includes("/") || value.includes("\\") || value.includes("\0")) {
+    throw new Error(`invalid commit ID ${JSON.stringify(value)}`);
+  }
+  return value;
+}
 
 // src/proxy.ts
 var ProxySecretBearer = "bearer";
 var ProxySecretBasic = "basic";
+var ProxySecretOAuthClientCredentials = "oauth-client-creds";
 function clientFromWire(w) {
   return { name: w.name, createdAt: w.created_at };
 }
@@ -1422,12 +1642,14 @@ var SlicerClient = class _SlicerClient {
   transport;
   hostGroups;
   vms;
+  commits;
   secrets;
   proxy;
   constructor(opts) {
     this.transport = new TransportClient(opts);
     this.hostGroups = new HostGroupsAPI(this.transport);
     this.vms = new VMsAPI(this.transport);
+    this.commits = new CommitsAPI(this.transport);
     this.secrets = new SecretsAPI(this.transport);
     this.proxy = new ProxyAPI(this.transport);
   }
@@ -1586,6 +1808,8 @@ var SlicerShellSession = class {
   }
 };
 
+exports.CommitsAPI = CommitsAPI;
+exports.CommittedVM = CommittedVM;
 exports.ExecStdioBase64 = ExecStdioBase64;
 exports.ExecStdioText = ExecStdioText;
 exports.FRAME_TYPE_DATA = FRAME_TYPE_DATA;
@@ -1603,6 +1827,7 @@ exports.ProxyAllowsAPI = ProxyAllowsAPI;
 exports.ProxyClientsAPI = ProxyClientsAPI;
 exports.ProxySecretBasic = ProxySecretBasic;
 exports.ProxySecretBearer = ProxySecretBearer;
+exports.ProxySecretOAuthClientCredentials = ProxySecretOAuthClientCredentials;
 exports.ProxySecretsAPI = ProxySecretsAPI;
 exports.SecretExistsError = SecretExistsError;
 exports.SecretsAPI = SecretsAPI;