@slicervm/sdk 0.1.6 → 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

@@ -266,6 +266,7 @@ function createVMReqToWire(r) {
   if (r.ip !== void 0) o.ip = r.ip;
   if (r.tags !== void 0) o.tags = r.tags;
   if (r.secrets !== void 0) o.secrets = r.secrets;
+  if (r.network !== void 0) o.network = r.network;
   return o;
 }
 function createVMResFromWire(w) {
@@ -283,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) {
@@ -738,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;
@@ -777,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;
@@ -803,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(
@@ -838,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
@@ -957,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;
@@ -1215,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;
@@ -1261,18 +1474,184 @@ 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 };
+}
+function clientCreatedFromWire(w) {
+  return { name: w.name, token: w.token, createdAt: w.created_at };
+}
+function secretFromWire2(w) {
+  const out = { name: w.name, host: w.host, createdAt: w.created_at };
+  if (w.type) out.type = w.type;
+  return out;
+}
+function ruleFromWire(w) {
+  const out = { host: w.host };
+  if (w.secret) out.secret = w.secret;
+  if (w.methods && w.methods.length > 0) out.methods = w.methods;
+  if (w.paths && w.paths.length > 0) out.paths = w.paths;
+  if (w.expires && w.expires !== "0001-01-01T00:00:00Z") out.expires = w.expires;
+  if (w.passthrough) out.passthrough = w.passthrough;
+  return out;
+}
+var ProxyAPI = class {
+  constructor(transport) {
+    this.transport = transport;
+    this.clients = new ProxyClientsAPI(transport);
+    this.secrets = new ProxySecretsAPI(transport);
+    this.allows = new ProxyAllowsAPI(transport);
+  }
+  transport;
+  clients;
+  secrets;
+  allows;
+};
+var ProxyClientsAPI = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /** Mint a new proxy client. The returned token is shown once. */
+  async create(name, opts = {}) {
+    const body = { name };
+    if (opts.token) body.token = opts.token;
+    const wire = await this.transport.request(
+      "POST",
+      "/proxy/v1/clients",
+      body
+    );
+    return clientCreatedFromWire(wire);
+  }
+  async list() {
+    const wire = await this.transport.request("GET", "/proxy/v1/clients");
+    return (wire ?? []).map(clientFromWire);
+  }
+  /**
+   * Revoke the token, drop every allow rule the client owned, and
+   * remove the client.
+   */
+  async delete(name) {
+    await this.transport.request("DELETE", `/proxy/v1/clients/${encodeURIComponent(name)}`);
+  }
+  /** List a client's allow rules in declaration order (first-match-wins). */
+  async rules(name) {
+    const wire = await this.transport.request(
+      "GET",
+      `/proxy/v1/clients/${encodeURIComponent(name)}`
+    );
+    return (wire ?? []).map(ruleFromWire);
+  }
+};
+var ProxySecretsAPI = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  async create(req) {
+    const body = {
+      name: req.name,
+      host: req.host,
+      value: req.value
+    };
+    if (req.type) body.type = req.type;
+    await this.transport.request("POST", "/proxy/v1/secrets", body);
+  }
+  async list() {
+    const wire = await this.transport.request("GET", "/proxy/v1/secrets");
+    return (wire ?? []).map(secretFromWire2);
+  }
+  /**
+   * Remove a secret. Allow rules that reference it stop matching until
+   * the secret is recreated or the rule is rewritten.
+   */
+  async delete(name) {
+    await this.transport.request("DELETE", `/proxy/v1/secrets/${encodeURIComponent(name)}`);
+  }
+};
+var ProxyAllowsAPI = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /** Add an allow rule. Returns the resolved rule with absolute `expires`. */
+  async add(req) {
+    const body = {
+      client: req.client,
+      host: req.host
+    };
+    if (req.secret) body.secret = req.secret;
+    if (req.methods && req.methods.length > 0) body.methods = req.methods;
+    if (req.paths && req.paths.length > 0) body.paths = req.paths;
+    if (req.ttlSeconds && req.ttlSeconds > 0) body.ttl_seconds = req.ttlSeconds;
+    if (req.passthrough) body.passthrough = true;
+    const wire = await this.transport.request(
+      "POST",
+      "/proxy/v1/allows",
+      body
+    );
+    return ruleFromWire(wire);
+  }
+  /**
+   * Host-bulk revoke: removes **every** rule on the client whose host
+   * matches. For surgical removal of one rule among siblings on the
+   * same host (e.g. several path-scoped rules on `github.com`), use
+   * `removeByTuple` instead.
+   */
+  async remove(client, host) {
+    await this.transport.request(
+      "DELETE",
+      `/proxy/v1/allows/${encodeURIComponent(client)}/${encodeURIComponent(host)}`
+    );
+  }
+  /**
+   * Surgical revoke: removes the single rule whose
+   * (host, methods, paths, passthrough) tuple matches the request.
+   * Pass exactly the same fields you used at create time. Method and
+   * host casing are normalised server-side, so `"GET"` / `"get"` and
+   * `"github.com"` / `"GITHUB.COM"` all match the same stored rule.
+   *
+   * Returns 404 (surfaced as a SlicerAPIError) when no rule matches.
+   */
+  async removeByTuple(req) {
+    const body = {
+      client: req.client,
+      host: req.host
+    };
+    if (req.secret) body.secret = req.secret;
+    if (req.methods && req.methods.length > 0) body.methods = req.methods;
+    if (req.paths && req.paths.length > 0) body.paths = req.paths;
+    if (req.passthrough) body.passthrough = true;
+    await this.transport.request("POST", "/proxy/v1/allows/revoke", body);
+  }
+};
 
 // src/client.ts
 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);
   }
   static fromEnv(overrides = {}) {
     const baseURL = overrides.baseURL ?? process.env.SLICER_URL;
@@ -1429,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;
@@ -1441,6 +1822,13 @@ exports.GiB = GiB;
 exports.HostGroupsAPI = HostGroupsAPI;
 exports.MiB = MiB;
 exports.NonRootUser = NonRootUser;
+exports.ProxyAPI = ProxyAPI;
+exports.ProxyAllowsAPI = ProxyAllowsAPI;
+exports.ProxyClientsAPI = ProxyClientsAPI;
+exports.ProxySecretBasic = ProxySecretBasic;
+exports.ProxySecretBearer = ProxySecretBearer;
+exports.ProxySecretOAuthClientCredentials = ProxySecretOAuthClientCredentials;
+exports.ProxySecretsAPI = ProxySecretsAPI;
 exports.SecretExistsError = SecretExistsError;
 exports.SecretsAPI = SecretsAPI;
 exports.SlicerAPIError = SlicerAPIError;