@braedonsaunders/appkit-desk 0.10.0 → 0.11.0

package/host.js

@@ -20,6 +20,8 @@ import { buildDeskLaunchPlan, cleanDeskId, DEFAULT_KVM_PATH, DEFAULT_VMM_PATH, D
 import { cloudHypervisorBackend, } from './backend.js';
 import { readShareManifest } from './machine.js';
 import { parseCapabilities, parseClipboardText, parseExecResult, parseHandoverBegun, parseJobStarted, parseObservation, } from './protocol.js';
+/** Capability marker for the fenced template lifecycle and mapping proof. */
+export const DESK_TEMPLATE_VERSION = 3;
 export const DEFAULT_CAPACITY = 4;
 export const DEFAULT_IDLE_SUSPEND_MS = 5 * 60_000;
 export const DEFAULT_LEASE_MS = 15 * 60_000;
@@ -62,6 +64,8 @@ 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.strictMemoryRestore && !parkWithMemory)
+        throw new DeskError('Strict memory restore requires parkWithMemory.');
     if (options.memoryRestoreMode && (!parkWithMemory || backend.hypervisor === 'virtualization')) {
         throw new DeskError('Copy-on-write restore requires Cloud Hypervisor and parkWithMemory.');
     }
@@ -105,6 +109,7 @@ export function createDeskHost(options) {
     const queue = [];
     let occupied = 0;
     let nextCid = positiveInteger(options.cidBase ?? DEFAULT_CID_BASE, 'cidBase');
+    const cidOwners = new Map();
     let lastStartedAt = null;
     let lastSuspendedAt = null;
     let lastError = null;
@@ -293,7 +298,26 @@ export function createDeskHost(options) {
     function snapshotDirFor(overlayPath, deskId) {
         return join(dirname(overlayPath), `${deskId}.snapshot`);
     }
-    async function teardown(record, keepMemory = true) {
+    function strictMemory(start) {
+        return Boolean(options.strictMemoryRestore || start.strictMemoryRestore || start.template
+            || (start.memoryRestoreMode ?? options.memoryRestoreMode) === 'ondemand');
+    }
+    async function clearRestoreMarker(snapshotDir) {
+        await rm(`${snapshotDir}.restore-pending`, { force: true });
+        const parent = await open(dirname(snapshotDir), 'r');
+        try {
+            await parent.sync();
+        }
+        finally {
+            await parent.close();
+        }
+    }
+    async function teardown(record, keepMemory = true, hooks) {
+        let sidecarFailed = false;
+        if (hooks) {
+            const supplied = hooks;
+            hooks = { ...supplied, onPausedError: error => { sidecarFailed = true; supplied.onPausedError?.(error); } };
+        }
         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.
@@ -361,6 +385,13 @@ export function createDeskHost(options) {
             // it is flushed exactly as a park is.
             if (parking || !keepMemory)
                 await syncGuest(record, machine);
+            if (hooks && (!parking || !machine.supportsPausedParkHook)) {
+                try {
+                    hooks.onPausedError?.(new DeskError('Paused park hooks are unavailable'));
+                }
+                catch { /* preserve memory */ }
+                hooks = undefined;
+            }
             try {
                 if (parking) {
                     const snapshotDir = snapshotDirFor(record.startOptions.overlayPath, record.deskId);
@@ -385,9 +416,60 @@ export function createDeskHost(options) {
                             await directory.close();
                         }
                     }
-                    await machine.park(snapshotDir);
+                    if (hooks?.beforePark) {
+                        try {
+                            await hooks.beforePark(machine);
+                        }
+                        catch (error) {
+                            try {
+                                hooks.onPausedError?.(error);
+                            }
+                            catch { /* preserve memory */ }
+                            ;
+                            hooks = undefined;
+                        }
+                    }
+                    await machine.park(snapshotDir, hooks);
                     const signature = await (options.cpuSignature ?? hostCpuSignature)();
                     await (options.writeSnapshotSignature ?? writeSnapshotSignature)(snapshotDir, signature);
+                    if (strictMemory(record.startOptions) || (hooks?.onParked && !sidecarFailed)) {
+                        for (const name of ['config.json', 'state.json', 'memory-ranges', 'appkit-cpu-signature']) {
+                            const file = await open(join(snapshotDir, name), 'r');
+                            try {
+                                await file.sync();
+                            }
+                            finally {
+                                await file.close();
+                            }
+                        }
+                        const directory = await open(snapshotDir, 'r');
+                        try {
+                            await directory.sync();
+                        }
+                        finally {
+                            await directory.close();
+                        }
+                        const parent = await open(dirname(snapshotDir), 'r');
+                        try {
+                            await parent.sync();
+                        }
+                        finally {
+                            await parent.close();
+                        }
+                        if (strictMemory(record.startOptions))
+                            await clearRestoreMarker(snapshotDir);
+                    }
+                    if (hooks?.onParked && !sidecarFailed) {
+                        try {
+                            await hooks.onParked(snapshotDir);
+                        }
+                        catch (error) {
+                            try {
+                                hooks.onPausedError?.(error);
+                            }
+                            catch { /* preserve memory */ }
+                        }
+                    }
                 }
                 else {
                     await machine.shutdown();
@@ -404,7 +486,7 @@ export function createDeskHost(options) {
                     record.machine = machine;
                     throw new DeskError(`Desk ${record.deskId} could not stop after teardown failed: ${errorMessage(stopError)}`);
                 }
-                if (parking) {
+                if (parking && !strictMemory(record.startOptions)) {
                     await removeSnapshot(snapshotDirFor(record.startOptions.overlayPath, record.deskId)).catch(() => undefined);
                 }
             }
@@ -473,10 +555,33 @@ export function createDeskHost(options) {
         // as whatever the overlay copy fails with.
         await admitDisk(startOptions.overlayPath);
         const snapshotDir = snapshotDirFor(startOptions.overlayPath, deskId);
+        const strictRestore = strictMemory(startOptions);
+        const restoreMode = startOptions.template ? 'copyonwrite' : startOptions.memoryRestoreMode ?? options.memoryRestoreMode;
+        if ((strictRestore || restoreMode) && (!parkWithMemory || backend.hypervisor === 'virtualization'))
+            throw new DeskError('Strict or copy-on-write restore requires Cloud Hypervisor and parkWithMemory.');
+        if (strictRestore && existsSync(`${snapshotDir}.restore-pending`)) {
+            throw new DeskError(`Desk ${deskId} has an interrupted memory restore; operator recovery is required.`);
+        }
         // The SAME cid for both attempts below. A restored VM's snapshotted config
         // 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++;
+        let cid;
+        if (startOptions.vsockCid !== undefined) {
+            cid = startOptions.vsockCid;
+            if (!Number.isSafeInteger(cid) || cid < 3 || cid > 0xfffffffe)
+                throw new DeskError('Invalid guest vsock CID.');
+            const owner = cidOwners.get(cid);
+            if (owner !== undefined && owner !== deskId)
+                throw new DeskError('Guest vsock CID is already assigned.');
+        }
+        else {
+            while (cidOwners.has(nextCid))
+                nextCid++;
+            cid = nextCid++;
+            if (cid > 0xfffffffe)
+                throw new DeskError('Guest vsock CID space exhausted.');
+        }
+        cidOwners.set(cid, deskId);
         const initramfsPath = startOptions.initramfsPath ?? resolveInitramfsPath();
         let restoreDir = snapshotDir;
         const planFor = (restore, shares = startOptions.shares) => buildDeskLaunchPlan({
@@ -505,8 +610,8 @@ export function createDeskHost(options) {
             ...(kernelCmdline === undefined ? {} : { kernelCmdline }),
             launcherIdentity: options.launcherIdentity,
             snapshotDir: restore ? restoreDir : snapshotDir,
-            ...(restore ? { restore: true, ...(options.memoryRestoreMode ? { memoryRestoreMode: options.memoryRestoreMode } : {}) } : {}),
-        }, { pathExists, deviceExists, ...(options.isDirectory ? { isDirectory: options.isDirectory } : {}) });
+            ...(restore ? { restore: true, ...(restoreMode ? { memoryRestoreMode: restoreMode } : {}) } : {}),
+        }, { pathExists: (path) => Boolean(startOptions.template && path === dirname(startOptions.overlayPath)) || pathExists(path), deviceExists, ...(options.isDirectory ? { isDirectory: options.isDirectory } : {}) });
         const restorePlan = async () => {
             const parked = await (options.readSnapshotShares ?? readShareManifest)(restoreDir);
             try {
@@ -524,14 +629,51 @@ export function createDeskHost(options) {
             if (hash.digest('hex') !== image.sha256)
                 throw new DeskError(`Read-only attachment digest mismatch: ${image.path}`);
         }
+        let initializeTemplate = false;
+        if (startOptions.template) {
+            if (!strictRestore || restoreMode !== 'copyonwrite' || backend.hypervisor === 'virtualization') {
+                throw new DeskError('Template forks require strict Cloud Hypervisor copy-on-write restore.');
+            }
+            const childDir = dirname(startOptions.overlayPath);
+            const prepared = join(childDir, '.prepared');
+            const initialized = join(childDir, '.initialized');
+            if (existsSync(initialized) && !existsSync(snapshotDir))
+                throw new DeskError('Template descendant has no saved memory; recovery is required.');
+            if (existsSync(initialized))
+                await startOptions.template.verifyResume(planFor(true));
+            if (!existsSync(initialized)) {
+                await startOptions.template.holdFence();
+                if (!existsSync(prepared)) {
+                    if (existsSync(startOptions.overlayPath) || existsSync(snapshotDir))
+                        throw new DeskError('Incomplete template fork needs recovery.');
+                    await startOptions.template.prepare(planFor(false));
+                }
+                if (await readFile(prepared, 'utf8') !== '1\n' || !existsSync(startOptions.overlayPath) || !existsSync(snapshotDir))
+                    throw new DeskError('Template fork was not prepared completely.');
+                const planned = planFor(true);
+                if (planned.hypervisor !== 'cloud-hypervisor')
+                    throw new DeskError('Template fork requires Cloud Hypervisor.');
+                const savedConfig = JSON.parse(await readFile(join(snapshotDir, 'config.json'), 'utf8'));
+                if (savedConfig.disks?.[0]?.path !== startOptions.overlayPath || savedConfig.net?.[0]?.tap !== planned.tap.device
+                    || savedConfig.net?.[0]?.mac?.toLowerCase() !== planned.tap.mac.toLowerCase()
+                    || savedConfig.vsock?.cid !== planned.vsock.cid || savedConfig.vsock.socket !== planned.vsock.socketPath
+                    || savedConfig.memory?.size !== planned.memoryMb * 1024 * 1024 || savedConfig.cpus?.boot_vcpus !== planned.vcpus) {
+                    throw new DeskError('Prepared template device or resource identity does not match its launch plan.');
+                }
+                await startOptions.template.verifyPrepared(planned);
+                initializeTemplate = true;
+            }
+        }
         let resuming = parkWithMemory && pathExists(snapshotDir);
+        if (initializeTemplate && !resuming)
+            throw new DeskError('A template fork requires its prepared snapshot.');
         // 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 (restoreMode) {
             if (startOptions.shares?.length)
-                throw new DeskError('Copy-on-write restore cannot be combined with virtio-fs shares.');
+                throw new DeskError('Copy-on-write or on-demand 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.');
+                throw new DeskError('The parked snapshot has virtio-fs shares and cannot use copy-on-write or on-demand restore.');
             }
         }
         if (resuming) {
@@ -548,31 +690,84 @@ export function createDeskHost(options) {
                 throw new DeskError('Snapshot read-only attachment identity does not match; restore requires the original images.');
             }
             const saved = await (options.readSnapshotSignature ?? readSnapshotSignature)(snapshotDir);
+            if (strictRestore && saved === null)
+                throw new DeskError(`Desk ${deskId} snapshot has no CPU identity.`);
             if (saved !== null && saved !== await (options.cpuSignature ?? hostCpuSignature)()) {
+                if (strictRestore)
+                    throw new DeskError(`Desk ${deskId} snapshot CPU identity does not match.`);
                 await removeSnapshot(snapshotDir);
                 resuming = false;
                 recordCpuFallback(deskId, 'signature_mismatch');
             }
         }
+        if (strictRestore) {
+            const marker = await open(`${snapshotDir}.restore-pending`, 'wx', 0o600);
+            try {
+                await marker.writeFile('restore in progress\n');
+                await marker.sync();
+            }
+            finally {
+                await marker.close();
+            }
+            const parent = await open(dirname(snapshotDir), 'r');
+            try {
+                await parent.sync();
+            }
+            finally {
+                await parent.close();
+            }
+        }
         // 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') {
+        if (resuming && restoreMode) {
             restoreDir = `${snapshotDir}.source-${randomUUID()}`;
             await retireSnapshot(snapshotDir, restoreDir);
         }
         let machine;
         try {
+            const launchPlan = resuming ? await restorePlan() : planFor(false);
+            if (resuming && (startOptions.template || (startOptions.strictMemoryRestore && restoreMode === 'copyonwrite')))
+                launchPlan.snapshot.requirePrivateMemoryMapping = true;
             machine = resuming
-                ? await backend.boot(await restorePlan(), {
+                ? await backend.boot(launchPlan, {
                     // 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),
+                    onRestored: restoreMode ? async () => { } : () => removeSnapshot(snapshotDir),
                 })
-                : await backend.boot(planFor(false));
+                : await backend.boot(launchPlan);
+            if (initializeTemplate && startOptions.template) {
+                try {
+                    await startOptions.template.initialize(machine, launchPlan);
+                    const initialized = await open(join(dirname(startOptions.overlayPath), '.initialized'), 'wx', 0o600);
+                    try {
+                        await initialized.writeFile('1\n');
+                        await initialized.sync();
+                    }
+                    finally {
+                        await initialized.close();
+                    }
+                    const directory = await open(dirname(startOptions.overlayPath), 'r');
+                    try {
+                        await directory.sync();
+                    }
+                    finally {
+                        await directory.close();
+                    }
+                    await startOptions.template.releaseFence();
+                }
+                catch (error) {
+                    await machine.shutdown();
+                    throw error;
+                }
+            }
         }
         catch (error) {
             if (resuming) {
+                if (strictRestore) {
+                    lastError = `Desk ${deskId} memory restore failed: ${errorMessage(error)}`;
+                    throw new DeskError(lastError);
+                }
                 // A snapshot that will not come back is worse than no snapshot: it makes
                 // the desk unbootable for as long as it sits there. Drop it and cold
                 // boot. Safe by construction — the guest never ran, so the disk is
@@ -594,7 +789,7 @@ export function createDeskHost(options) {
                     : new DeskError(`Desk ${deskId} failed to boot: ${errorMessage(error)}`);
             }
         }
-        if (resuming && options.memoryRestoreMode === 'copyonwrite') {
+        if (resuming && restoreMode) {
             // 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;
@@ -610,7 +805,7 @@ export function createDeskHost(options) {
             };
             restored.shutdown = async () => { await stop(); await releaseSource(); };
             if (park)
-                restored.park = async (dir) => { await park(dir); await releaseSource(); };
+                restored.park = async (dir, hooks) => { await park(dir, hooks); await releaseSource(); };
         }
         let record = records.get(deskId);
         if (!record) {
@@ -1331,13 +1526,13 @@ export function createDeskHost(options) {
             return admit(() => boot(record.deskId, record.startOptions));
         });
     }
-    async function suspend(deskId) {
+    async function suspend(deskId, hooks) {
         const id = cleanDeskId(deskId);
         await serializeLifecycle(id, async () => {
             const record = records.get(id);
             if (!record)
                 return;
-            await teardown(record);
+            await teardown(record, true, hooks);
         });
     }
     async function shutdown(deskId) {
@@ -1350,7 +1545,10 @@ export function createDeskHost(options) {
             // A desk parked earlier still has its memory image on disk; dropping it is
             // what makes the next boot cold. The overlay is untouched — only `destroy`
             // may remove it.
-            await removeSnapshot(snapshotDirFor(record.startOptions.overlayPath, record.deskId));
+            const snapshot = snapshotDirFor(record.startOptions.overlayPath, record.deskId);
+            await removeSnapshot(snapshot);
+            if (strictMemory(record.startOptions))
+                await clearRestoreMarker(snapshot);
         });
     }
     /**