@tikoci/quickchr 0.4.6 → 0.4.8

package/src/lib/state.ts

@@ -7,6 +7,7 @@ import { join, } from "node:path";
 import type { MachineState, } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
 import { networkModeToConfigs } from "./network.ts";
+import { assertPathSafeName, isPathSafeName } from "./names.ts";
 
 /** Get the quickchr data directory root. Override with QUICKCHR_DATA_DIR env var. */
 export function getDataDir(): string {
@@ -91,12 +92,72 @@ export function saveMachine(state: MachineState): void {
 	writeFileSync(machineJsonPath(state.name), JSON.stringify(state, null, "\t") + "\n");
 }
 
-/** Load machine state from disk. Returns undefined if not found. */
+/** The fields every caller dereferences without guarding, with the `typeof` each must
+ *  answer. Deliberately not a schema: it is the set that turns a bad file into a crash
+ *  somewhere else, which is the thing being prevented. `cpu`/`mem` are absent because a
+ *  missing one prints oddly rather than throwing, and a narrow check cannot wrongly
+ *  condemn a machine that works today. `networks` is absent because `loadMachine()`
+ *  migrates it just below.
+ *
+ *  Every field listed here has been required on `MachineState` since the commit that
+ *  introduced it (5cfe052), so no `machine.json` any version of quickchr wrote can be
+ *  condemned by this check — which is the thing that would make it worse than the bug
+ *  it fixes. */
+const REQUIRED_STATE_FIELDS: ReadonlyArray<[keyof MachineState, "string" | "number" | "object"]> = [
+	["name", "string"],
+	["version", "string"],
+	["arch", "string"],
+	["status", "string"],
+	["machineDir", "string"],
+	["portBase", "number"],
+	["ports", "object"],
+	["packages", "object"],
+];
+
+/** Why `parsed` is not usable as a `MachineState`, or `undefined` when it is.
+ *
+ *  Parsing successfully is not the same as being state. `{"name":"lab"}` parses, and
+ *  `JSON.parse` is happy with `null` and `[]` too; casting any of them to `MachineState`
+ *  only moves the failure — `{"name":"lab"}` reached `formatPorts(m.ports)` and aborted
+ *  `quickchr list` exactly as an unparseable file used to (#165). */
+function stateShapeProblem(parsed: unknown): string | undefined {
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return "not a JSON object";
+	}
+	const record = parsed as Record<string, unknown>;
+	const bad = REQUIRED_STATE_FIELDS
+		.filter(([key, kind]) => typeof record[key] !== kind || record[key] === null)
+		.map(([key]) => key);
+	return bad.length > 0 ? `missing or invalid: ${bad.join(", ")}` : undefined;
+}
+
+/** Load machine state from disk. Returns undefined if not found.
+ *
+ *  Throws `STATE_ERROR` when the file is there but unusable. A targeted lookup by name
+ *  has to fail: the caller named *this* machine, and answering `undefined` would report
+ *  a machine that exists on disk as one that never did. `loadAllMachines()` is the
+ *  enumeration and takes the other policy — see `tryLoadMachine()` (#165). */
 export function loadMachine(name: string): MachineState | undefined {
 	const path = machineJsonPath(name);
 	if (!existsSync(path)) return undefined;
-	const data = readFileSync(path, "utf-8");
-	const state = JSON.parse(data) as MachineState;
+	let state: MachineState;
+	try {
+		state = JSON.parse(readFileSync(path, "utf-8")) as MachineState;
+	} catch (e) {
+		throw new QuickCHRError(
+			"STATE_ERROR",
+			`Machine "${name}" has an unreadable machine.json (${e instanceof Error ? e.message : String(e)})`,
+			`Inspect ${path}, or clear the machine with 'quickchr remove ${name}'`,
+		);
+	}
+	const shapeProblem = stateShapeProblem(state);
+	if (shapeProblem) {
+		throw new QuickCHRError(
+			"STATE_ERROR",
+			`Machine "${name}" has an unreadable machine.json (${shapeProblem})`,
+			`Inspect ${path}, or clear the machine with 'quickchr remove ${name}'`,
+		);
+	}
 	// Migrate legacy `network` field → `networks` array
 	if (!state.networks && (state as unknown as Record<string, unknown>).network) {
 		const legacy = (state as unknown as Record<string, unknown>).network as MachineState["networks"][0]["specifier"] | "user" | "vmnet-shared" | { type: "vmnet-bridge"; iface: string };
@@ -107,7 +168,33 @@ export function loadMachine(name: string): MachineState | undefined {
 	return state;
 }
 
-/** Load all machine states. */
+/** The three things a machine directory can turn out to be.
+ *
+ *  `loadMachine()` collapses `missing` and `unreadable` into "undefined or throw", which
+ *  is the right contract for a lookup and the wrong one for an enumeration. This keeps
+ *  them apart so each caller can pick (#165). Internal for now: promoting it to public
+ *  API is a rename if #58 lands. */
+type MachineLoad =
+	| { status: "ok"; state: MachineState }
+	| { status: "missing" }
+	| { status: "unreadable"; error: string };
+
+/** `loadMachine()` without the throw. */
+function tryLoadMachine(name: string): MachineLoad {
+	try {
+		const state = loadMachine(name);
+		return state ? { status: "ok", state } : { status: "missing" };
+	} catch (e) {
+		return { status: "unreadable", error: e instanceof Error ? e.message : String(e) };
+	}
+}
+
+/** Load all machine states, skipping directories with no usable `machine.json`.
+ *
+ *  An enumeration is best-effort across many: one corrupt file used to abort the whole
+ *  listing, which loses the state of every healthy machine as well. Nothing is hidden by
+ *  the skip — `listUnreadableMachines()` names what was left out, and `quickchr list`
+ *  shows it as a row (#165). */
 export function loadAllMachines(): MachineState[] {
 	const dir = getMachinesDir();
 	if (!existsSync(dir)) return [];
@@ -117,13 +204,27 @@ export function loadAllMachines(): MachineState[] {
 
 	for (const entry of entries) {
 		if (!entry.isDirectory()) continue;
-		const state = loadMachine(entry.name);
-		if (state) machines.push(state);
+		const loaded = tryLoadMachine(entry.name);
+		if (loaded.status === "ok") machines.push(loaded.state);
 	}
 
 	return machines;
 }
 
+/** Every machine directory whose `machine.json` exists but cannot be read.
+ *
+ *  Distinct from `listOrphanMachineDirs()`, which also counts a directory with no
+ *  `machine.json` at all — a create that never finished. This one is a machine that did
+ *  exist and whose state went bad, so it still holds a disk image worth naming. */
+export function listUnreadableMachines(): Array<{ name: string; error: string }> {
+	const out: Array<{ name: string; error: string }> = [];
+	for (const name of listMachineNames()) {
+		const loaded = tryLoadMachine(name);
+		if (loaded.status === "unreadable") out.push({ name, error: loaded.error });
+	}
+	return out;
+}
+
 /** Get all existing machine names. */
 export function listMachineNames(): string[] {
 	const dir = getMachinesDir();
@@ -133,13 +234,53 @@ export function listMachineNames(): string[] {
 		.map((e) => e.name);
 }
 
+/** True when `name` has a machine directory but no readable `machine.json` — a create
+ *  that did not finish. `list` cannot show it and `start` cannot boot it, but
+ *  `listMachineNames()` (directory-based) still counts it, so it blocks re-add (#155). */
+export function isOrphanMachineDir(name: string): boolean {
+	// A traversal name resolves to a directory that exists and holds no machine.json —
+	// the data dir itself, for ".." — so the path check has to come first or the
+	// predicate answers "orphan" about something that is not a machine directory.
+	if (!isPathSafeName(name)) return false;
+	const dir = getMachineDir(name);
+	if (!existsSync(dir)) return false;
+	return !isReadableMachine(name);
+}
+
+/** Every machine directory with no readable `machine.json`. */
+export function listOrphanMachineDirs(): string[] {
+	return listMachineNames().filter((name) => !isReadableMachine(name));
+}
+
+/** A truncated or corrupt `machine.json` is as unusable as a missing one, and both make
+ *  the directory an orphan. */
+function isReadableMachine(name: string): boolean {
+	return tryLoadMachine(name).status === "ok";
+}
+
 /** Get all port bases currently in use by existing machines. */
 export function getUsedPortBases(): number[] {
 	return loadAllMachines().map((m) => m.portBase);
 }
 
+/** Every NIC MAC currently assigned across all machines.
+ *  Passed to `assignMacs()` so a new machine cannot be handed an address another
+ *  machine already presents on a shared L2 segment (#154). */
+export function getUsedMacs(): Set<string> {
+	const macs = new Set<string>();
+	for (const m of loadAllMachines()) {
+		for (const n of m.networks ?? []) {
+			if (n.mac) macs.add(n.mac);
+		}
+	}
+	return macs;
+}
+
 /** Delete a machine and all its files. */
 export function removeMachine(name: string): void {
+	// This is an `rmSync(..., { recursive: true })`; the name must never be able to
+	// point outside machines/<name>/.
+	assertPathSafeName(name, "machine");
 	const dir = getMachineDir(name);
 	if (!existsSync(dir)) {
 		throw new QuickCHRError("MACHINE_NOT_FOUND", `Machine "${name}" not found`);

package/src/lib/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { ProgressLogger } from "./log.ts";
+import type { BootProbeStats } from "./diagnostics.ts";
 
 // --- Version & Architecture ---
 
@@ -54,13 +55,14 @@ export type NetworkMode =
  * - **Host needs to see guest L2 frames** (MNDP, MAC-Telnet, raw Ethernet,
  *   broadcasts) → `{type:"socket-connect", port}` against a host TCP server
  *   (rootless, cross-platform; recipe in `docs/mndp.md`).
- * - **L2 link between two VMs** → `{type:"socket", name}` (named pair) or
- *   `socket-listen`/`socket-connect`/`socket-mcast` (low-level).
+ * - **L2 link between two VMs** → `{type:"socket", name}`, a named link whose
+ *   transport (`dgram`, `listen-connect`, `mcast`) is fixed when the name is created;
+ *   or `socket-listen`/`socket-connect`/`socket-mcast` for a raw netdev.
  * - **Real LAN / DHCP-from-host presence** → `"shared"` or `{type:"bridged", iface}`
  *   (rootless via socket_vmnet on macOS / pre-created TAP on Linux).
  *
  * Note: receiving guest-*originated* UDP (e.g. a guest replying to `10.0.2.2`)
- * needs no extra NIC and no forward — see {@link ChrInstance.tzspGatewayIp}.
+ * needs no extra NIC and no forward — see {@link ChrInstance.hostGatewayIp}.
  */
 export type NetworkSpecifier =
 	/** SLIRP user-mode NAT + `hostfwd` port mapping. Management default; the only
@@ -105,6 +107,12 @@ export interface NetworkConfig {
 	specifier: NetworkSpecifier;
 	/** QEMU netdev id (net0, net1, ...). */
 	id: string;
+	/** Locally-administered MAC, assigned at creation and persisted so it survives
+	 *  restart. Without it QEMU hands every guest the same default sequence and two
+	 *  machines on one L2 segment collide — see `deriveMac` in `network.ts` (#154).
+	 *  Never reassigned: changing it on a booted machine orphans RouterOS's interface
+	 *  identity. Absent on machines created before #154, which keep QEMU's defaults. */
+	mac?: string;
 	/** Resolved QEMU args (populated at launch time, not persisted). */
 	resolved?: ResolvedNetwork;
 }
@@ -169,6 +177,11 @@ export const SERVICE_NAMES = Object.keys(SERVICE_PORTS) as ServiceName[];
 export const PORTS_PER_BLOCK = 10;
 export const DEFAULT_PORT_BASE = 9100;
 
+/** QEMU user-mode (SLIRP) gateway — the host's address as seen from inside a guest.
+ *  Fixed by QEMU's built-in 10.0.2.0/24 user network; surfaced on a running instance
+ *  as {@link ChrInstance.hostGatewayIp}. */
+export const HOST_GATEWAY_IP = "10.0.2.2";
+
 /**
  * TCP endpoint for QEMU IPC channels on Windows.
  * Used instead of named pipes when QEMU's Winsock bind() can't handle \\.\pipe\ paths.
@@ -340,7 +353,7 @@ export interface StartOptions {
 	 *  {@link lookupGuestPort} resolve guest port + proto for common service names.
 	 *
 	 *  For *receiving* guest-originated UDP (no forward needed), see
-	 *  {@link ChrInstance.tzspGatewayIp} and `docs/networking-recipes.md`.
+	 *  {@link ChrInstance.hostGatewayIp} and `docs/networking-recipes.md`.
 	 *  @example
 	 *  extraPorts: [{ name: "snmp", host: 9161, guest: 161, proto: "udp" }]
 	 *  @example
@@ -590,15 +603,26 @@ export interface ChrInstance {
 	 *  `docs/networking-recipes.md`, `examples/udp-gateway/`.
 	 *  @example
 	 *  // RouterOS TZSP sniffer streaming to the host:
-	 *  await instance.exec(`/tool/sniffer/set streaming-server=${instance.tzspGatewayIp}:37008`);
+	 *  await instance.exec(`/tool/sniffer/set streaming-server=${instance.hostGatewayIp}:37008`);
 	 */
+	hostGatewayIp: string;
+	/** @deprecated Renamed to {@link ChrInstance.hostGatewayIp} — the value was never
+	 *  TZSP-specific, it is the host as seen from inside the guest and carries any
+	 *  guest→host UDP (remote syslog, NetFlow, a plain socket). The old name led
+	 *  readers to assume a sniffer-only primitive.
+	 *
+	 *  Still populated with the identical value, and will be removed no earlier than
+	 *  the next minor. Migration is a rename at the call site — nothing else changes. */
 	tzspGatewayIp: string;
 
 	/** Check or wait for REST API readiness.
 	 *  After `QuickCHR.start()` with provisioning options (installAllPackages, license, etc.),
 	 *  the returned instance is already REST-reachable — this returns immediately.
 	 *  Call this only when starting without provisioning, or as a safety check after a manual stop/restart. */
-	waitForBoot(timeoutMs?: number): Promise<boolean>;
+	/** @param stats Optional out-param; each REST readiness probe is classified
+	 *  into it (see diagnostics.ts BootProbeStats) so a failed wait can explain
+	 *  whether the forwarded port ever answered. */
+	waitForBoot(timeoutMs?: number, stats?: BootProbeStats): Promise<boolean>;
 	/** Poll a condition until it returns true or the timeout elapses.
 	 *  Retries every 2 s, swallowing errors from the condition function.
 	 *  Returns `true` when the condition passes, `false` on timeout.
@@ -784,6 +808,16 @@ export type ErrorCode =
 	| "QGA_UNSUPPORTED"
 	| "QGA_TIMEOUT"
 	| "DOWNLOAD_FAILED"
+	// A transfer that received nothing for DOWNLOAD_STALL_MS. Retriable, and
+	// retried before this surfaces — a wedged socket usually moves on the next
+	// attempt (#116).
+	| "DOWNLOAD_STALLED"
+	// A transfer that kept moving but could not finish inside a budget derived
+	// from its content-length and COLD_DOWNLOAD_FLOOR_BYTES_PER_S. Terminal on
+	// purpose: retrying re-downloads from zero on a link already measured slower
+	// than the floor, which is the "one slow transfer becomes three" behavior
+	// #116 exists to remove.
+	| "DOWNLOAD_TOO_SLOW"
 	| "MACHINE_EXISTS"
 	| "MACHINE_NOT_FOUND"
 	| "MACHINE_RUNNING"
@@ -791,6 +825,10 @@ export type ErrorCode =
 	| "INVALID_VERSION"
 	| "INVALID_ARCH"
 	| "INVALID_NAME"
+	// A flag or argument the CLI cannot honour as written — a removed flag name, or a
+	// value it will not accept. Distinct from INVALID_SETTING_VALUE, which is about a
+	// stored setting rather than what was typed.
+	| "INVALID_ARGUMENT"
 	| "INVALID_DISK_SIZE"
 	| "MACHINE_LOCKED"
 	| "EXEC_FAILED"

package/src/lib/versions.ts

@@ -4,7 +4,7 @@
 
 import type { Arch, Channel } from "./types.ts";
 import { CHANNELS, QuickCHRError } from "./types.ts";
-import { fetchResilient } from "./net.ts";
+import { fetchResilient, isConnectionFailure } from "./net.ts";
 
 const UPGRADE_BASE = "https://upgrade.mikrotik.com/routeros/NEWESTa7";
 const DOWNLOAD_BASE = "https://download.mikrotik.com/routeros";
@@ -65,35 +65,112 @@ export function provisioningSupportHint(minimumVersion = MIN_PROVISION_VERSION):
 	return `Use --channel long-term or --version ${minimumVersion}+ for ${PROVISIONING_FEATURE_SUMMARY}, or keep the older version without provisioning options.`;
 }
 
-/** Fetch the latest version for a given channel from MikroTik's upgrade server. */
-export async function resolveVersion(channel: Channel): Promise<string> {
-	const url = `${UPGRADE_BASE}.${channel}`;
+/** Attempts for a connection-class failure while resolving a channel version. */
+export const VERSION_RESOLVE_MAX_ATTEMPTS = 3;
+
+/** Backoff base: attempt N waits N × this before N+1. Mirrors `downloadToFile`. */
+const VERSION_RESOLVE_RETRY_MS = 2000;
+
+export interface ResolveVersionOptions {
+	/** Attempts for connection-class failures. Defaults to {@link VERSION_RESOLVE_MAX_ATTEMPTS}. */
+	maxAttempts?: number;
+	/**
+	 * Override the backoff base. A test lever, like `downloadToFile`'s `stallMs`:
+	 * the real backoff spends 6 s of wall clock exhausting the default attempts.
+	 * Production callers should not set it.
+	 */
+	retryDelayMs?: number;
+}
 
-	const response = await fetchResilient(url);
-	if (!response.ok) {
-		throw new QuickCHRError(
-			"DOWNLOAD_FAILED",
-			`Failed to fetch version for channel "${channel}": HTTP ${response.status}`,
-		);
-	}
+/** A whole count of at least 1, or `fallback` for anything that isn't one. */
+function positiveInt(value: number | undefined, fallback: number): number {
+	if (value === undefined || !Number.isFinite(value)) return fallback;
+	return Math.max(1, Math.floor(value));
+}
+
+/** A finite, non-negative delay in ms, or `fallback` for anything that isn't one. */
+function nonNegativeMs(value: number | undefined, fallback: number): number {
+	if (value === undefined || !Number.isFinite(value)) return fallback;
+	return Math.max(0, value);
+}
 
-	const text = await response.text();
-	// Response format: "7.22.1 1774276515" (version + unix timestamp)
-	const version = text.trim().split(/\s+/)[0]?.trim();
-	if (!version || !isValidVersion(version)) {
-		throw new QuickCHRError(
-			"INVALID_VERSION",
-			`Unexpected version format for channel "${channel}": "${text.trim()}"`,
-		);
+/**
+ * Fetch the latest version for a given channel from MikroTik's upgrade server.
+ *
+ * Retried on a connection-class failure only — a transient refusal at
+ * `upgrade.mikrotik.com` used to fail a whole `quickchr start`, since this sits
+ * on the critical path of `start()`, the wizard and the CLI while only the
+ * download path had a retry policy (#121). An HTTP answer is the server's verdict
+ * and stays terminal on the first attempt: a 404 for a bad channel must fail fast.
+ */
+export async function resolveVersion(
+	channel: Channel,
+	opts: ResolveVersionOptions = {},
+): Promise<string> {
+	const url = `${UPGRADE_BASE}.${channel}`;
+	// Sanitized, not just clamped: these are public options, and `Math.max(1, NaN)`
+	// is NaN — the loop would never run, and the failure would read "all NaN
+	// attempts: undefined" instead of doing anything.
+	const maxAttempts = positiveInt(opts.maxAttempts, VERSION_RESOLVE_MAX_ATTEMPTS);
+	const retryDelayMs = nonNegativeMs(opts.retryDelayMs, VERSION_RESOLVE_RETRY_MS);
+	let lastError: unknown;
+
+	for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+		let text: string;
+		try {
+			const response = await fetchResilient(url);
+			if (!response.ok) {
+				// An HTTP answer is the server's verdict. Thrown as a QuickCHRError so
+				// the catch below can tell it from a transport failure and let it out.
+				throw new QuickCHRError(
+					"DOWNLOAD_FAILED",
+					`Failed to fetch version for channel "${channel}": HTTP ${response.status}`,
+				);
+			}
+			// Inside the try: the body can fail *after* the headers arrive (a reset
+			// mid-response), which is a transport failure like any other and must be
+			// retried rather than escaping the loop unwrapped.
+			text = await response.text();
+		} catch (err) {
+			// Only "could not reach the host at all" is retried. An HTTP verdict, an
+			// abort (the caller gave up) or a real bug surfaces immediately.
+			if (err instanceof QuickCHRError) throw err;
+			if (!isConnectionFailure(err)) throw err;
+			lastError = err;
+			if (attempt < maxAttempts) await Bun.sleep(attempt * retryDelayMs);
+			continue;
+		}
+
+		// Parsing is terminal: the server answered, and answering with something
+		// unparseable is not a condition another attempt can improve.
+		// Response format: "7.22.1 1774276515" (version + unix timestamp)
+		const version = text.trim().split(/\s+/)[0]?.trim();
+		if (!version || !isValidVersion(version)) {
+			throw new QuickCHRError(
+				"INVALID_VERSION",
+				`Unexpected version format for channel "${channel}": "${text.trim()}"`,
+			);
+		}
+
+		return version;
 	}
 
-	return version;
+	// Says "1 attempt" rather than "all 1 attempts" — these land in CI logs.
+	const tries = maxAttempts === 1 ? "1 attempt" : `all ${maxAttempts} attempts`;
+	throw new QuickCHRError(
+		"DOWNLOAD_FAILED",
+		`Failed to fetch version for channel "${channel}" on ${tries}: ` +
+			`${lastError instanceof Error ? lastError.message : String(lastError)}`,
+		`Check network access to ${new URL(url).hostname}, or pass an explicit --version to skip channel resolution.`,
+	);
 }
 
 /** Fetch latest versions for all channels in parallel. */
-export async function resolveAllVersions(): Promise<Record<Channel, string>> {
+export async function resolveAllVersions(
+	opts: ResolveVersionOptions = {},
+): Promise<Record<Channel, string>> {
 	const results = await Promise.all(
-		CHANNELS.map(async (ch) => [ch, await resolveVersion(ch)] as const),
+		CHANNELS.map(async (ch) => [ch, await resolveVersion(ch, opts)] as const),
 	);
 	return Object.fromEntries(results) as Record<Channel, string>;
 }