@tikoci/quickchr 0.5.0 → 0.5.1

package/src/lib/disk.ts

@@ -12,11 +12,12 @@
  *  - {@link formatSnapshotTable} — render snapshot list as a human-readable ANSI table
  */
 
-import { join } from "node:path";
-import { existsSync, unlinkSync } from "node:fs";
+import { basename, join } from "node:path";
+import { copyFileSync, existsSync, rmSync, unlinkSync } from "node:fs";
 import type { BootDiskFormat, SnapshotInfo } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
 import { requireQemuImg } from "./platform.ts";
+import { renameWithRetry } from "./rename.ts";
 
 const DISK_SIZE_RE = /^\d+[KMGT]?$/i;
 
@@ -25,6 +26,8 @@ export interface DiskInfo {
 	virtualSize: number;
 	actualSize: number;
 	filename: string;
+	/** Set when the image depends on another file (a qcow2 backing chain). */
+	backingFilename?: string;
 }
 
 /** True when a disk size string is valid for qemu-img (e.g. 512M, 1G, 2048). */
@@ -139,34 +142,58 @@ export async function getDiskInfo(path: string): Promise<DiskInfo> {
 		virtualSize: info["virtual-size"],
 		actualSize: info["actual-size"],
 		filename: info.filename,
+		backingFilename: info["backing-filename"],
 	};
 }
 
+/** The boot format a machine record implies. Records from before `bootDiskFormat`
+ *  existed only had `bootSize`, which always meant qcow2. */
+export function bootDiskFormatOf(state: { bootDiskFormat?: BootDiskFormat; bootSize?: string }): BootDiskFormat {
+	return state.bootDiskFormat ?? (state.bootSize ? "qcow2" : "raw");
+}
+
+/** Where a machine's boot disk lives: `disk.img` for raw, `boot.qcow2` for qcow2. */
+export function bootDiskPath(machineDir: string, format: BootDiskFormat): string {
+	return join(machineDir, format === "qcow2" ? "boot.qcow2" : "disk.img");
+}
+
 /**
- * Prepare the boot disk for a machine.
- * If bootSize is specified, converts the raw disk.img to boot.qcow2 and resizes it.
- * Otherwise returns the raw disk.img as-is.
+ * Write a machine's boot disk from a factory raw image, replacing any existing one.
+ *
+ * The disk is built under a `.tmp` name and renamed into place only once complete, so
+ * an interrupted copy or conversion never leaves a file the next start would accept.
+ * qcow2 is converted straight from `sourceImg` (normally the shared cache image) and
+ * checked to be standalone: no machine-local raw copy is kept, and no guest disk
+ * depends on the cache through a backing chain.
  */
-export async function prepareBootDisk(
+export async function writeBootDisk(
 	machineDir: string,
+	sourceImg: string,
+	format: BootDiskFormat,
 	bootSize?: string,
-	bootDiskFormat?: BootDiskFormat,
 ): Promise<{ path: string; format: BootDiskFormat }> {
-	const format: BootDiskFormat = bootDiskFormat ?? (bootSize ? "qcow2" : "raw");
-	const rawPath = join(machineDir, "disk.img");
-
-	if (format === "raw") {
-		return { path: rawPath, format: "raw" };
-	}
-
-	const qcow2Path = join(machineDir, "boot.qcow2");
-	if (!existsSync(qcow2Path)) {
-		await convertRawToQcow2(rawPath, qcow2Path);
-	}
-	if (bootSize) {
-		await resizeQcow2(qcow2Path, bootSize);
+	const path = bootDiskPath(machineDir, format);
+	const tmpPath = `${path}.tmp`;
+	rmSync(tmpPath, { force: true });
+	try {
+		if (format === "raw") {
+			copyFileSync(sourceImg, tmpPath);
+		} else {
+			await convertRawToQcow2(sourceImg, tmpPath);
+			if (bootSize) await resizeQcow2(tmpPath, bootSize);
+			const info = await getDiskInfo(tmpPath);
+			if (info.format !== "qcow2" || info.backingFilename) {
+				throw new QuickCHRError(
+					"PROCESS_FAILED",
+					`Converted boot disk is not a standalone qcow2 (format=${info.format}${info.backingFilename ? `, backing=${info.backingFilename}` : ""})`,
+				);
+			}
+		}
+		renameWithRetry(tmpPath, path);
+	} finally {
+		rmSync(tmpPath, { force: true });
 	}
-	return { path: qcow2Path, format: "qcow2" };
+	return { path, format };
 }
 
 /**
@@ -186,24 +213,53 @@ export async function prepareExtraDisks(
 	return results;
 }
 
-/** Ensure disk artifacts referenced by machine state exist on disk.
- *  Used both for new-machine creation and to heal older add()-created states
- *  that predate eager disk materialization. */
+export interface DiskSources {
+	/** True once the guest has booted. Its disks then hold guest state, so a missing one
+	 *  is an error: rebuilding it from the factory image would quietly reset the router. */
+	booted: boolean;
+	/** The factory raw image a missing boot disk of a never-booted machine is built from.
+	 *  Called only when it is needed. */
+	factoryImage?: () => Promise<string>;
+}
+
+function missingDiskError(machineDir: string, path: string): QuickCHRError {
+	const name = basename(machineDir);
+	return new QuickCHRError(
+		"MACHINE_NOT_FOUND",
+		`Disk image not found for "${name}": ${path}. The machine has booted before, so quickchr will not rebuild it from the factory image — that would silently reset the router. Restore the file, or run 'quickchr clean ${name}' to reset it to factory.`,
+	);
+}
+
+/** Resolve the disks a machine record calls for, creating any that a never-booted
+ *  machine is still missing. New machines, and older add()-created states that predate
+ *  eager disk materialization, are built here; a booted machine's disks never are.
+ *
+ *  A qcow2 machine needs only `boot.qcow2`. Machines created before 0.5.1 also hold a
+ *  `disk.img`; it is unused once `boot.qcow2` exists, and is the conversion source for a
+ *  legacy never-booted state that has no `boot.qcow2` yet. */
 export async function ensureConfiguredDisks(
 	machineDir: string,
-	bootSize?: string,
-	extraDiskSizes?: string[],
-	bootDiskFormat?: BootDiskFormat,
+	bootSize: string | undefined,
+	extraDiskSizes: string[] | undefined,
+	bootDiskFormat: BootDiskFormat,
+	sources: DiskSources,
 ): Promise<{
 	bootDisk: { path: string; format: BootDiskFormat };
 	extraDisks?: { path: string; format: "qcow2" }[];
 }> {
-	const format: BootDiskFormat = bootDiskFormat ?? (bootSize ? "qcow2" : "raw");
-	const bootDisk = format === "raw"
-		? { path: join(machineDir, "disk.img"), format: "raw" as const }
-		: (existsSync(join(machineDir, "boot.qcow2"))
-			? { path: join(machineDir, "boot.qcow2"), format: "qcow2" as const }
-			: await prepareBootDisk(machineDir, bootSize, "qcow2"));
+	const bootPath = bootDiskPath(machineDir, bootDiskFormat);
+	let bootDisk = { path: bootPath, format: bootDiskFormat };
+	if (!existsSync(bootPath)) {
+		if (sources.booted) throw missingDiskError(machineDir, bootPath);
+		const legacyRaw = join(machineDir, "disk.img");
+		const source = bootDiskFormat === "qcow2" && existsSync(legacyRaw)
+			? legacyRaw
+			: await sources.factoryImage?.();
+		if (!source) {
+			throw new QuickCHRError("MACHINE_NOT_FOUND", `Disk image not found for "${basename(machineDir)}": ${bootPath}`);
+		}
+		bootDisk = await writeBootDisk(machineDir, source, bootDiskFormat, bootSize);
+	}
 
 	let extraDisks: { path: string; format: "qcow2" }[] | undefined;
 	if (extraDiskSizes && extraDiskSizes.length > 0) {
@@ -211,6 +267,7 @@ export async function ensureConfiguredDisks(
 		for (let i = 0; i < extraDiskSizes.length; i++) {
 			const diskPath = join(machineDir, `disk${i + 1}.qcow2`);
 			if (!existsSync(diskPath)) {
+				if (sources.booted) throw missingDiskError(machineDir, diskPath);
 				await createQcow2Disk(diskPath, extraDiskSizes[i] as string);
 			}
 			extraDisks.push({ path: diskPath, format: "qcow2" });

package/src/lib/download.ts

@@ -46,11 +46,12 @@
  * a transfer; it does not change the transport).
  */
 
-import { unlinkSync, existsSync, renameSync } from "node:fs";
+import { unlinkSync, existsSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { QuickCHRError } from "./types.ts";
 import { fetchResilient } from "./net.ts";
 import { createLogger, type ProgressLogger } from "./log.ts";
+import { renameWithRetry } from "./rename.ts";
 
 /**
  * Throughput to assume when budgeting a COLD download from MikroTik, in bytes
@@ -257,7 +258,7 @@ export async function downloadToFile(
 			// so this is a same-filesystem move and the artifact appears at its final
 			// path atomically. Copying would re-write every byte (52 MB for the
 			// largest artifact) for no benefit.
-			renameSync(partPath, destPath);
+			renameWithRetry(partPath, destPath);
 			log.status(`  Saved (${describeTransfer(outcome)})`);
 			return outcome;
 		} catch (e) {

package/src/lib/images.ts

@@ -2,7 +2,7 @@
  * Image download, ZIP extraction, and cache management.
  */
 
-import { existsSync, copyFileSync, mkdtempSync, readdirSync, renameSync, rmSync, unlinkSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, rmSync, unlinkSync, utimesSync } from "node:fs";
 import { join, basename } from "node:path";
 import type { Arch } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
@@ -11,7 +11,18 @@ import { downloadToFile } from "./download.ts";
 import { getCacheDir, ensureDir } from "./state.ts";
 import { createLogger, type ProgressLogger } from "./log.ts";
 import { extractZip } from "./zip.ts";
-import { assertSufficientQuickchrStorage } from "./storage.ts";
+import { admitStorage, STORAGE_ESTIMATES } from "./storage.ts";
+import { renameWithRetry } from "./rename.ts";
+
+/** A cache hit is a use: bump the mtime so automatic eviction counts the entry as
+ *  recently used while this operation reads it (#199). Best-effort: a read-only cache
+ *  still works. */
+export function touchCacheEntry(path: string): void {
+	try {
+		const now = new Date();
+		utimesSync(path, now, now);
+	} catch { /* read-only cache */ }
+}
 
 function finalizeExtractedImage(zipPath: string, imgPath: string): string {
 	if (existsSync(imgPath) && existsSync(zipPath)) {
@@ -118,7 +129,7 @@ export async function extractImage(
 		if (!(await isUsableCachedImage(extractedPath))) {
 			throw new QuickCHRError("PROCESS_FAILED", `Extracted CHR image is incomplete or invalid: ${expected}`);
 		}
-		renameSync(extractedPath, imgPath);
+		renameWithRetry(extractedPath, imgPath);
 	} finally {
 		rmSync(tempDir, { recursive: true, force: true });
 	}
@@ -138,21 +149,29 @@ export async function ensureCachedImage(
 	if (await isUsableCachedImage(imgPath)) {
 		const log = logger ?? createLogger();
 		log.status(`  Using cached image: ${chrImageBasename(version, arch)}`);
+		touchCacheEntry(imgPath);
 		return imgPath;
 	}
 	if (existsSync(imgPath)) unlinkSync(imgPath);
-	assertSufficientQuickchrStorage(`cache CHR ${version} (${arch})`);
-	const zipPath = await downloadImage(version, arch, cacheDir, logger);
-	const extractedImgPath = await extractImage(zipPath, cacheDir, logger);
-	return finalizeExtractedImage(zipPath, extractedImgPath);
-}
-
-/** Copy a cached image to a machine's working directory as disk.img. */
-export function copyImageToMachine(cachedImgPath: string, machineDir: string): string {
-	ensureDir(machineDir);
-	const dest = join(machineDir, "disk.img");
-	copyFileSync(cachedImgPath, dest);
-	return dest;
+	const log = logger ?? createLogger();
+	const base = chrImageBasename(version, arch);
+	const lease = admitStorage(
+		`cache CHR ${version} (${arch})`,
+		{
+			parts: [{ label: "image download", bytes: STORAGE_ESTIMATES.imageDownload, path: cache }],
+			protectVersions: [version],
+			pins: [`${base}.img`, `${base}.img.zip`],
+			cacheDir: cache,
+		},
+		{ logger: (message: string) => log.status(message) },
+	);
+	try {
+		const zipPath = await downloadImage(version, arch, cacheDir, logger);
+		const extractedImgPath = await extractImage(zipPath, cacheDir, logger);
+		return finalizeExtractedImage(zipPath, extractedImgPath);
+	} finally {
+		lease.release();
+	}
 }
 
 /** List cached images. */

package/src/lib/lock.ts

@@ -65,7 +65,8 @@ export type LockOperation =
 	| "remove"
 	| "device-mode"
 	| "remove-orphan"
-	| "allocate";
+	| "allocate"
+	| "storage";
 
 /** Resources a machine creation has claimed but not yet persisted in `machine.json`.
  *  Carried in the creator's machine lock, so it lives exactly as long as the create

package/src/lib/packages.ts

@@ -2,7 +2,7 @@
  * Extra package download and installation for CHR instances.
  */
 
-import { existsSync, mkdtempSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, rmSync, statSync } from "node:fs";
 import { join, basename } from "node:path";
 import { QuickCHRError, type Arch } from "./types.ts";
 import { packagesDownloadUrl } from "./versions.ts";
@@ -12,6 +12,10 @@ import { createLogger, type ProgressLogger } from "./log.ts";
 import { restPost } from "./rest.ts";
 import { scpPush } from "./scp.ts";
 import { extractZip } from "./zip.ts";
+import { renameWithRetry } from "./rename.ts";
+import { admitStorage, STORAGE_ESTIMATES } from "./storage.ts";
+import { touchCacheEntry } from "./images.ts";
+import { pinCacheEntries } from "./storage-lease.ts";
 
 const PACKAGE_CACHE_MANIFEST = ".quickchr-complete.json";
 
@@ -76,50 +80,65 @@ export async function downloadPackages(
 	if (await isCompletePackageCache(version, arch, cache)) {
 		const log = logger ?? createLogger();
 		log.status(`  Using cached packages: ${version} (${arch})`);
+		touchCacheEntry(zipPath);
 		return extractDir;
 	}
 
-	// Download if needed. Same bounded path as the image download (#116) — this
-	// call site previously had neither a deadline nor retries, so its only bound
-	// was whatever the calling test happened to impose.
-	if (!existsSync(zipPath)) {
-		const log = logger ?? createLogger();
-		log.status(`Downloading packages for ${version} (${arch})...`);
-		log.status(`  ${url}`);
-		await downloadToFile(url, zipPath, { logger: log });
-	}
-
-	// Extract into a sibling directory, record the exact complete set, then
-	// rename it into place. A killed extraction can never look like a cache hit.
-	const tempDir = mkdtempSync(join(cache, ".quickchr-packages-"));
+	const lease = admitStorage(
+		`cache packages ${version} (${arch})`,
+		{
+			parts: [{ label: "packages download", bytes: STORAGE_ESTIMATES.packagesDownload, path: cache }],
+			protectVersions: [version],
+			pins: [`packages-${arch}-${version}`],
+			cacheDir: cache,
+		},
+		{ logger: (message: string) => (logger ?? createLogger()).status(message) },
+	);
 	try {
-		extractZip(zipPath, tempDir);
-		const packages = packageFiles(tempDir);
-		if (packages.length === 0) {
-			throw new Error(`No non-empty .npk files found in ${zipName}`);
+		// Download if needed. Same bounded path as the image download (#116) — this
+		// call site previously had neither a deadline nor retries, so its only bound
+		// was whatever the calling test happened to impose.
+		if (!existsSync(zipPath)) {
+			const log = logger ?? createLogger();
+			log.status(`Downloading packages for ${version} (${arch})...`);
+			log.status(`  ${url}`);
+			await downloadToFile(url, zipPath, { logger: log });
 		}
-		const manifest: PackageCacheManifest = {
-			version,
-			arch,
-			archiveSize: statSync(zipPath).size,
-			packages,
-		};
-		await Bun.write(join(tempDir, PACKAGE_CACHE_MANIFEST), `${JSON.stringify(manifest, null, "\t")}\n`);
-		if (existsSync(extractDir)) rmSync(extractDir, { recursive: true, force: true });
-		renameSync(tempDir, extractDir);
-	} catch (error) {
-		rmSync(tempDir, { recursive: true, force: true });
-		if (error instanceof Error && error.message.startsWith("No non-empty")) {
-			throw new QuickCHRError("PROCESS_FAILED", error.message);
+
+		// Extract into a sibling directory, record the exact complete set, then
+		// rename it into place. A killed extraction can never look like a cache hit.
+		const tempDir = mkdtempSync(join(cache, ".quickchr-packages-"));
+		try {
+			extractZip(zipPath, tempDir);
+			const packages = packageFiles(tempDir);
+			if (packages.length === 0) {
+				throw new Error(`No non-empty .npk files found in ${zipName}`);
+			}
+			const manifest: PackageCacheManifest = {
+				version,
+				arch,
+				archiveSize: statSync(zipPath).size,
+				packages,
+			};
+			await Bun.write(join(tempDir, PACKAGE_CACHE_MANIFEST), `${JSON.stringify(manifest, null, "\t")}\n`);
+			if (existsSync(extractDir)) rmSync(extractDir, { recursive: true, force: true });
+			renameWithRetry(tempDir, extractDir);
+		} catch (error) {
+			rmSync(tempDir, { recursive: true, force: true });
+			if (error instanceof Error && error.message.startsWith("No non-empty")) {
+				throw new QuickCHRError("PROCESS_FAILED", error.message);
+			}
+			throw error;
 		}
-		throw error;
-	}
 
-	if (!(await isCompletePackageCache(version, arch, cache))) {
-		throw new QuickCHRError(
-			"PROCESS_FAILED",
-			`Package cache verification failed for ${version} (${arch})`,
-		);
+		if (!(await isCompletePackageCache(version, arch, cache))) {
+			throw new QuickCHRError(
+				"PROCESS_FAILED",
+				`Package cache verification failed for ${version} (${arch})`,
+			);
+		}
+	} finally {
+		lease.release();
 	}
 
 	return extractDir;
@@ -225,8 +244,15 @@ export async function downloadAndListPackages(
 	version: string,
 	arch: Arch,
 ): Promise<string[]> {
-	const extractDir = await downloadPackages(version, arch);
-	return listAvailablePackages(extractDir);
+	// Pinned through the listing: once downloadPackages() returns, nothing else stops a
+	// concurrent eviction from removing the extraction mid-read.
+	const pin = pinCacheEntries(`list packages ${version} (${arch})`, [`packages-${arch}-${version}`]);
+	try {
+		const extractDir = await downloadPackages(version, arch);
+		return listAvailablePackages(extractDir);
+	} finally {
+		pin.release();
+	}
 }
 
 /** Download all packages and install every one of them. Useful for API schema generation.