@braedonsaunders/appkit-desk 0.9.0 → 0.10.0

package/host.js

@@ -8,9 +8,9 @@
  * emission to the consumer's ports, and the handover masking contract. It
  * never touches a database and knows nothing about tenants or approvals.
  */
-import { existsSync } from 'node:fs';
+import { createReadStream, existsSync } from 'node:fs';
 import { execFile } from 'node:child_process';
-import { mkdir, readFile, rm, statfs, writeFile } from 'node:fs/promises';
+import { mkdir, open, readFile, rename, rm, statfs, writeFile } from 'node:fs/promises';
 import { arch, cpus, release, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
@@ -62,6 +62,19 @@ export function createDeskHost(options) {
     const deviceExists = options.deviceExists ?? existsSync;
     const removeOverlay = options.removeOverlay ?? ((path) => rm(path, { force: true }));
     const parkWithMemory = options.parkWithMemory ?? false;
+    if (options.memoryRestoreMode && (!parkWithMemory || backend.hypervisor === 'virtualization')) {
+        throw new DeskError('Copy-on-write restore requires Cloud Hypervisor and parkWithMemory.');
+    }
+    const retireSnapshot = options.retireSnapshot ?? (async (from, to) => {
+        await rename(from, to);
+        const directory = await open(dirname(from), 'r');
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    });
     const makeSnapshotDir = options.makeSnapshotDir ?? ((path) => mkdir(path, { recursive: true }).then(() => undefined));
     const removeSnapshot = options.removeSnapshot ?? ((path) => rm(path, { recursive: true, force: true }));
     const freeBytes = options.freeBytes ?? defaultFreeBytes;
@@ -125,7 +138,7 @@ export function createDeskHost(options) {
         record.lastActivityAt = now();
     }
     function requireMachine(record, epoch) {
-        if (record.status !== 'resident' || record.epoch !== epoch || !record.machine) {
+        if (record.status !== 'resident' || record.paused || record.epoch !== epoch || !record.machine) {
             throw new DeskError(`Desk ${record.deskId} is not resident; resume it first.`);
         }
         return record.machine;
@@ -281,8 +294,26 @@ export function createDeskHost(options) {
         return join(dirname(overlayPath), `${deskId}.snapshot`);
     }
     async function teardown(record, keepMemory = true) {
+        if (record.status === 'suspending' && record.machine) {
+            // A previous stop failed. Keep the overlay fenced until a retry confirms
+            // the VMM has exited; never boot another VM or delete it underneath one.
+            await record.machine.shutdown();
+            await removeSnapshot(snapshotDirFor(record.startOptions.overlayPath, record.deskId));
+            record.machine = null;
+            record.status = 'suspended';
+            occupied -= 1;
+            lastSuspendedAt = iso(now());
+            drainQueue();
+            return true;
+        }
         if (record.status !== 'resident')
             return false;
+        // Resume before issuing trim, sync, or handover commands. On failure leave
+        // the resident record intact and fenced so the caller can retry.
+        if (record.paused) {
+            await record.machine.resume();
+            record.paused = false;
+        }
         await endHandover(record, 'revoked');
         for (const stop of [...record.streamStops])
             stop();
@@ -334,6 +365,26 @@ export function createDeskHost(options) {
                 if (parking) {
                     const snapshotDir = snapshotDirFor(record.startOptions.overlayPath, record.deskId);
                     await makeSnapshotDir(snapshotDir);
+                    // Persist attachment identity before the VMM can produce a complete
+                    // snapshot. A crash must never leave attached VM state with no record.
+                    if (record.startOptions.readOnlyAttachments?.length) {
+                        const manifest = join(snapshotDir, 'attachments.json');
+                        const file = await open(manifest, 'wx', 0o600);
+                        try {
+                            await file.writeFile(JSON.stringify(record.startOptions.readOnlyAttachments));
+                            await file.sync();
+                        }
+                        finally {
+                            await file.close();
+                        }
+                        const directory = await open(snapshotDir, 'r');
+                        try {
+                            await directory.sync();
+                        }
+                        finally {
+                            await directory.close();
+                        }
+                    }
                     await machine.park(snapshotDir);
                     const signature = await (options.cpuSignature ?? hostCpuSignature)();
                     await (options.writeSnapshotSignature ?? writeSnapshotSignature)(snapshotDir, signature);
@@ -343,10 +394,16 @@ export function createDeskHost(options) {
                 }
             }
             catch (error) {
-                // `park` stops the VMM on its own way out, so the desk is down either
-                // way; what is lost is the memory, not the desk. Leave nothing behind
-                // that a later boot would try to restore from.
+                // Preparation can fail before park is called, so confirm the VMM is
+                // down even when park itself normally stops on failure.
                 lastError = errorMessage(error);
+                try {
+                    await machine.shutdown();
+                }
+                catch (stopError) {
+                    record.machine = machine;
+                    throw new DeskError(`Desk ${record.deskId} could not stop after teardown failed: ${errorMessage(stopError)}`);
+                }
                 if (parking) {
                     await removeSnapshot(snapshotDirFor(record.startOptions.overlayPath, record.deskId)).catch(() => undefined);
                 }
@@ -420,7 +477,8 @@ export function createDeskHost(options) {
         // names its vsock and tap, and a cold-boot retry that renumbered them would
         // come up on a different tap than the one the egress rules were put on.
         const cid = nextCid++;
-        const initramfsPath = resolveInitramfsPath();
+        const initramfsPath = startOptions.initramfsPath ?? resolveInitramfsPath();
+        let restoreDir = snapshotDir;
         const planFor = (restore, shares = startOptions.shares) => buildDeskLaunchPlan({
             deskId,
             hypervisor: backend.hypervisor ?? 'cloud-hypervisor',
@@ -429,26 +487,28 @@ export function createDeskHost(options) {
                 : { virtiofsdPath: options.virtiofsdPath, virtiofsdSandbox: options.virtiofsdSandbox }),
             vmmPath: options.vmmPath,
             kvmPath: options.kvmPath,
-            kernelPath,
+            kernelPath: startOptions.kernelPath ?? kernelPath,
             ...(initramfsPath === undefined ? {} : { initramfsPath }),
             baseImagePath: startOptions.baseImage,
             overlayPath: startOptions.overlayPath,
             memoryMb: startOptions.memoryMb,
+            freePageReporting: startOptions.freePageReporting,
             vcpus: startOptions.vcpus,
             vsockCid: cid,
             runtimeDir: options.runtimeDir,
             tapDevice: startOptions.network?.tapDevice,
             macAddress: startOptions.network?.macAddress,
             shares,
+            readOnlyAttachments: startOptions.readOnlyAttachments,
             // Forward the host's cmdline only when set; otherwise the plan falls
             // back to DEFAULT_KERNEL_CMDLINE.
             ...(kernelCmdline === undefined ? {} : { kernelCmdline }),
             launcherIdentity: options.launcherIdentity,
-            snapshotDir,
-            ...(restore ? { restore: true } : {}),
+            snapshotDir: restore ? restoreDir : snapshotDir,
+            ...(restore ? { restore: true, ...(options.memoryRestoreMode ? { memoryRestoreMode: options.memoryRestoreMode } : {}) } : {}),
         }, { pathExists, deviceExists, ...(options.isDirectory ? { isDirectory: options.isDirectory } : {}) });
         const restorePlan = async () => {
-            const parked = await (options.readSnapshotShares ?? readShareManifest)(snapshotDir);
+            const parked = await (options.readSnapshotShares ?? readShareManifest)(restoreDir);
             try {
                 return planFor(true, parked);
             }
@@ -456,8 +516,37 @@ export function createDeskHost(options) {
                 throw new DeskError(`its restore, with the shares it was parked with, could not be planned: ${errorMessage(error)}`);
             }
         };
+        // Verify bytes, not just the caller's label, before the VMM can map them.
+        for (const image of startOptions.readOnlyAttachments ?? []) {
+            const hash = createHash('sha256');
+            for await (const chunk of createReadStream(image.path))
+                hash.update(chunk);
+            if (hash.digest('hex') !== image.sha256)
+                throw new DeskError(`Read-only attachment digest mismatch: ${image.path}`);
+        }
         let resuming = parkWithMemory && pathExists(snapshotDir);
+        // Shared guest memory, required by virtio-fs, makes Cloud Hypervisor fall
+        // back to eager restore. Reject before retiring the snapshot or cold booting.
+        if (options.memoryRestoreMode === 'copyonwrite') {
+            if (startOptions.shares?.length)
+                throw new DeskError('Copy-on-write restore cannot be combined with virtio-fs shares.');
+            if (resuming && (await (options.readSnapshotShares ?? readShareManifest)(snapshotDir)).length) {
+                throw new DeskError('The parked snapshot has virtio-fs shares and cannot use copy-on-write restore.');
+            }
+        }
         if (resuming) {
+            let savedAttachments;
+            try {
+                savedAttachments = JSON.parse(await readFile(join(snapshotDir, 'attachments.json'), 'utf8'));
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                savedAttachments = [];
+            }
+            if (JSON.stringify(savedAttachments) !== JSON.stringify(startOptions.readOnlyAttachments ?? [])) {
+                throw new DeskError('Snapshot read-only attachment identity does not match; restore requires the original images.');
+            }
             const saved = await (options.readSnapshotSignature ?? readSnapshotSignature)(snapshotDir);
             if (saved !== null && saved !== await (options.cpuSignature ?? hostCpuSignature)()) {
                 await removeSnapshot(snapshotDir);
@@ -465,15 +554,20 @@ export function createDeskHost(options) {
                 recordCpuFallback(deskId, 'signature_mismatch');
             }
         }
+        // Retire before starting the VMM: after a crash the old name can never be
+        // replayed against a disk the guest may have changed. The retired file is
+        // private backing memory, not a restorable snapshot.
+        if (resuming && options.memoryRestoreMode === 'copyonwrite') {
+            restoreDir = `${snapshotDir}.source-${randomUUID()}`;
+            await retireSnapshot(snapshotDir, restoreDir);
+        }
         let machine;
         try {
             machine = resuming
                 ? await backend.boot(await restorePlan(), {
-                    // The guest is restored and PAUSED here. Destroying the snapshot in
-                    // this window is what stops a memory image ever outliving the disk
-                    // state it belongs to. If it fails the restore is abandoned rather
-                    // than resumed, because resuming would leave both alive at once.
-                    onRestored: () => removeSnapshot(snapshotDir),
+                    // Eager restore removes the parked snapshot before resume. A CoW
+                    // source was already retired durably before the VMM started.
+                    onRestored: options.memoryRestoreMode === 'copyonwrite' ? async () => { } : () => removeSnapshot(snapshotDir),
                 })
                 : await backend.boot(planFor(false));
         }
@@ -484,6 +578,7 @@ export function createDeskHost(options) {
                 // boot. Safe by construction — the guest never ran, so the disk is
                 // exactly as the pre-park sync left it.
                 const why = errorMessage(error);
+                resuming = false;
                 await removeSnapshot(snapshotDir);
                 if (isIncompatibleCpuSnapshotError(error))
                     recordCpuFallback(deskId, 'incompatible_cpuid');
@@ -499,12 +594,31 @@ export function createDeskHost(options) {
                     : new DeskError(`Desk ${deskId} failed to boot: ${errorMessage(error)}`);
             }
         }
+        if (resuming && options.memoryRestoreMode === 'copyonwrite') {
+            // The mapping remains file-backed until the VMM has exited. Never remove
+            // it after a failed stop; leaking it is safer than invalidating a live VM.
+            const restored = machine;
+            const stop = restored.shutdown.bind(restored);
+            const park = restored.park?.bind(restored);
+            const releaseSource = async () => {
+                try {
+                    await removeSnapshot(restoreDir);
+                }
+                catch (error) {
+                    lastError = `Snapshot source cleanup failed for ${deskId}: ${errorMessage(error)}`;
+                }
+            };
+            restored.shutdown = async () => { await stop(); await releaseSource(); };
+            if (park)
+                restored.park = async (dir) => { await park(dir); await releaseSource(); };
+        }
         let record = records.get(deskId);
         if (!record) {
             record = {
                 deskId,
                 startOptions,
                 status: 'resident',
+                paused: false,
                 machine,
                 epoch: 1,
                 leaseDeadline: 0,
@@ -523,6 +637,7 @@ export function createDeskHost(options) {
         else {
             record.startOptions = startOptions;
             record.status = 'resident';
+            record.paused = false;
             record.machine = machine;
             record.epoch += 1;
             record.jobs = new Map();
@@ -769,22 +884,28 @@ export function createDeskHost(options) {
         return {
             deskId: record.deskId,
             renewLease(ms) {
-                requireMachine(record, epoch);
+                // Renewing a lease is host-side and remains valid during resident pause.
+                if (record.status !== 'resident' || record.epoch !== epoch || !record.machine) {
+                    throw new DeskError(`Desk ${record.deskId} is not resident; resume it first.`);
+                }
                 record.leaseDeadline = now() + positiveInteger(ms, 'ms');
                 touch(record);
                 armTimer(record);
             },
-            async connect(port) {
+            async connect(port, choice) {
                 requireMachine(record, epoch);
                 if (!Number.isInteger(port) || port < 1 || port > 65535)
                     throw new DeskError('Guest TCP port must be between 1 and 65535.');
                 const machine = requireMachine(record, epoch);
                 const address = record.startOptions.network?.guestAddress;
-                if (!machine.connect && (!address || isIP(address) !== 4))
+                const useVsock = choice?.transport === 'vsock' || (choice?.transport !== 'tcp' && !!machine.connect);
+                if (useVsock && !machine.connect)
+                    throw new DeskError('This backend has no service vsock connector.');
+                if (!useVsock && (!address || isIP(address) !== 4))
                     throw new DeskError('A guest IPv4 address is required to connect to a desk port.');
                 touch(record);
                 try {
-                    const stream = machine.connect ? await machine.connect(port) : await (options.connectGuest ?? connectGuestTcp)(address, port);
+                    const stream = useVsock ? await machine.connect(port) : await (options.connectGuest ?? connectGuestTcp)(address, port);
                     try {
                         requireMachine(record, epoch);
                     }
@@ -1162,19 +1283,51 @@ export function createDeskHost(options) {
         const deskId = cleanDeskId(startOptions.deskId);
         return serializeLifecycle(deskId, async () => {
             const existing = records.get(deskId);
-            if (existing?.status === 'resident' && existing.handle)
+            if (existing?.status === 'suspending')
+                throw new DeskError(`Desk ${deskId} has not stopped; retry suspend first.`);
+            if (existing?.status === 'resident' && existing.handle) {
+                if (existing.paused) {
+                    await existing.machine.resume();
+                    existing.paused = false;
+                }
                 return existing.handle;
+            }
             return admit(() => boot(deskId, { ...startOptions, deskId }));
         });
     }
+    function canPause(deskId) {
+        const record = records.get(cleanDeskId(deskId));
+        return record?.status === 'resident' && typeof record.machine?.pause === 'function' && typeof record.machine?.resume === 'function';
+    }
+    async function pause(deskId) {
+        const id = cleanDeskId(deskId);
+        await serializeLifecycle(id, async () => {
+            const record = records.get(id);
+            if (!record || record.status !== 'resident' || !canPause(id))
+                throw new DeskError(`Desk ${id} cannot be paused.`);
+            if (record.paused)
+                return;
+            if (record.screen?.handover)
+                throw new DeskError(`Desk ${id} has an active handover.`);
+            record.paused = true;
+            await record.machine.pause();
+        });
+    }
     async function resume(deskId) {
         const id = cleanDeskId(deskId);
         return serializeLifecycle(id, async () => {
             const record = records.get(id);
             if (!record)
                 throw new DeskError(`Unknown desk: ${deskId}`);
-            if (record.status === 'resident' && record.handle)
+            if (record.status === 'suspending')
+                throw new DeskError(`Desk ${id} has not stopped; retry suspend first.`);
+            if (record.status === 'resident' && record.handle) {
+                if (record.paused) {
+                    await record.machine.resume();
+                    record.paused = false;
+                }
                 return record.handle;
+            }
             return admit(() => boot(record.deskId, record.startOptions));
         });
     }
@@ -1296,7 +1449,7 @@ export function createDeskHost(options) {
             lastSnapshotCpuFallback,
         };
     }
-    return { start, resume, suspend, shutdown, destroy, stats, sweep };
+    return { start, canPause, pause, resume, suspend, shutdown, destroy, stats, sweep };
 }
 /**
  * Whether the overlay directory's filesystem can make reflink clones.