@braedonsaunders/appkit-desk 0.5.1 → 0.6.0

package/host.js

@@ -10,7 +10,7 @@
  */
 import { existsSync } from 'node:fs';
 import { execFile } from 'node:child_process';
-import { rm, statfs, writeFile } from 'node:fs/promises';
+import { mkdir, rm, statfs, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
@@ -59,6 +59,9 @@ export function createDeskHost(options) {
     const pathExists = options.pathExists ?? existsSync;
     const deviceExists = options.deviceExists ?? existsSync;
     const removeOverlay = options.removeOverlay ?? ((path) => rm(path, { force: true }));
+    const parkWithMemory = options.parkWithMemory ?? false;
+    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;
     const minFreeBytes = nonNegativeInteger(options.minFreeBytes ?? 0, 'minFreeBytes');
     const trimOnSuspend = options.trimOnSuspend ?? true;
@@ -251,6 +254,28 @@ export function createDeskHost(options) {
             lastError = `Trim before suspend failed for ${record.deskId}: ${errorMessage(error)}`;
         }
     }
+    /**
+     * Flush the guest's filesystem, immediately before it stops.
+     *
+     * Only needed when parking keeps memory. A snapshot always matches the disk it
+     * was taken with, so the pair is consistent either way — but the disk ON ITS
+     * OWN is not, and that is what remains every time a snapshot has to be
+     * discarded. Without this, discarding one leaves a filesystem mid-transaction
+     * and the next cold boot recovers a journal and loses the last writes. Best
+     * effort and bounded: a guest too wedged to sync must still be parked.
+     */
+    async function syncGuest(record, machine) {
+        try {
+            await machine.request({ op: 'exec', command: 'sync', args: [], timeoutMs: trimTimeoutMs });
+        }
+        catch (error) {
+            lastError = `Sync before park failed for ${record.deskId}: ${errorMessage(error)}`;
+        }
+    }
+    /** Where this desk's memory snapshot lives; must agree with the launch plan. */
+    function snapshotDirFor(overlayPath, deskId) {
+        return join(dirname(overlayPath), `${deskId}.snapshot`);
+    }
     async function teardown(record) {
         if (record.status !== 'resident')
             return false;
@@ -286,11 +311,34 @@ export function createDeskHost(options) {
         record.handle = null;
         if (machine) {
             await trimGuest(record, machine);
+            // Flush the guest's filesystem before anything stops.
+            //
+            // A paused guest still holds dirty pages that exist only in its memory, so
+            // a snapshot is consistent with the disk but the DISK ALONE is not — and
+            // 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)
+                await syncGuest(record, machine);
             try {
-                await machine.shutdown();
+                if (parking) {
+                    const snapshotDir = snapshotDirFor(record.startOptions.overlayPath, record.deskId);
+                    await makeSnapshotDir(snapshotDir);
+                    await machine.park(snapshotDir);
+                }
+                else {
+                    await machine.shutdown();
+                }
             }
             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.
                 lastError = errorMessage(error);
+                if (parking) {
+                    await removeSnapshot(snapshotDirFor(record.startOptions.overlayPath, record.deskId)).catch(() => undefined);
+                }
             }
         }
         lastSuspendedAt = iso(now());
@@ -356,7 +404,12 @@ export function createDeskHost(options) {
         // Before the plan, so a full disk is reported as a full disk rather than
         // as whatever the overlay copy fails with.
         await admitDisk(startOptions.overlayPath);
-        const plan = buildDeskLaunchPlan({
+        const snapshotDir = snapshotDirFor(startOptions.overlayPath, deskId);
+        // 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++;
+        const planFor = (restore) => buildDeskLaunchPlan({
             deskId,
             vmmPath: options.vmmPath,
             kvmPath: options.kvmPath,
@@ -366,7 +419,7 @@ export function createDeskHost(options) {
             overlayPath: startOptions.overlayPath,
             memoryMb: startOptions.memoryMb,
             vcpus: startOptions.vcpus,
-            vsockCid: nextCid++,
+            vsockCid: cid,
             runtimeDir: options.runtimeDir,
             tapDevice: startOptions.network?.tapDevice,
             macAddress: startOptions.network?.macAddress,
@@ -374,16 +427,40 @@ export function createDeskHost(options) {
             // back to DEFAULT_KERNEL_CMDLINE.
             ...(kernelCmdline === undefined ? {} : { kernelCmdline }),
             launcherIdentity: options.launcherIdentity,
+            snapshotDir,
+            ...(restore ? { restore: true } : {}),
         }, { pathExists, deviceExists });
+        const resuming = parkWithMemory && pathExists(snapshotDir);
         let machine;
         try {
-            machine = await backend.boot(plan);
+            machine = resuming
+                ? await backend.boot(planFor(true), {
+                    // 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),
+                })
+                : await backend.boot(planFor(false));
         }
         catch (error) {
-            lastError = errorMessage(error);
-            throw error instanceof DeskError
-                ? error
-                : new DeskError(`Desk ${deskId} failed to boot: ${errorMessage(error)}`);
+            if (resuming) {
+                // 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
+                // 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}`;
+                // Falls through to the shared record path below with a cold machine.
+                machine = await backend.boot(planFor(false));
+            }
+            else {
+                lastError = errorMessage(error);
+                throw error instanceof DeskError
+                    ? error
+                    : new DeskError(`Desk ${deskId} failed to boot: ${errorMessage(error)}`);
+            }
         }
         let record = records.get(deskId);
         if (!record) {
@@ -1061,6 +1138,19 @@ export function createDeskHost(options) {
         catch (error) {
             lastError = `Overlay was not reclaimed for ${record.deskId}: ${errorMessage(error)}`;
         }
+        // The snapshot goes with the disk, always — not only when parking is on.
+        //
+        // A snapshot outliving its overlay is the worst state this feature can
+        // produce: the next desk created under the same id gets a FRESH overlay and
+        // would restore a previous desk's memory on top of it. That is not stale
+        // state, it is one machine's RAM over another machine's disk. Teardown just
+        // ran, so nothing holds it open.
+        try {
+            await removeSnapshot(snapshotDirFor(record.startOptions.overlayPath, record.deskId));
+        }
+        catch (error) {
+            lastError = `Snapshot was not reclaimed for ${record.deskId}: ${errorMessage(error)}`;
+        }
     }
     async function destroy(deskId) {
         const id = cleanDeskId(deskId);