@braedonsaunders/appkit-desk 0.6.0 → 0.8.0

package/host.js

@@ -10,11 +10,12 @@
  */
 import { existsSync } from 'node:fs';
 import { execFile } from 'node:child_process';
-import { mkdir, rm, statfs, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
+import { mkdir, readFile, rm, statfs, writeFile } from 'node:fs/promises';
+import { arch, cpus, release, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { Buffer } from 'node:buffer';
+import { connect as tcpConnect, isIP } from 'node:net';
 import { buildDeskLaunchPlan, cleanDeskId, DEFAULT_KVM_PATH, DEFAULT_VMM_PATH, DeskError, } from './plan.js';
 import { cloudHypervisorBackend, } from './backend.js';
 import { parseCapabilities, parseClipboardText, parseExecResult, parseHandoverBegun, parseJobStarted, parseObservation, } from './protocol.js';
@@ -76,7 +77,7 @@ export function createDeskHost(options) {
     // cloud kernel boots without every caller having to name it; an explicit
     // option always wins.
     const defaultInitramfs = join(options.imageRoot, 'initrd');
-    const initramfsPath = options.initramfsPath ?? (pathExists(defaultInitramfs) ? defaultInitramfs : undefined);
+    const resolveInitramfsPath = () => options.initramfsPath ?? (pathExists(defaultInitramfs) ? defaultInitramfs : undefined);
     const kernelCmdline = options.kernelCmdline;
     const records = new Map();
     /**
@@ -93,6 +94,8 @@ export function createDeskHost(options) {
     let lastStartedAt = null;
     let lastSuspendedAt = null;
     let lastError = null;
+    let snapshotCpuFallbacks = 0;
+    let lastSnapshotCpuFallback = null;
     let reconnects = 0;
     let lastReconnectAt = null;
     let lastReconnectDeskId = null;
@@ -276,13 +279,16 @@ export function createDeskHost(options) {
     function snapshotDirFor(overlayPath, deskId) {
         return join(dirname(overlayPath), `${deskId}.snapshot`);
     }
-    async function teardown(record) {
+    async function teardown(record, keepMemory = true) {
         if (record.status !== 'resident')
             return false;
         await endHandover(record, 'revoked');
         for (const stop of [...record.streamStops])
             stop();
         record.streamStops.clear();
+        for (const stop of record.relayStops)
+            stop();
+        record.relayStops.clear();
         if (record.screen?.running) {
             record.screen.running = false;
             emit(record, { kind: 'screen_close' });
@@ -318,14 +324,18 @@ export function createDeskHost(options) {
             // the disk alone is exactly what is left whenever a snapshot is discarded,
             // which happens on every failed restore. Syncing first makes discarding a
             // snapshot always safe instead of usually safe.
-            const parking = parkWithMemory && typeof machine.park === 'function';
-            if (parking)
+            const parking = keepMemory && parkWithMemory && typeof machine.park === 'function';
+            // A shutdown that throws memory away leaves the disk as the only state, so
+            // it is flushed exactly as a park is.
+            if (parking || !keepMemory)
                 await syncGuest(record, machine);
             try {
                 if (parking) {
                     const snapshotDir = snapshotDirFor(record.startOptions.overlayPath, record.deskId);
                     await makeSnapshotDir(snapshotDir);
                     await machine.park(snapshotDir);
+                    const signature = await (options.cpuSignature ?? hostCpuSignature)();
+                    await (options.writeSnapshotSignature ?? writeSnapshotSignature)(snapshotDir, signature);
                 }
                 else {
                     await machine.shutdown();
@@ -409,8 +419,11 @@ 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 planFor = (restore) => buildDeskLaunchPlan({
             deskId,
+            hypervisor: backend.hypervisor ?? 'cloud-hypervisor',
+            ...(backend.hypervisor === 'virtualization' ? { guestNetwork: options.guestNetwork } : {}),
             vmmPath: options.vmmPath,
             kvmPath: options.kvmPath,
             kernelPath,
@@ -430,7 +443,15 @@ export function createDeskHost(options) {
             snapshotDir,
             ...(restore ? { restore: true } : {}),
         }, { pathExists, deviceExists });
-        const resuming = parkWithMemory && pathExists(snapshotDir);
+        let resuming = parkWithMemory && pathExists(snapshotDir);
+        if (resuming) {
+            const saved = await (options.readSnapshotSignature ?? readSnapshotSignature)(snapshotDir);
+            if (saved !== null && saved !== await (options.cpuSignature ?? hostCpuSignature)()) {
+                await removeSnapshot(snapshotDir);
+                resuming = false;
+                recordCpuFallback(deskId, 'signature_mismatch');
+            }
+        }
         let machine;
         try {
             machine = resuming
@@ -450,8 +471,11 @@ 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);
-                await removeSnapshot(snapshotDir).catch(() => undefined);
-                lastError = `Desk ${deskId} could not resume from its snapshot and was cold booted: ${why}`;
+                await removeSnapshot(snapshotDir);
+                if (isIncompatibleCpuSnapshotError(error))
+                    recordCpuFallback(deskId, 'incompatible_cpuid');
+                else
+                    lastError = `Desk ${deskId} could not resume from its snapshot and was cold booted: ${why}`;
                 // Falls through to the shared record path below with a cold machine.
                 machine = await backend.boot(planFor(false));
             }
@@ -479,6 +503,7 @@ export function createDeskHost(options) {
                 handle: null,
                 timer: null,
                 streamStops: new Set(),
+                relayStops: new Set(),
             };
             records.set(deskId, record);
         }
@@ -490,6 +515,7 @@ export function createDeskHost(options) {
             record.jobs = new Map();
             record.screen = null;
             record.streamStops = new Set();
+            record.relayStops = new Set();
         }
         const current = record;
         const epoch = current.epoch;
@@ -735,6 +761,33 @@ export function createDeskHost(options) {
                 touch(record);
                 armTimer(record);
             },
+            async connect(port) {
+                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))
+                    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);
+                    try {
+                        requireMachine(record, epoch);
+                    }
+                    catch (error) {
+                        stream.destroy();
+                        throw error;
+                    }
+                    const stop = () => stream.destroy();
+                    record.relayStops.add(stop);
+                    stream.once('close', () => record.relayStops.delete(stop));
+                    return stream;
+                }
+                catch (error) {
+                    throw new DeskError(`Cannot connect to guest ${address}:${port}: ${errorMessage(error)}`);
+                }
+            },
             exec: execImplementation,
             jobs() {
                 return [...record.jobs.values()]
@@ -1121,6 +1174,19 @@ export function createDeskHost(options) {
             await teardown(record);
         });
     }
+    async function shutdown(deskId) {
+        const id = cleanDeskId(deskId);
+        await serializeLifecycle(id, async () => {
+            const record = records.get(id);
+            if (!record)
+                return;
+            await teardown(record, false);
+            // 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));
+        });
+    }
     /**
      * Delete a desk's overlay. The ONLY place in this module that removes a
      * desk's disk, and it is reachable from `destroy` alone — see the contract
@@ -1191,6 +1257,11 @@ export function createDeskHost(options) {
         }
         return suspendedCount;
     }
+    function recordCpuFallback(deskId, reason) {
+        snapshotCpuFallbacks += 1;
+        lastSnapshotCpuFallback = { deskId, reason, at: iso(now()) };
+        ports.onEvent({ kind: 'snapshot_cpu_fallback', deskId, reason, at: iso(now()) });
+    }
     function stats() {
         let suspended = 0;
         for (const record of records.values()) {
@@ -1208,12 +1279,15 @@ export function createDeskHost(options) {
             lastReconnectAt,
             lastReconnectDeskId,
             lastError,
+            snapshotCpuFallbacks,
+            lastSnapshotCpuFallback,
         };
     }
-    return { start, resume, suspend, destroy, stats, sweep };
+    return { start, resume, suspend, shutdown, destroy, stats, sweep };
 }
 /**
  * Whether the overlay directory's filesystem can make reflink clones.
+ * On macOS this probes APFS cloning with `cp -c`. On Linux:
  *
  * This exists because `cp --reflink=auto` — what `buildDeskLaunchPlan` uses,
  * deliberately, so a desk still boots on a filesystem without reflink — is
@@ -1246,7 +1320,7 @@ export async function verifyOverlayReflink(options) {
                 + `support could not be determined: ${errorMessage(error)}`);
         }
         await copy(source, destination);
-        return { supported: true, overlayDirectory, detail: 'cp --reflink=always succeeded.' };
+        return { supported: true, overlayDirectory, detail: process.platform === 'darwin' ? 'cp -c succeeded.' : 'cp --reflink=always succeeded.' };
     }
     catch (error) {
         if (error instanceof DeskError)
@@ -1265,16 +1339,18 @@ export async function verifyOverlayReflink(options) {
 export async function assertOverlayReflink(options) {
     const check = await verifyOverlayReflink(options);
     if (!check.supported) {
-        throw new DeskError(`The overlay directory ${check.overlayDirectory} is on a filesystem without reflink `
-            + 'support, so every desk would FULL-COPY the base image instead of sharing its '
-            + 'blocks — gigabytes and minutes per desk, and a disk sized for sharing fills after '
-            + `a handful of them. Put the overlay directory on XFS or Btrfs. Probe said: ${check.detail}`);
+        throw new DeskError(process.platform === 'darwin'
+            ? `The overlay directory ${check.overlayDirectory} does not support cloning. Put it on APFS. Probe said: ${check.detail}`
+            : `The overlay directory ${check.overlayDirectory} is on a filesystem without reflink `
+                + 'support, so every desk would FULL-COPY the base image instead of sharing its '
+                + 'blocks — gigabytes and minutes per desk, and a disk sized for sharing fills after '
+                + `a handful of them. Put the overlay directory on XFS or Btrfs. Probe said: ${check.detail}`);
     }
     return check;
 }
 async function reflinkAlways(source, destination) {
     await new Promise((resolvePromise, rejectPromise) => {
-        execFile('cp', ['--reflink=always', source, destination], (error, _stdout, stderr) => {
+        execFile('cp', [process.platform === 'darwin' ? '-c' : '--reflink=always', source, destination], (error, _stdout, stderr) => {
             if (error) {
                 rejectPromise(new Error(stderr.trim() || errorMessage(error)));
                 return;
@@ -1297,13 +1373,14 @@ export async function verifyDeskHost(options) {
     const deviceExists = options.deviceExists ?? existsSync;
     const idFactory = options.idFactory ?? randomUUID;
     const backend = options.backend ?? cloudHypervisorBackend;
-    const vmmPath = options.vmmPath ?? DEFAULT_VMM_PATH;
+    const isVirtualization = backend.hypervisor === 'virtualization';
+    const vmmPath = options.vmmPath ?? backend.vmmPath ?? DEFAULT_VMM_PATH;
     const kvmPath = options.kvmPath ?? DEFAULT_KVM_PATH;
-    if (platform !== 'linux') {
-        throw new DeskError(`The AppKit desk requires Linux; received ${platform}.`);
+    if (platform !== (isVirtualization ? 'darwin' : 'linux')) {
+        throw new DeskError(isVirtualization ? `Virtualization requires macOS; received ${platform}.` : `The AppKit desk requires Linux; received ${platform}.`);
     }
     if (!pathExists(vmmPath)) {
-        throw new DeskError(`Cloud Hypervisor was not found at ${vmmPath}.`);
+        throw new DeskError(isVirtualization ? `Virtualization helper was not found at ${vmmPath}.` : `Cloud Hypervisor was not found at ${vmmPath}.`);
     }
     if (!pathExists(options.kernelPath)) {
         throw new DeskError(`Guest kernel does not exist: ${options.kernelPath}`);
@@ -1311,7 +1388,7 @@ export async function verifyDeskHost(options) {
     if (!pathExists(options.baseImagePath)) {
         throw new DeskError(`Base image does not exist: ${options.baseImagePath}`);
     }
-    if (!deviceExists(kvmPath)) {
+    if (!isVirtualization && !deviceExists(kvmPath)) {
         return { supported: false, vmmPath, kvm: false, vsock: false, virtioGpu: false };
     }
     const scratchDir = options.scratchDir ?? tmpdir();
@@ -1319,6 +1396,7 @@ export async function verifyDeskHost(options) {
     const overlayPath = join(scratchDir, `${deskId}.raw`);
     const plan = buildDeskLaunchPlan({
         deskId,
+        hypervisor: backend.hypervisor ?? 'cloud-hypervisor',
         vmmPath,
         kvmPath,
         kernelPath: options.kernelPath,
@@ -1365,7 +1443,7 @@ export async function verifyDeskHost(options) {
         }
         await rm(overlayPath, { force: true });
     }
-    return { supported: vsock, vmmPath, kvm: true, vsock, virtioGpu };
+    return { supported: vsock, vmmPath, kvm: !isVirtualization, vsock, virtioGpu };
 }
 function nonEmptyString(value, field) {
     if (typeof value !== 'string' || value.length === 0) {
@@ -1402,4 +1480,44 @@ async function defaultFreeBytes(path) {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+async function connectGuestTcp(address, port) {
+    return new Promise((resolve, reject) => {
+        const socket = tcpConnect({ host: address, port });
+        socket.setTimeout(10_000, () => socket.destroy(new Error('Guest TCP connection timed out.')));
+        socket.once('error', reject);
+        socket.once('connect', () => { socket.setTimeout(0); socket.removeListener('error', reject); resolve(socket); });
+    });
+}
+/** Cloud Hypervisor's specific restore error; do not classify generic CPUID mentions. */
+export function isIncompatibleCpuSnapshotError(error) {
+    return /Detected incompatible CPUID entry/.test(errorMessage(error));
+}
+/** Hash the host's CPU identity and advertised feature set, excluding per-core counters. */
+export async function hostCpuSignature() {
+    if (process.platform === 'darwin') {
+        const model = cpus()[0]?.model;
+        if (!model)
+            throw new DeskError('Cannot determine host CPU signature.');
+        return createHash('sha256').update(`darwin:${arch()}:${release()}:${model}`).digest('hex');
+    }
+    const cpuinfo = await readFile('/proc/cpuinfo', 'utf8');
+    const first = cpuinfo.split(/\n\s*\n/)[0] ?? '';
+    const identity = first.split('\n').filter((line) => /^(vendor_id|cpu family|model\s|model name|stepping|flags|microcode)\s*:/.test(line)).join('\n');
+    if (!identity)
+        throw new DeskError('Cannot determine host CPU signature.');
+    return createHash('sha256').update(identity).digest('hex');
+}
+async function readSnapshotSignature(directory) {
+    try {
+        return (await readFile(join(directory, 'appkit-cpu-signature'), 'utf8')).trim();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+async function writeSnapshotSignature(directory, signature) {
+    await writeFile(join(directory, 'appkit-cpu-signature'), signature, { mode: 0o600 });
+}
 //# sourceMappingURL=host.js.map