@tikoci/quickchr 0.4.8 → 0.5.1

package/src/lib/rename.ts

@@ -0,0 +1,41 @@
+/**
+ * Publish-by-rename that survives Windows' transient sharing violations.
+ */
+
+import { renameSync } from "node:fs";
+
+/** Codes Windows returns while another process (Defender, the Search indexer) still
+ *  holds a handle on a file it is scanning — typically one we just wrote. */
+const TRANSIENT_WINDOWS_CODES = new Set(["EPERM", "EACCES", "EBUSY"]);
+const RETRY_DELAYS_MS = [25, 50, 100, 200, 400, 800];
+
+/**
+ * `renameSync`, retried on Windows while the failure looks like a sharing violation
+ * (#202). Every quickchr publish writes a temp file or directory and renames it into
+ * place, which is exactly when a scanner has the fresh file open. libuv does not retry
+ * this case. The budget is bounded (about 1.6 s); after it, the last error is thrown
+ * unchanged. Elsewhere this is a plain `renameSync`.
+ */
+export function renameWithRetry(
+	from: string,
+	to: string,
+	opts: { platform?: NodeJS.Platform; rename?: (from: string, to: string) => void; sleep?: (ms: number) => void } = {},
+): void {
+	const rename = opts.rename ?? renameSync;
+	if ((opts.platform ?? process.platform) !== "win32") {
+		rename(from, to);
+		return;
+	}
+	const sleep = opts.sleep ?? Bun.sleepSync;
+	for (const delay of RETRY_DELAYS_MS) {
+		try {
+			rename(from, to);
+			return;
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (!code || !TRANSIENT_WINDOWS_CODES.has(code)) throw error;
+			sleep(delay);
+		}
+	}
+	rename(from, to);
+}

package/src/lib/settings.ts

@@ -17,7 +17,7 @@ import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, renameSync, u
 import { basename, dirname, join } from "node:path";
 import { ARCHES, CHANNELS, QuickCHRError, parseAccelMode } from "./types.ts";
 import type { AccelMode, Channel } from "./types.ts";
-import { parseSizeString, DEFAULT_CACHE_MAX_BYTES } from "./cache.ts";
+import { parseSizeString, DEFAULT_CACHE_MAX_BYTES, DEFAULT_STORAGE_RESERVE_BYTES } from "./cache.ts";
 import { loadSettingsFileDefaults, readSettingsFileLines, settingsFilePath } from "./settings-file.ts";
 
 // The quickchr.env file tier lives in the leaf module settings-file.ts (see its
@@ -56,12 +56,14 @@ function parseArchSetting(raw: string): SettingsValue {
 	return raw;
 }
 
-function parseCacheMaxSize(raw: string): SettingsValue {
-	try {
-		return parseSizeString(raw);
-	} catch (e) {
-		throw new QuickCHRError("INVALID_SETTING_VALUE", `Invalid value "${raw}" for cache-max-size — ${e instanceof Error ? e.message : String(e)}`);
-	}
+function sizeSetting(attr: string): (raw: string) => SettingsValue {
+	return (raw) => {
+		try {
+			return parseSizeString(raw);
+		} catch (e) {
+			throw new QuickCHRError("INVALID_SETTING_VALUE", `Invalid value "${raw}" for ${attr} — ${e instanceof Error ? e.message : String(e)}`);
+		}
+	};
 }
 
 /** Shared with the CLI's own `--timeout-extra`/`-T` flag validation (cmdStart in
@@ -112,7 +114,16 @@ export const SETTINGS_KEYS: readonly SettingsKeyDef[] = [
 		attr: "cache-max-size",
 		envKey: "QUICKCHR_CACHE_MAX_SIZE",
 		builtinDefault: DEFAULT_CACHE_MAX_BYTES,
-		parse: parseCacheMaxSize,
+		parse: sizeSetting("cache-max-size"),
+		serialize: (v) => String(v),
+	},
+	{
+		// Free space creating a machine or filling the cache must leave on the data
+		// dir's filesystem, on top of what the operation itself writes (#199).
+		attr: "storage-reserve",
+		envKey: "QUICKCHR_STORAGE_RESERVE",
+		builtinDefault: DEFAULT_STORAGE_RESERVE_BYTES,
+		parse: sizeSetting("storage-reserve"),
 		serialize: (v) => String(v),
 	},
 	{
@@ -123,7 +134,7 @@ export const SETTINGS_KEYS: readonly SettingsKeyDef[] = [
 		serialize: (v) => String(v),
 	},
 	{
-		// No builtinDefault: unlike the other 5 keys, the wizard needs to distinguish
+		// No builtinDefault: unlike the other keys, the wizard needs to distinguish
 		// "not configured" from "explicitly false" (src/cli/wizard.ts's userChoice
 		// initialValue only pre-highlights "admin" when the setting is concretely
 		// false) — a builtinDefault here would collapse that distinction and always

package/src/lib/shutdown.ts

@@ -0,0 +1,49 @@
+/** Bounded guest shutdown, independently observing process exit (#143). */
+import { QuickCHRError } from "./types.ts";
+import type { ShutdownResult } from "./types.ts";
+
+export const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
+
+export function validateShutdownTimeout(timeoutMs: number): number {
+	// node:http timers cannot represent a larger delay; overflow becomes a 1 ms timer.
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+		throw new QuickCHRError("INVALID_ARGUMENT", "shutdown timeoutMs must be a positive integer no greater than 2147483647 milliseconds");
+	}
+	return timeoutMs;
+}
+
+/** The process observer is separate from the request: RouterOS can return HTTP 400
+ * `interrupted` while successfully halting. Request must enforce its timeout (exec does). */
+export async function shutdownGuest(
+	timeoutMs: number,
+	request: (timeoutMs: number) => Promise<unknown>,
+	isRunning: () => boolean,
+	forceStop: () => Promise<unknown>,
+): Promise<ShutdownResult> {
+	const deadline = performance.now() + timeoutMs;
+	let requestError: string | undefined;
+	const pending = Promise.resolve().then(() => request(Math.max(1, Math.ceil(deadline - performance.now())))).catch((error: unknown) => {
+		requestError = error instanceof Error ? error.message : String(error);
+	});
+	while (isRunning() && performance.now() < deadline) {
+		await Bun.sleep(Math.min(100, Math.max(1, deadline - performance.now())));
+	}
+	const guestExited = !isRunning();
+	// exec's HTTP timer settles this within the same grace budget, including when
+	// QEMU exits while its HTTP response is still pending. Never replay the request.
+	await pending;
+	if (guestExited || !isRunning()) {
+		return { outcome: "guest-exited", ...(requestError === undefined ? {} : { requestError }) };
+	}
+
+	try {
+		await forceStop();
+	} catch {
+		if (isRunning()) throw new QuickCHRError("STATE_ERROR", "shutdown could not terminate QEMU; machine remains running");
+	}
+	// stopQemu sends SIGKILL after its SIGTERM wait but does not await that exit.
+	const killDeadline = performance.now() + 1000;
+	while (isRunning() && performance.now() < killDeadline) await Bun.sleep(50);
+	if (isRunning()) throw new QuickCHRError("STATE_ERROR", "shutdown could not confirm QEMU exit; machine remains running");
+	return { outcome: "forced", ...(requestError === undefined ? {} : { requestError }) };
+}

package/src/lib/socket-registry.ts

@@ -142,8 +142,8 @@ const LOCK_TIMEOUT_MS = 5_000;
  *  A two-process repro lost an endpoint on 12 of 12 rounds.
  *
  *  `quickchr start a & quickchr start b &` is the shape that hits this, and it is
- *  exactly how the field report drove its multi-CHR lab. The per-machine
- *  `.start-lock` cannot help: the two contenders are different machines. */
+ *  exactly how the field report drove its multi-CHR lab. The per-machine lock
+ *  cannot help: the two contenders are different machines. */
 const _heldLocks = new Set<string>();
 
 /** How long a lock file may be unreadable before it counts as abandoned.

package/src/lib/state.ts

@@ -2,7 +2,7 @@
  * Machine state persistence — JSON files in ~/.local/share/quickchr/machines/.
  */
 
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync, statSync } from "node:fs";
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, rmSync, statSync } from "node:fs";
 import { join, } from "node:path";
 import type { MachineState, } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
@@ -285,9 +285,71 @@ export function removeMachine(name: string): void {
 	if (!existsSync(dir)) {
 		throw new QuickCHRError("MACHINE_NOT_FOUND", `Machine "${name}" not found`);
 	}
-	rmSync(dir, { recursive: true, force: true });
+	// Out of `machines/` in one step, then deleted. A recursive delete in place removes
+	// entries one by one, so there is a window where the machine lock (`.lock/`, inside
+	// the directory) is gone while the directory is not, and a waiter or a same-named
+	// create could take a fresh lock in a directory that is being deleted. After the
+	// rename the name is simply free.
+	//
+	// There is no in-place fallback, because it would reopen exactly that window. A
+	// rename can fail briefly while a scanner or indexer holds a handle (Windows refuses
+	// to rename a directory with one open), so it is retried. If it still fails, the
+	// directory is left alone and the failure is reported.
+	const trashDir = join(getDataDir(), ".removing");
+	const trash = join(trashDir, `${name}.${process.pid}.${crypto.randomUUID()}`);
+	ensureDir(trashDir);
+	sweepAbandonedRemovals(trashDir);
+	for (let attempt = 1; ; attempt++) {
+		try {
+			renameSync(dir, trash);
+			break;
+		} catch (e) {
+			if (attempt >= REMOVE_RENAME_ATTEMPTS) {
+				throw new QuickCHRError(
+					"STATE_ERROR",
+					`Could not remove machine "${name}": moving ${dir} aside failed (${(e as Error).message}). ` +
+					`The directory was left in place — close anything using it and run 'quickchr remove ${name}' again.`,
+				);
+			}
+			Bun.sleepSync(REMOVE_RENAME_RETRY_MS);
+		}
+	}
+	// The name is already free, so a failed delete does not fail the removal. The
+	// files stay under `.removing/` and the next removal sweeps them.
+	try {
+		rmSync(trash, { recursive: true, force: true });
+	} catch (e) {
+		console.warn(`Warning: machine "${name}" is removed, but deleting its files at ${trash} failed (${(e as Error).message}). The next 'quickchr remove' retries it, or delete that directory by hand.`);
+	}
+}
+
+/** Delete what earlier removals moved aside and did not finish deleting: a delete that
+ *  failed, or a process that stopped after its rename. Each entry is
+ *  `<name>.<pid>.<uuid>`. One whose pid is alive in another process is still being
+ *  deleted, so it is left alone. Best effort: a failure here never fails a removal. */
+function sweepAbandonedRemovals(trashDir: string): void {
+	let entries: string[];
+	try { entries = readdirSync(trashDir); } catch { return; }
+	for (const entry of entries) {
+		const pid = Number(entry.split(".").at(-2));
+		if (!Number.isInteger(pid) || pid <= 0) continue;
+		if (pid !== process.pid) {
+			try {
+				process.kill(pid, 0);
+				continue; // still being deleted by that process
+			} catch (e) {
+				if ((e as NodeJS.ErrnoException).code === "EPERM") continue;
+			}
+		}
+		try { rmSync(join(trashDir, entry), { recursive: true, force: true }); } catch { /* next time */ }
+	}
 }
 
+/** How long `removeMachine()` keeps trying to move a directory aside: about 2 s in
+ *  all, enough for a scanner to let go of a handle. */
+const REMOVE_RENAME_ATTEMPTS = 10;
+const REMOVE_RENAME_RETRY_MS = 200;
+
 /** Update the status of a machine. */
 export function updateMachineStatus(
 	name: string,
@@ -353,3 +415,28 @@ export function pruneCache(maxAgeDays: number = 30): number {
 
 	return removed;
 }
+
+/** Logical size of a file, or of everything under a directory. */
+export 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;
+}

package/src/lib/storage-lease.ts

@@ -0,0 +1,169 @@
+/**
+ * Cross-process coordination between storage admission, cache readers and cache
+ * eviction (#199, Codex review of #203).
+ *
+ * One data-dir-wide lock, held only for the length of a check-and-record or an
+ * eviction pass: never across a download or a boot. Under it, an operation records a
+ * **lease** — a file naming the cache entries it is about to read (pins) and the bytes
+ * it is about to write (reservations, per filesystem). Eviction runs under the same
+ * lock and skips pinned entries; admission subtracts other live leases' reservations
+ * from measured free space. A pin is recorded before the reader checks the entry
+ * exists, so an eviction either sees the pin or has already finished — and then the
+ * reader finds the entry gone and fetches it again.
+ *
+ * A lease lives exactly as long as its operation: released when the operation's
+ * writes are done (or its machine.json, which protects the image from then on, is
+ * saved), and ignored and deleted once its pid is dead. While an operation is still
+ * writing, its reservation and the bytes already written are both counted — a
+ * deliberate over-estimate for the length of one create.
+ */
+
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { acquireLockNow, type HeldLock } from "./lock.ts";
+import { ensureDir, getDataDir } from "./state.ts";
+import { renameWithRetry } from "./rename.ts";
+import { QuickCHRError } from "./types.ts";
+
+/** Bytes an in-flight operation will write to one filesystem, by `stat().dev`. */
+export interface StorageReservation {
+	dev: number;
+	bytes: number;
+}
+
+export interface LeaseRecord {
+	pid: number;
+	at: string;
+	/** What the operation is, for diagnostics. */
+	action: string;
+	/** Cache entry names (as `cacheInventory` gives them) that must not be evicted. */
+	pins: string[];
+	reservations: StorageReservation[];
+}
+
+export interface StorageLease {
+	readonly record: LeaseRecord;
+	/** Idempotent. */
+	release(): void;
+}
+
+const LOCK_WAIT_MS = 30_000;
+const LOCK_POLL_MS = 25;
+
+export function storageLockPath(): string {
+	return join(getDataDir(), ".storage.lock");
+}
+
+function leaseDir(): string {
+	return join(getDataDir(), ".storage-leases");
+}
+
+export function isPidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/** Run `fn` holding the storage lock. Synchronous: holders keep it for milliseconds
+ *  (a check, or one eviction pass), so a short spin is simpler than making every
+ *  caller async. The lock is not reentrant: `fn` must not take it again. */
+export function withStorageLock<T>(fn: () => T): T {
+	ensureDir(getDataDir());
+	const deadline = Date.now() + LOCK_WAIT_MS;
+	let lock: HeldLock | undefined;
+	for (;;) {
+		try {
+			lock = acquireLockNow(storageLockPath(), "storage", { subject: "The storage lock" });
+			break;
+		} catch (error) {
+			if (!(error instanceof QuickCHRError) || error.code !== "MACHINE_LOCKED" || Date.now() >= deadline) throw error;
+			Bun.sleepSync(LOCK_POLL_MS);
+		}
+	}
+	try {
+		return fn();
+	} finally {
+		lock.release();
+	}
+}
+
+/** Every live lease. Leases of dead processes are deleted. Call under the lock. */
+export function liveLeases(): LeaseRecord[] {
+	let names: string[];
+	try {
+		names = readdirSync(leaseDir());
+	} catch {
+		return [];
+	}
+	const live: LeaseRecord[] = [];
+	for (const name of names) {
+		if (!name.endsWith(".json")) continue;
+		const path = join(leaseDir(), name);
+		try {
+			const record = JSON.parse(readFileSync(path, "utf8")) as LeaseRecord;
+			if (isPidAlive(record.pid)) {
+				live.push(record);
+				continue;
+			}
+		} catch { /* unreadable: a writer died mid-write — files are renamed into place */ }
+		rmSync(path, { force: true });
+	}
+	return live;
+}
+
+/** Pins of live leases, read without the lock (for `cache list`'s IN-USE column). */
+export function pinnedEntries(): Set<string> {
+	const pins = new Set<string>();
+	try {
+		for (const name of readdirSync(leaseDir())) {
+			if (!name.endsWith(".json")) continue;
+			try {
+				const record = JSON.parse(readFileSync(join(leaseDir(), name), "utf8")) as LeaseRecord;
+				if (isPidAlive(record.pid)) for (const pin of record.pins) pins.add(pin);
+			} catch { /* being written or removed */ }
+		}
+	} catch { /* no leases */ }
+	return pins;
+}
+
+/** Record a lease. Call under the lock, after the checks it stands for. */
+export function createLease(action: string, pins: string[], reservations: StorageReservation[]): StorageLease {
+	const record: LeaseRecord = { pid: process.pid, at: new Date().toISOString(), action, pins, reservations };
+	mkdirSync(leaseDir(), { recursive: true });
+	const path = join(leaseDir(), `${process.pid}-${crypto.randomUUID()}.json`);
+	writeFileSync(`${path}.tmp`, JSON.stringify(record));
+	renameWithRetry(`${path}.tmp`, path);
+	let released = false;
+	return {
+		record,
+		release() {
+			if (released) return;
+			released = true;
+			rmSync(path, { force: true });
+		},
+	};
+}
+
+/** Pin cache entries for the length of a read that is not otherwise protected (a
+ *  running machine installing packages). Release when done. */
+export function pinCacheEntries(action: string, pins: string[]): StorageLease {
+	return withStorageLock(() => createLease(action, pins, []));
+}
+
+/** The filesystem a path is (or will be) written on: `stat().dev` of its nearest
+ *  existing ancestor, and that ancestor. */
+export function filesystemOf(path: string): { dev: number; statPath: string } {
+	let current = path || ".";
+	for (;;) {
+		try {
+			return { dev: statSync(current).dev, statPath: current };
+		} catch {
+			const parent = dirname(current);
+			if (parent === current) return { dev: statSync(".").dev, statPath: "." };
+			current = parent;
+		}
+	}
+}