@tikoci/quickchr 0.5.0 → 0.5.1

package/src/lib/storage.ts

@@ -1,41 +1,81 @@
 /**
- * Storage health and usage helpers for quickchr-managed files.
+ * Storage admission and usage helpers for quickchr-managed files.
+ *
+ * An operation that writes is admitted when each filesystem it writes to has room for
+ * what the operation itself will write there (its estimated peak) plus the configured
+ * host reserve. When one does not, eligible cache entries are evicted first and free
+ * space is measured again; only then is the operation refused (#199).
  */
 
-import { existsSync, lstatSync, readdirSync, statfsSync } from "node:fs";
+import { existsSync, statfsSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { type CacheEntry, countEntries, describePrune, type PruneResult, pruneCacheUnderLock, RECENT_USE_MS } from "./cache.ts";
+import { createLease, filesystemOf, liveLeases, type StorageLease, withStorageLock } from "./storage-lease.ts";
 import { formatDiskSize } from "./disk.ts";
-import { getCacheDir, getDataDir, getMachinesDir } from "./state.ts";
-import { QuickCHRError } from "./types.ts";
+import { resolveSetting } from "./settings.ts";
+import { directorySize, getCacheDir, getDataDir, getMachinesDir } from "./state.ts";
+import { chrImageBasename } from "./versions.ts";
+import { type Arch, QuickCHRError } from "./types.ts";
 
-export const QUICKCHR_MIN_FREE_BYTES = 10 * 1024 ** 3;
-export const QUICKCHR_WARN_FREE_BYTES = 20 * 1024 ** 3;
+const MiB = 1024 ** 2;
+
+/**
+ * Peak new bytes per stage, rounded up from one host's measurements (#199, macOS x86,
+ * CHR 7.20–7.26): a 128 MiB extracted image from a ~45 MiB ZIP, a qcow2 boot disk of
+ * ~50 MiB after first boot (never more than the raw image it is converted from), and
+ * 29–52 MiB package archives that extract to about their own size. Estimates, not
+ * bounds: they are what admission charges, and the reserve absorbs the error.
+ */
+export const STORAGE_ESTIMATES = {
+	/** Image ZIP plus its extraction, which coexist until the ZIP is removed. */
+	imageDownload: 256 * MiB,
+	/** A raw copy or a qcow2 conversion of the image, plus first-boot writes. */
+	bootDisk: 192 * MiB,
+	/** The all-packages archive plus its extraction; both are kept. */
+	packagesDownload: 192 * MiB,
+} as const;
+
+/** doctor warns while free space is under the reserve plus this much. */
+const WARN_MARGIN_BYTES = 2 * 1024 ** 3;
 
 export interface QuickchrStorageReport {
-	label: ".local" | "data dir";
+	/** The data dir: where the cache and machines are written. */
 	path: string;
+	/** The nearest existing directory to `path`, whose filesystem is measured. */
 	statPath: string;
 	freeBytes: number;
 	quickchrBytes: number;
 	cacheBytes: number;
 	machinesBytes: number;
 	otherBytes: number;
-	recommendedFreeBytes: number;
+	reserveBytes: number;
 	warningFreeBytes: number;
 	status: "ok" | "warn" | "error";
 }
 
-function resolveStorageRoot(): { label: QuickchrStorageReport["label"]; path: string } {
-	if (process.env.QUICKCHR_DATA_DIR || process.platform === "win32") {
-		return { label: "data dir", path: getDataDir() };
-	}
-
-	const home = process.env.HOME || process.env.USERPROFILE || "";
-	if (!home) {
-		return { label: "data dir", path: getDataDir() };
-	}
+/** One stage of an operation's writes. */
+export interface StoragePart {
+	/** For the refusal message, e.g. "boot disk". */
+	label: string;
+	/** Estimated peak new bytes. */
+	bytes: number;
+	/** Where they are written: the part is checked on that path's filesystem. */
+	path: string;
+	/** Reserve the bytes in the operation's lease (the default). False for a stage that
+	 *  admits and reserves for itself when it runs, such as a download a create will
+	 *  trigger: checked now, so the create refuses early, but not held twice. */
+	hold?: boolean;
+}
 
-	return { label: ".local", path: join(home, ".local") };
+/** What an operation is about to write and read, for admission. */
+export interface StorageNeed {
+	parts: StoragePart[];
+	/** Versions the operation reads from the cache: reclamation never evicts them. */
+	protectVersions?: string[];
+	/** Cache entries the operation reads; pinned in its lease. */
+	pins?: string[];
+	/** The cache reclamation evicts from. Default: the data dir's cache. */
+	cacheDir?: string;
 }
 
 function nearestExistingPath(path: string): string {
@@ -48,30 +88,6 @@ function nearestExistingPath(path: string): string {
 	return current;
 }
 
-function directorySize(path: string): number {
-	if (!existsSync(path)) return 0;
-
-	const stat = lstatSync(path);
-	if (!stat.isDirectory()) {
-		return stat.size;
-	}
-
-	let total = 0;
-	for (const entry of readdirSync(path, { withFileTypes: true })) {
-		const fullPath = join(path, entry.name);
-		if (entry.isDirectory()) {
-			total += directorySize(fullPath);
-		} else {
-			try {
-				total += lstatSync(fullPath).size;
-			} catch {
-				// Skip entries that can't be stat'd (e.g. Windows named pipes throw EACCES)
-			}
-		}
-	}
-	return total;
-}
-
 function freeBytesForPath(path: string): number {
 	if (process.platform !== "win32") {
 		const result = Bun.spawnSync(["df", "-kP", path], {
@@ -95,15 +111,23 @@ function freeBytesForPath(path: string): number {
 	return fsStats.bavail * (fsStats.bsize || 4096);
 }
 
+/** The free-space measurement and filesystem identity, as an object so tests can
+ *  replace them (a unit test cannot mount a second filesystem). */
+export const storageProbe = { freeBytes: freeBytesForPath, filesystem: filesystemOf };
+
+/** The configured host reserve: the `storage-reserve` setting (default 2 GiB). */
+export function resolveStorageReserve(): number {
+	return resolveSetting("storage-reserve").value as number;
+}
+
 export function getQuickchrStorageReport(
-	recommendedFreeBytes: number = QUICKCHR_MIN_FREE_BYTES,
-	warningFreeBytes: number = QUICKCHR_WARN_FREE_BYTES,
+	reserveBytes: number = resolveStorageReserve(),
+	warningFreeBytes: number = reserveBytes + WARN_MARGIN_BYTES,
 ): QuickchrStorageReport {
-	const storageRoot = resolveStorageRoot();
-	const statPath = nearestExistingPath(storageRoot.path);
-	const freeBytes = freeBytesForPath(statPath);
-
 	const dataDir = getDataDir();
+	const statPath = nearestExistingPath(dataDir);
+	const freeBytes = storageProbe.freeBytes(statPath);
+
 	const cacheBytes = directorySize(getCacheDir());
 	const machinesBytes = directorySize(getMachinesDir());
 	const dataDirBytes = directorySize(dataDir);
@@ -111,22 +135,21 @@ export function getQuickchrStorageReport(
 	const otherBytes = Math.max(0, dataDirBytes - cacheBytes - machinesBytes);
 
 	let status: QuickchrStorageReport["status"] = "ok";
-	if (freeBytes < recommendedFreeBytes) {
+	if (freeBytes < reserveBytes) {
 		status = "error";
 	} else if (freeBytes < warningFreeBytes) {
 		status = "warn";
 	}
 
 	return {
-		label: storageRoot.label,
-		path: storageRoot.path,
+		path: dataDir,
 		statPath,
 		freeBytes,
 		quickchrBytes,
 		cacheBytes,
 		machinesBytes,
 		otherBytes,
-		recommendedFreeBytes,
+		reserveBytes,
 		warningFreeBytes,
 		status,
 	};
@@ -143,21 +166,155 @@ export function formatQuickchrUsage(report: QuickchrStorageReport): string {
 	return `quickchr uses ${formatDiskSize(report.quickchrBytes)} (${parts.join(", ")})`;
 }
 
-export function assertSufficientQuickchrStorage(
-	action: string,
-	minimumFreeBytes: number = QUICKCHR_MIN_FREE_BYTES,
-): QuickchrStorageReport {
-	const report = getQuickchrStorageReport(
-		minimumFreeBytes,
-		Math.max(QUICKCHR_WARN_FREE_BYTES, minimumFreeBytes),
-	);
+/** What creating a machine will write: its boot disk, plus the image and package
+ *  downloads it still needs. Extra disks are sparse qcow2 and start near zero.
+ *  Only the boot disk is held in the create's lease: each download admits and
+ *  reserves for itself when it runs, so holding it here would count it twice. */
+export function estimateMachineCreation(opts: { version: string; arch: Arch; packages: boolean }): StorageNeed {
+	const cache = getCacheDir();
+	const image = chrImageBasename(opts.version, opts.arch);
+	const parts: StoragePart[] = [{ label: "boot disk", bytes: STORAGE_ESTIMATES.bootDisk, path: getMachinesDir() }];
+	if (!existsSync(join(cache, `${image}.img`))) {
+		parts.push({ label: "image download", bytes: STORAGE_ESTIMATES.imageDownload, path: cache, hold: false });
+	}
+	if (opts.packages && !existsSync(join(cache, `packages-${opts.arch}-${opts.version}`))) {
+		parts.push({ label: "packages download", bytes: STORAGE_ESTIMATES.packagesDownload, path: cache, hold: false });
+	}
+	return { parts, protectVersions: [opts.version], pins: [`${image}.img`, `${image}.img.zip`] };
+}
+
+interface FilesystemGroup {
+	dev: number;
+	statPath: string;
+	parts: StoragePart[];
+	bytes: number;
+}
 
-	if (report.freeBytes < minimumFreeBytes) {
-		throw new QuickCHRError(
-			"INSUFFICIENT_DISK_SPACE",
-			`Not enough free space to ${action} in ${report.path}: ${formatDiskSize(report.freeBytes)} available, need at least ${formatDiskSize(minimumFreeBytes)}. ${formatQuickchrUsage(report)}.`,
-		);
+function groupByFilesystem(parts: StoragePart[]): FilesystemGroup[] {
+	const groups = new Map<number, FilesystemGroup>();
+	for (const part of parts.length > 0 ? parts : [{ label: "", bytes: 0, path: getDataDir() }]) {
+		const { dev, statPath } = storageProbe.filesystem(part.path);
+		const group = groups.get(dev) ?? { dev, statPath, parts: [], bytes: 0 };
+		if (part.label) group.parts.push(part);
+		group.bytes += part.bytes;
+		groups.set(dev, group);
 	}
+	return [...groups.values()];
+}
+
+/**
+ * Admit an operation, or throw `INSUFFICIENT_DISK_SPACE`. Returns a lease the caller
+ * releases once its writes are done (see storage-lease.ts).
+ *
+ * Each filesystem the operation writes to is checked on its own: free space, less
+ * what other in-flight operations have reserved there, must cover that filesystem's
+ * parts plus the reserve. When it does not, and the cache being reclaimed lives on that
+ * filesystem, eligible entries are evicted (oldest version first; never in-use, pinned,
+ * protected or recently used ones) and free space is measured again — repeatedly,
+ * because logical sizes are no proof of room (sparse files, APFS clones), until the
+ * measurement admits or nothing more can be evicted. When everything eligible could
+ * not cover the shortage, nothing is evicted.
+ *
+ * The check and the lease are made under the storage lock, so two creators cannot
+ * spend the same free bytes, and an eviction cannot remove what this operation pins.
+ */
+export function admitStorage(
+	action: string,
+	need: StorageNeed = { parts: [] },
+	opts: { reclaim?: boolean; logger?: (message: string) => void } = {},
+): StorageLease {
+	return withStorageLock(() => {
+		const reserveBytes = resolveStorageReserve();
+		const leases = liveLeases();
+		const pins = new Set([...leases.flatMap((lease) => lease.pins), ...(need.pins ?? [])]);
+		const cacheDir = need.cacheDir ?? getCacheDir();
+		const cacheDev = storageProbe.filesystem(cacheDir).dev;
 
-	return report;
+		for (const group of groupByFilesystem(need.parts)) {
+			const reservedByOthers = leases
+				.flatMap((lease) => lease.reservations)
+				.filter((r) => r.dev === group.dev)
+				.reduce((sum, r) => sum + r.bytes, 0);
+			const measure = () => storageProbe.freeBytes(group.statPath) - reservedByOthers;
+			const required = group.bytes + reserveBytes;
+			let free = measure();
+			if (free >= required) continue;
+
+			const reclaim = opts.reclaim !== false && cacheDev === group.dev;
+			const evicted: CacheEntry[] = [];
+			const failed: PruneResult["failed"] = [];
+			let kept: PruneResult | undefined;
+			let wouldNotCover = false;
+			if (reclaim) {
+				const policy = { cacheDir, protectVersions: need.protectVersions, skipRecentMs: RECENT_USE_MS };
+				// Evicting cannot close a gap larger than everything eligible: refuse with the
+				// cache intact rather than empty it for nothing.
+				kept = pruneCacheUnderLock({ ...policy, reclaimBytes: required - free, dryRun: true }, pins);
+				wouldNotCover = kept.freedBytes < required - free;
+				while (!wouldNotCover && free < required) {
+					const pass = pruneCacheUnderLock({
+						...policy,
+						reclaimBytes: required - free,
+						skipEntries: failed.map((f) => f.entry.basename),
+					}, pins);
+					for (const line of describePrune(pass)) opts.logger?.(line);
+					evicted.push(...pass.evicted);
+					failed.push(...pass.failed);
+					kept = pass;
+					free = measure();
+					if (pass.evicted.length === 0) break;
+				}
+				if (free >= required) continue;
+			}
+
+			throw insufficientSpace(action, group, { free, required, reserveBytes, reservedByOthers, reclaimed: kept && { evicted, failed, kept, wouldNotCover } });
+		}
+
+		const reservations = groupByFilesystem(need.parts.filter((part) => part.hold !== false))
+			.filter((group) => group.bytes > 0)
+			.map((group) => ({ dev: group.dev, bytes: group.bytes }));
+		if (reservations.length === 0 && (need.pins ?? []).length === 0) return { record: { pid: process.pid, at: "", action, pins: [], reservations: [] }, release() {} };
+		return createLease(action, need.pins ?? [], reservations);
+	});
+}
+
+function insufficientSpace(
+	action: string,
+	group: FilesystemGroup,
+	facts: {
+		free: number;
+		required: number;
+		reserveBytes: number;
+		reservedByOthers: number;
+		reclaimed?: { evicted: CacheEntry[]; failed: PruneResult["failed"]; kept: PruneResult; wouldNotCover: boolean };
+	},
+): QuickCHRError {
+	const detail = group.parts.map((part) => `${part.label} ${formatDiskSize(part.bytes)}`).join(" + ");
+	const needs = detail ? `${detail} + ${formatDiskSize(facts.reserveBytes)} reserve` : `${formatDiskSize(facts.reserveBytes)} reserve`;
+	const available = facts.reservedByOthers > 0
+		? `${formatDiskSize(facts.free)} available after ${formatDiskSize(facts.reservedByOthers)} held by other operations in progress`
+		: `${formatDiskSize(facts.free)} available`;
+	const sentences = [
+		`Not enough free space to ${action} in ${group.statPath}: ${available}, need ${formatDiskSize(facts.required)} (${needs}), ${formatDiskSize(facts.required - facts.free)} short.`,
+	];
+	const r = facts.reclaimed;
+	if (r) {
+		const freed = r.evicted.reduce((sum, e) => sum + e.sizeBytes, 0);
+		let line = r.wouldNotCover
+			? r.kept.evicted.length > 0
+				? `The cache could spare only ${formatDiskSize(r.kept.freedBytes)} (${countEntries(r.kept.evicted.length)}), not enough, so nothing was evicted.`
+				: "Nothing in the cache could be evicted."
+			: `Evicted ${countEntries(r.evicted.length)} from the cache (${formatDiskSize(freed)}) first.`;
+		if (r.failed.length > 0) line += ` ${r.failed.length} delete(s) failed.`;
+		const keptBytes = r.kept.kept
+			.filter((e) => r.kept.reasons[e.basename] !== "kept")
+			.reduce((sum, e) => sum + e.sizeBytes, 0);
+		if (keptBytes > 0) line += ` ${formatDiskSize(keptBytes)} is kept: in use by a machine or an operation in progress, needed by this operation, or used in the last ${RECENT_USE_MS / 60_000} minutes.`;
+		sentences.push(line);
+	}
+	return new QuickCHRError(
+		"INSUFFICIENT_DISK_SPACE",
+		sentences.join(" "),
+		"Free space on that filesystem, remove machines you no longer need, or lower the reserve with 'quickchr settings set storage-reserve <size>' (QUICKCHR_STORAGE_RESERVE).",
+	);
 }

package/src/lib/types.ts

@@ -432,7 +432,8 @@ export interface StartOptions {
 	 *  networks: ["user", { type: "socket-connect", port: hostTcpServerPort }]
 	 */
 	networks?: NetworkSpecifier[];
-	/** Install OS-level dependencies (QEMU, firmware) automatically if missing. */
+	/** @deprecated Ignored — nothing ever read it, so it never installed anything (#193).
+	 *  `quickchr doctor` lists missing host dependencies. To be removed in a later minor. */
 	installDeps?: boolean;
 	/** Print QEMU command and config without actually starting the VM. */
 	dryRun?: boolean;
@@ -740,7 +741,8 @@ export interface ChrInstance {
 	 *  **Soft errors.** Some RouterOS commands return HTTP 200 with an error
 	 *  string in `output` (e.g. `/dude/agent/add` may resolve OK with
 	 *  `"doAdd Agent not implemented"`). `exec()` does not parse output for these
-	 *  patterns — inspect `result.output` if you need to assert success.
+	 *  patterns — inspect `result.output` if you need to assert success. For a
+	 *  pass/fail result, use `centrs execute --quickchr <name> --yes <command>`.
 	 */
 	exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
 	/** Apply or renew a CHR trial license.
@@ -949,7 +951,15 @@ export interface ExecOptions {
 	timeout?: number;
 }
 
-/** Result of a ChrInstance.exec() call. */
+/** Result of a ChrInstance.exec() call.
+ *
+ *  A resolved `exec()` means the command was **delivered**, not that RouterOS
+ *  accepted it. `/rest/execute` answers HTTP 200 with the rejection text (e.g.
+ *  `failure: invalid user name`) in the same envelope as a success, so there is no
+ *  failure field here, and quickchr does not pattern-match RouterOS error text
+ *  (#142). For a pass/fail result, run the command through
+ *  `centrs execute --quickchr <name> --yes <command>`, which validates it first and
+ *  exits non-zero on a rejection (`--yes` confirms a write command outside a TTY). */
 export interface ExecResult {
 	/** Command output as a string (or parsed JSON when output="json"). */
 	output: string;