@ghalex/kvbox-server 0.1.3 → 0.1.4

package/dist/kvbox-server.js

@@ -278,9 +278,16 @@ import { rm as rm3, writeFile as writeFile5 } from "node:fs/promises";
 import { createAdaptorServer } from "@hono/node-server";
 
 // src/core/state.ts
+import { randomBytes } from "node:crypto";
 import { mkdir, readFile as readFile2, readdir, writeFile as writeFile2 } from "node:fs/promises";
 import { z as z2 } from "zod";
 var MachineMetaSchema = z2.object({
+  /**
+   * Host-unique, minted at `kvbox new` (fresh or restored) and kept for the box's life; the tap is
+   * `kv-<id>`. Absent only on a box that predates ids and is still running on its `kv-<name>` tap:
+   * `migrateBoxIds` gives stopped ones theirs at server start, a running one gets it when it next starts.
+   */
+  id: z2.string().optional(),
   name: z2.string(),
   /** Part of the box's identity: machines/<owner>/<name>. See refs.ts. */
   owner: z2.string(),
@@ -303,6 +310,12 @@ var MachineMetaSchema = z2.object({
   /** `kvbox pause`: Firecracker is alive but the VM is frozen (standby). Absent: not paused. */
   paused: z2.boolean().optional()
 });
+function newBoxId(taken) {
+  for (; ; ) {
+    const id = randomBytes(3).toString("hex");
+    if (!taken.has(id)) return id;
+  }
+}
 var SnapshotMetaSchema = z2.object({
   name: z2.string(),
   owner: z2.string(),
@@ -377,57 +390,6 @@ function pidAlive(pid) {
 import { existsSync as existsSync2 } from "node:fs";
 import { mkdir as mkdir2, readdir as readdir2, readFile as readFile3, rename, writeFile as writeFile3 } from "node:fs/promises";
 import { join as join2 } from "node:path";
-async function migrateOwnerLayout(owner, p = paths()) {
-  const done = { boxes: [], snapshots: [], conflicts: [] };
-  for (const name of await oldDepthEntries(p.machines)) {
-    const from = join2(p.machines, name);
-    const to = p.machine(owner, name).dir;
-    if (existsSync2(to)) {
-      done.conflicts.push(`machines/${name}`);
-      continue;
-    }
-    await patchJson(join2(from, "meta.json"), (meta) => ({
-      ...meta,
-      owner,
-      // a restored box names its snapshot: that moved under the same owner
-      source: typeof meta["source"] === "string" && meta["source"].startsWith("snapshot:") && !meta["source"].includes("/") ? `snapshot:${owner}/${meta["source"].slice("snapshot:".length)}` : meta["source"]
-    }));
-    await mkdir2(p.ownerMachines(owner), { recursive: true, mode: 448 });
-    await rename(from, to);
-    done.boxes.push(name);
-  }
-  for (const name of await oldDepthEntries(p.snapshots)) {
-    const from = join2(p.snapshots, name);
-    const to = p.snapshot(owner, name).dir;
-    if (existsSync2(to)) {
-      done.conflicts.push(`snapshots/${name}`);
-      continue;
-    }
-    await patchJson(join2(from, "meta.json"), (meta) => ({
-      ...meta,
-      owner,
-      source: typeof meta["source"] === "string" && !meta["source"].includes("/") ? `${owner}/${meta["source"]}` : meta["source"]
-    }));
-    await mkdir2(p.ownerSnapshots(owner), { recursive: true, mode: 448 });
-    await rename(from, to);
-    done.snapshots.push(name);
-  }
-  return done;
-}
-async function oldDepthEntries(root) {
-  let entries;
-  try {
-    entries = await readdir2(root, { withFileTypes: true });
-  } catch (err) {
-    if (err.code === "ENOENT") return [];
-    throw err;
-  }
-  return entries.filter((e) => e.isDirectory() && existsSync2(join2(root, e.name, "meta.json"))).map((e) => e.name).sort();
-}
-async function patchJson(file, patch) {
-  const raw = JSON.parse(await readFile3(file, "utf8"));
-  await writeFile3(file, JSON.stringify(patch(raw), null, 2) + "\n");
-}
 
 // src/core/db.ts
 import { chmodSync, closeSync, mkdirSync, openSync } from "node:fs";
@@ -509,6 +471,91 @@ function usageEventsFor(boxId, since, p = paths()) {
   const rows = openDb(p).prepare("select * from usage_events where box_id = ? and at >= ? order by at, id").all(boxId, since);
   return rows.map(fromRaw);
 }
+function rekeyUsageEvents(from, to, p = paths()) {
+  return Number(openDb(p).prepare("update usage_events set box_id = ? where box_id = ?").run(to, from).changes);
+}
+
+// src/core/migrate.ts
+async function migrateOwnerLayout(owner, p = paths()) {
+  const done = { boxes: [], snapshots: [], conflicts: [] };
+  for (const name of await oldDepthEntries(p.machines)) {
+    const from = join2(p.machines, name);
+    const to = p.machine(owner, name).dir;
+    if (existsSync2(to)) {
+      done.conflicts.push(`machines/${name}`);
+      continue;
+    }
+    await patchJson(join2(from, "meta.json"), (meta) => ({
+      ...meta,
+      owner,
+      // a restored box names its snapshot: that moved under the same owner
+      source: typeof meta["source"] === "string" && meta["source"].startsWith("snapshot:") && !meta["source"].includes("/") ? `snapshot:${owner}/${meta["source"].slice("snapshot:".length)}` : meta["source"]
+    }));
+    await mkdir2(p.ownerMachines(owner), { recursive: true, mode: 448 });
+    await rename(from, to);
+    done.boxes.push(name);
+  }
+  for (const name of await oldDepthEntries(p.snapshots)) {
+    const from = join2(p.snapshots, name);
+    const to = p.snapshot(owner, name).dir;
+    if (existsSync2(to)) {
+      done.conflicts.push(`snapshots/${name}`);
+      continue;
+    }
+    await patchJson(join2(from, "meta.json"), (meta) => ({
+      ...meta,
+      owner,
+      source: typeof meta["source"] === "string" && !meta["source"].includes("/") ? `${owner}/${meta["source"]}` : meta["source"]
+    }));
+    await mkdir2(p.ownerSnapshots(owner), { recursive: true, mode: 448 });
+    await rename(from, to);
+    done.snapshots.push(name);
+  }
+  return done;
+}
+async function oldDepthEntries(root) {
+  let entries;
+  try {
+    entries = await readdir2(root, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+  return entries.filter((e) => e.isDirectory() && existsSync2(join2(root, e.name, "meta.json"))).map((e) => e.name).sort();
+}
+async function patchJson(file, patch) {
+  const raw = JSON.parse(await readFile3(file, "utf8"));
+  await writeFile3(file, JSON.stringify(patch(raw), null, 2) + "\n");
+}
+async function migrateBoxIds(p = paths()) {
+  const metas = [];
+  for (const ref of await listMachineRefs(p)) {
+    try {
+      metas.push(await readMachineMeta(ref, p));
+    } catch {
+      continue;
+    }
+  }
+  const taken = new Set(metas.flatMap((m) => m.id === void 0 ? [] : [m.id]));
+  const done = [];
+  for (const meta of metas) {
+    if (meta.id !== void 0) {
+      rekeyUsageEvents(refKey(meta), meta.id, p);
+      continue;
+    }
+    if (pidAlive(meta.pid)) continue;
+    await adoptBoxId(meta, taken, p);
+    done.push(refKey(meta));
+  }
+  return done;
+}
+async function adoptBoxId(meta, taken, p = paths()) {
+  if (meta.id !== void 0) return meta;
+  const withId2 = { ...meta, id: newBoxId(taken) };
+  await writeMachineMeta(withId2, p);
+  rekeyUsageEvents(refKey(meta), withId2.id, p);
+  return withId2;
+}
 
 // src/core/machines.ts
 import { spawn } from "node:child_process";
@@ -752,6 +799,12 @@ var NAME_RE = /^[a-z0-9][a-z0-9-]{0,11}$/;
 var AUTO_PREFIX = "box";
 var GUEST_CID = 3;
 var OVERLAY_REL = "overlay.ext4";
+var tapKey = (meta) => meta.id ?? meta.name;
+var usageKey = (meta) => meta.id ?? refKey(meta);
+var idsInUse = (metas) => new Set(metas.flatMap((m) => m.id === void 0 ? [] : [m.id]));
+async function withId(meta, p) {
+  return meta.id !== void 0 ? meta : adoptBoxId(meta, idsInUse(await readAllMeta(p)), p);
+}
 function diskStats(disk) {
   try {
     const st = statSync(disk);
@@ -773,7 +826,7 @@ function diskGibOf(meta, p) {
 }
 function recordState(meta, state, by, p, at = (/* @__PURE__ */ new Date()).toISOString()) {
   try {
-    insertUsageEvent({ boxId: refKey(meta), owner: meta.owner, name: meta.name, at, state, by, vcpu: meta.vcpu, memMib: meta.memMib, diskGib: diskGibOf(meta, p) }, p);
+    insertUsageEvent({ boxId: usageKey(meta), owner: meta.owner, name: meta.name, at, state, by, vcpu: meta.vcpu, memMib: meta.memMib, diskGib: diskGibOf(meta, p) }, p);
   } catch (err) {
     console.error(`warning: usage ledger: ${err.message}`);
   }
@@ -792,12 +845,13 @@ function toMachine(meta, p = paths()) {
   const alive = pidAlive(meta.pid);
   if (!alive && meta.pid !== null) {
     try {
-      closeOpenRun(refKey(meta), (/* @__PURE__ */ new Date()).toISOString(), p);
+      closeOpenRun(usageKey(meta), (/* @__PURE__ */ new Date()).toISOString(), p);
     } catch (err) {
       console.error(`warning: usage ledger: ${err.message}`);
     }
   }
   return {
+    id: meta.id,
     name: meta.name,
     owner: meta.owner,
     ip: meta.ip,
@@ -1014,6 +1068,7 @@ async function createMachine(req, owner, p = paths()) {
   const pubkeyB64 = await readPubkeyB64(p);
   const existing = await readAllMeta(p);
   const name = pickName(req.name, new Set(existing.filter((m2) => m2.owner === owner).map((m2) => m2.name)));
+  const id = newBoxId(idsInUse(existing));
   const ip = nextFreeIp(cfg.subnet, [...existing.map((m2) => m2.ip), cfg.gateway]);
   const mac = macFor(ip);
   const m = p.machine(owner, name);
@@ -1024,16 +1079,16 @@ async function createMachine(req, owner, p = paths()) {
   let tapCreated = false;
   try {
     await createOverlay(m.overlay, size.diskGib);
-    const tap = await createTap(name, cfg);
+    const tap = await createTap(id, cfg);
     tapCreated = true;
-    const spec = { name, owner, ip, mac, vcpu: size.vcpu, memMib: size.memMib, base: base.version };
+    const spec = { id, name, owner, ip, mac, vcpu: size.vcpu, memMib: size.memMib, base: base.version };
     const pid = await launch(spec, tap, cfg, pubkeyB64, p);
     const meta = { ...spec, pid, createdAt: (/* @__PURE__ */ new Date()).toISOString(), source: "base" };
     await writeMachineMeta(meta, p);
     recordState(meta, "running", "new", p, meta.createdAt);
     return toMachine(meta, p);
   } catch (err) {
-    if (tapCreated) await deleteTap(name, cfg).catch(() => void 0);
+    if (tapCreated) await deleteTap(id, cfg).catch(() => void 0);
     await rm(m.dir, { recursive: true, force: true });
     throw err;
   }
@@ -1062,6 +1117,7 @@ async function restoreMachine(fromText, owner, req, cfg, p) {
   await assertRoomFor(snap.vcpu, snap.memMib, req.force ?? false, p);
   const existing = await readAllMeta(p);
   const name = pickName(req.name, new Set(existing.filter((m2) => m2.owner === owner).map((m2) => m2.name)));
+  const id = newBoxId(idsInUse(existing));
   const ip = nextFreeIp(cfg.subnet, [...existing.map((m2) => m2.ip), cfg.gateway]);
   const mac = macFor(ip);
   const m = p.machine(owner, name);
@@ -1073,23 +1129,23 @@ async function restoreMachine(fromText, owner, req, cfg, p) {
   try {
     await run(["cp", "--sparse=always", "--reflink=auto", s.overlay, m.overlay]);
     await link(s.mem, m.memBase);
-    const tap = await createTap(name, cfg, { detached: true });
+    const tap = await createTap(id, cfg, { detached: true });
     tapCreated = true;
-    const spec = { name, owner, ip, mac, vcpu: snap.vcpu, memMib: snap.memMib, base: snap.base };
+    const spec = { id, name, owner, ip, mac, vcpu: snap.vcpu, memMib: snap.memMib, base: snap.base };
     pid = await loadSnapshot(spec, { vmstate: s.vmstate, mem: s.mem, label: shown(from) }, tap, cfg, p);
     await resumeVm(m.sock);
     await introduce(spec, m.vsock, cfg, {
       silent: `nothing answered on the restored box's control channel for 3 s; ${tooOldToRestore(shown(from))}`,
       noAnswer: "the restored box was discarded. kvbox-agent inside it took the request but gave no answer; try again, and if it keeps happening look at the box's journal (kvbox exec <box> -- sudo journalctl -u kvbox-agent) on a box started from the same snapshot."
     });
-    await attachTap(name, cfg);
+    await attachTap(id, cfg);
     const meta = { ...spec, pid, createdAt: (/* @__PURE__ */ new Date()).toISOString(), source: `snapshot:${refKey(from)}`, memSnapshots: 1 };
     await writeMachineMeta(meta, p);
     recordState(meta, "running", "new", p, meta.createdAt);
     return toMachine(meta, p);
   } catch (err) {
     if (pid !== void 0) killQuietly(pid);
-    if (tapCreated) await deleteTap(name, cfg).catch(() => void 0);
+    if (tapCreated) await deleteTap(id, cfg).catch(() => void 0);
     await rm(m.dir, { recursive: true, force: true });
     throw err;
   }
@@ -1147,7 +1203,7 @@ async function waitDead(pid, graceMs) {
   }
 }
 async function cleanupProcess(meta, cfg, p) {
-  await deleteTap(meta.name, cfg);
+  await deleteTap(tapKey(meta), cfg);
   const m = p.machine(meta.owner, meta.name);
   await rm(m.sock, { force: true });
   await rm(m.vsock, { force: true });
@@ -1166,7 +1222,7 @@ async function stopMachine(ref, p = paths()) {
   return toMachine(stopped, p);
 }
 async function startMachine(ref, p = paths()) {
-  const meta = await readMeta(ref, p);
+  const meta = await withId(await readMeta(ref, p), p);
   const cfg = await loadConfig(p);
   if (pidAlive(meta.pid)) throw new KvboxError(`box ${shown(ref)} is already ${meta.paused ? "up, in standby (kvbox resume " + shown(ref) + ")" : "running"}`);
   if (isHibernated(meta, p)) {
@@ -1175,7 +1231,7 @@ async function startMachine(ref, p = paths()) {
   assertAssets(cfg);
   const pubkeyB64 = await readPubkeyB64(p);
   await ensureHostNetwork(cfg);
-  const tap = await createTap(ref.name, cfg);
+  const tap = await createTap(meta.id, cfg);
   try {
     const pid = await launch(meta, tap, cfg, pubkeyB64, p);
     const started = { ...meta, pid };
@@ -1183,7 +1239,7 @@ async function startMachine(ref, p = paths()) {
     recordState(started, "running", "start", p);
     return toMachine(started, p);
   } catch (err) {
-    await deleteTap(ref.name, cfg).catch(() => void 0);
+    await deleteTap(meta.id, cfg).catch(() => void 0);
     throw err;
   }
 }
@@ -1250,7 +1306,7 @@ async function hibernateMachine(ref, p = paths()) {
   return toMachine(hibernated, p);
 }
 async function wakeMachine(ref, p = paths()) {
-  const meta = await readMeta(ref, p);
+  const meta = await withId(await readMeta(ref, p), p);
   const cfg = await loadConfig(p);
   const status = statusOf(meta, p);
   if (status === "running" || status === "standby") throw new KvboxError(`${stateMessage(ref, status)}, not hibernated`);
@@ -1261,20 +1317,20 @@ async function wakeMachine(ref, p = paths()) {
   }
   const m = p.machine(ref.owner, ref.name);
   await ensureHostNetwork(cfg);
-  const tap = await createTap(ref.name, cfg, { detached: true });
+  const tap = await createTap(meta.id, cfg, { detached: true });
   let pid;
   try {
-    const spec = { name: meta.name, owner: meta.owner, ip: meta.ip, mac: meta.mac, vcpu: meta.vcpu, memMib: meta.memMib, base: meta.base };
+    const spec = { id: meta.id, name: meta.name, owner: meta.owner, ip: meta.ip, mac: meta.mac, vcpu: meta.vcpu, memMib: meta.memMib, base: meta.base };
     pid = await loadSnapshot(spec, { vmstate: m.hibernateVmstate, mem: m.hibernateMem, label: `box ${shown(ref)}'s memory image` }, tap, cfg, p);
     await resumeVm(m.sock);
     await introduce(spec, m.vsock, cfg, {
       silent: `nothing answered on the box's control channel for 3 s; it stays hibernated, try kvbox wake ${shown(ref)} again`,
       noAnswer: `the box stays hibernated. kvbox-agent inside it took the request but gave no answer; try kvbox wake ${shown(ref)} again`
     });
-    await attachTap(ref.name, cfg);
+    await attachTap(meta.id, cfg);
   } catch (err) {
     if (pid !== void 0) killQuietly(pid);
-    await deleteTap(ref.name, cfg).catch(() => void 0);
+    await deleteTap(meta.id, cfg).catch(() => void 0);
     throw err;
   }
   await rm(m.memBase, { force: true });
@@ -1404,7 +1460,7 @@ async function machineUsage(ref, since, p = paths()) {
   const box = await getMachine(ref, p);
   const cfg = await loadConfig(p);
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  const boxId = refKey(ref);
+  const boxId = box.id ?? refKey(ref);
   let events = usageEventsFor(boxId, box.createdAt, p);
   if (events.length === 0) {
     insertUsageEvent(
@@ -1419,7 +1475,7 @@ async function machineUsage(ref, since, p = paths()) {
 async function seedUsageLedger(p = paths()) {
   let seeded = 0;
   for (const box of await listMachines(null, p)) {
-    const boxId = `${box.owner}/${box.name}`;
+    const boxId = box.id ?? `${box.owner}/${box.name}`;
     if (usageEventsFor(boxId, box.createdAt, p).length > 0) continue;
     insertUsageEvent(
       { boxId, owner: box.owner, name: box.name, at: (/* @__PURE__ */ new Date()).toISOString(), state: box.status, by: "upgrade", vcpu: box.vcpu, memMib: box.memMib, diskGib: Math.round(box.diskBytes / GIB) },
@@ -1446,7 +1502,7 @@ function versionOf(srcFileUrl, injected) {
 }
 
 // src/version.ts
-var VERSION = versionOf(import.meta.url, true ? "0.1.3" : void 0);
+var VERSION = versionOf(import.meta.url, true ? "0.1.4" : void 0);
 
 // src/caller.ts
 function resolveCaller() {
@@ -1473,6 +1529,8 @@ import { z as z3 } from "zod";
 var SizeSchema = z3.enum(SIZE_NAMES);
 var BoxStatusSchema = z3.enum(["running", "standby", "hibernated", "stopped"]);
 var MachineSchema = z3.object({
+  /** Host-unique short id (the tap is `kv-<id>`). Missing only on a box made before ids that has not restarted since. */
+  id: z3.string().optional(),
   name: z3.string(),
   /** Who the box belongs to; names are unique per owner. A bare name is local to the host, `user@control-plane` later. */
   owner: z3.string(),
@@ -1780,6 +1838,8 @@ async function listen(opts = {}) {
     console.error(`boxes and snapshots now belong to an owner: moved ${moved.boxes.length} box(es) and ${moved.snapshots.length} snapshot(s) under ${cfg.owner}/`);
   }
   for (const c of moved.conflicts) console.error(`warning: ${c} left in place: ${cfg.owner} already has one with that name`);
+  const withIds = await migrateBoxIds(p);
+  if (withIds.length > 0) console.error(`boxes now have an id of their own: ${withIds.length} box(es) made before this version got theirs (${withIds.join(", ")})`);
   const seeded = await seedUsageLedger(p);
   if (seeded > 0) console.error(`usage: started keeping time for ${seeded} box(es) made before this version; kvbox vm usage counts from now for them`);
   const socketPath = opts.socketPath ?? p.serverSock;