@tikoci/quickchr 0.2.0

package/src/lib/exec.ts

@@ -0,0 +1,101 @@
+/**
+ * Execute RouterOS CLI commands via the REST /execute endpoint.
+ *
+ * POST /rest/execute  { "script": "<cli-command>", "as-string": true }
+ *
+ * RouterOS 7.1+ exposes this endpoint as a universal command runner.
+ * `as-string` controls fg/bg mode: the **presence** of the key (with any
+ * value — true, false, "", "false") makes it synchronous (fg) and returns
+ * {"ret":"<output>"}. When the key is absent entirely, RouterOS runs the
+ * script in the background and returns a job ID (e.g. {"ret":"*B70A"}).
+ *
+ * The 60-second server-side timeout applies; callers can set a shorter
+ * client-side timeout via AbortSignal.
+ *
+ * Uses node:http with agent:false (no connection pooling). Bun's fetch
+ * pools TCP connections by host:port; RouterOS may return stale session
+ * data on a reused connection immediately after provisioning (SSH key
+ * install leaves state on the connection the verification loop used).
+ */
+
+import type { ExecOptions, ExecResult, ExecTransport } from "./types.ts";
+import { QuickCHRError } from "./types.ts";
+import type { ResolvedAuth } from "./auth.ts";
+import { restPost } from "./rest.ts";
+
+/** Default client-side timeout for exec requests (ms). */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Execute a RouterOS CLI command via POST /rest/execute.
+ *
+ * The command is passed through as-is — no wrapping or transformation.
+ * If you need structured JSON output, wrap the command yourself:
+ *   `:put [:serialize to=json [/system/resource/print]]`
+ *
+ * @param restUrl  Base URL of the CHR REST API, e.g. "http://127.0.0.1:9100"
+ * @param auth     Resolved credentials (from resolveAuth).
+ * @param command  RouterOS CLI command string, e.g. "/system/resource/print"
+ * @param opts     Optional exec settings (timeout).
+ * @returns        ExecResult with output text and transport used.
+ */
+export async function restExecute(
+	restUrl: string,
+	auth: ResolvedAuth,
+	command: string,
+	opts?: Pick<ExecOptions, "timeout">,
+): Promise<ExecResult> {
+	const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+	const url = `${restUrl}/rest/execute`;
+
+	let status: number;
+	let data: string;
+	try {
+		const resp = await restPost(url, auth.header, { script: command, "as-string": true }, timeout);
+		status = resp.status;
+		data = resp.body;
+	} catch (e) {
+		throw new QuickCHRError(
+			"EXEC_FAILED",
+			`exec timed out or failed: ${e instanceof Error ? e.message : String(e)}`,
+		);
+	}
+
+	if (status < 200 || status >= 300) {
+		throw new QuickCHRError(
+			"EXEC_FAILED",
+			`exec failed (HTTP ${status}): ${data || "unknown error"}`,
+		);
+	}
+
+	let output: string;
+	try {
+		const json = JSON.parse(data);
+		output = extractRetValue(json);
+	} catch {
+		// Non-JSON response — return raw text
+		output = data;
+	}
+
+	return { output, via: "rest" as ExecTransport };
+}
+
+/**
+ * Extract the output string from an /execute response.
+ *
+ * With `as-string`, RouterOS always returns { "ret": "<output>" } for
+ * commands that produce output, or [] for void commands (e.g. /log/info).
+ */
+function extractRetValue(json: unknown): string {
+	if (Array.isArray(json)) {
+		if (json.length === 0) return "";
+		return JSON.stringify(json);
+	}
+	if (typeof json === "object" && json !== null) {
+		const obj = json as Record<string, unknown>;
+		if ("ret" in obj) return String(obj.ret);
+		if ("message" in obj) return String(obj.message);
+		return JSON.stringify(obj);
+	}
+	return String(json);
+}

package/src/lib/images.ts

@@ -0,0 +1,167 @@
+/**
+ * Image download, ZIP extraction, and cache management.
+ */
+
+import { existsSync, copyFileSync, readdirSync, renameSync, unlinkSync } from "node:fs";
+import { join, basename } from "node:path";
+import type { Arch } from "./types.ts";
+import { QuickCHRError } from "./types.ts";
+import { chrDownloadUrl, chrImageBasename } from "./versions.ts";
+import { getCacheDir, ensureDir } from "./state.ts";
+import { createLogger, type ProgressLogger } from "./log.ts";
+import { extractZip } from "./zip.ts";
+import { assertSufficientQuickchrStorage } from "./storage.ts";
+
+function finalizeExtractedImage(zipPath: string, imgPath: string): string {
+	if (existsSync(imgPath) && existsSync(zipPath)) {
+		unlinkSync(zipPath);
+	}
+	return imgPath;
+}
+
+/** Download a CHR image ZIP if not already cached. Returns path to the ZIP. */
+export async function downloadImage(
+	version: string,
+	arch: Arch,
+	cacheDir?: string,
+	logger?: ProgressLogger,
+): Promise<string> {
+	const cache = cacheDir ?? getCacheDir();
+	ensureDir(cache);
+
+	const url = chrDownloadUrl(version, arch);
+	const zipName = `${chrImageBasename(version, arch)}.img.zip`;
+	const zipPath = join(cache, zipName);
+
+	if (existsSync(zipPath)) {
+		return zipPath;
+	}
+
+	const log = logger ?? createLogger();
+	log.status(`Downloading CHR ${version} (${arch})...`);
+	log.status(`  ${url}`);
+
+	const MAX_RETRIES = 3;
+	let lastError: Error | undefined;
+
+	for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+		try {
+			const response = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+			// Non-retriable: client errors except 408 (request timeout) and 429
+			// (rate limited), which can be transient on CDNs.
+			if (response.status >= 400 && response.status < 500
+					&& response.status !== 408 && response.status !== 429) {
+				throw new QuickCHRError(
+					"DOWNLOAD_FAILED",
+					`Download failed: HTTP ${response.status} for ${url}`,
+				);
+			}
+			if (!response.ok) {
+				lastError = new Error(`HTTP ${response.status}`);
+			} else {
+				// Stream to disk via arrayBuffer (Bun.write with Response can hang on large files)
+				const buf = await response.arrayBuffer();
+				await Bun.write(zipPath, buf);
+				log.status(`  Saved (${(buf.byteLength / 1024 / 1024).toFixed(1)} MB)`);
+				return zipPath;
+			}
+		} catch (e) {
+			if (e instanceof QuickCHRError) throw e;
+			lastError = e instanceof Error ? e : new Error(String(e));
+		}
+		if (attempt < MAX_RETRIES) {
+			log.status(`  Download failed (attempt ${attempt}/${MAX_RETRIES}), retrying in ${attempt * 2}s...`);
+			await Bun.sleep(attempt * 2000);
+		}
+	}
+
+	throw new QuickCHRError(
+		"DOWNLOAD_FAILED",
+		`Download failed after ${MAX_RETRIES} attempts: ${lastError?.message ?? "unknown error"}`,
+	);
+}
+
+/** Extract the .img from the ZIP. Returns path to the raw .img file. */
+export async function extractImage(
+	zipPath: string,
+	cacheDir?: string,
+	logger?: ProgressLogger,
+): Promise<string> {
+	const cache = cacheDir ?? getCacheDir();
+	ensureDir(cache);
+
+	const imgName = basename(zipPath, ".zip");
+	const imgPath = join(cache, imgName);
+
+	if (existsSync(imgPath)) {
+		return finalizeExtractedImage(zipPath, imgPath);
+	}
+
+	const log = logger ?? createLogger();
+	log.status(`Extracting: ${basename(zipPath)}`);
+
+	extractZip(zipPath, cache);
+
+	// MikroTik x86 ZIPs contain chr-X.Y.Z.img (no arch suffix).
+	// Our ZIP is named chr-X.Y.Z.img.zip (without -x86 for x86). Check if we need to
+	// find the extracted file.
+	if (!existsSync(imgPath)) {
+		const files = readdirSync(cache).filter(
+			(f) => f.endsWith(".img") && f.startsWith("chr-"),
+		);
+		// Find the one that was just extracted (matching version)
+		const expected = files.find((f) => {
+			const base = basename(zipPath, ".img.zip");
+			// chr-7.22.1.img matches chr-7.22.1.img.zip
+			return f === base + ".img" || f.replace("-arm64", "") === base.replace("-arm64", "") + ".img";
+		});
+		if (expected) {
+			const extractedPath = join(cache, expected);
+			if (extractedPath !== imgPath) {
+				renameSync(extractedPath, imgPath);
+			}
+		} else {
+			throw new QuickCHRError(
+				"PROCESS_FAILED",
+				`Expected ${imgPath} after unzip, but not found. Files: ${files.join(", ")}`,
+			);
+		}
+	}
+
+	return finalizeExtractedImage(zipPath, imgPath);
+}
+
+/** Download and extract a CHR image. Returns path to the raw .img in cache. */
+export async function ensureCachedImage(
+	version: string,
+	arch: Arch,
+	cacheDir?: string,
+	logger?: ProgressLogger,
+): Promise<string> {
+	const cache = cacheDir ?? getCacheDir();
+	const imgPath = join(cache, `${chrImageBasename(version, arch)}.img`);
+	if (existsSync(imgPath)) {
+		const log = logger ?? createLogger();
+		log.status(`  Using cached image: ${chrImageBasename(version, arch)}`);
+		return 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;
+}
+
+/** List cached images. */
+export function listCachedImages(cacheDir?: string): string[] {
+	const cache = cacheDir ?? getCacheDir();
+	if (!existsSync(cache)) return [];
+	return readdirSync(cache).filter((f) => f.endsWith(".img"));
+}

package/src/lib/license.ts

@@ -0,0 +1,292 @@
+/**
+ * CHR license management — renew/get via /system/license REST endpoint.
+ *
+ * Free CHR runs at 1 Mbps. A trial license from MikroTik unlocks full speed:
+ *   p1  → 1 Gbps
+ *   p10 → 10 Gbps
+ *   unlimited → no cap
+ *
+ * License is applied by POST /rest/system/license/renew with MikroTik.com
+ * account credentials. No reboot required — takes effect immediately.
+ */
+
+import type { LicenseLevel, LicenseOptions } from "./types.ts";
+import { QuickCHRError } from "./types.ts";
+import { createLogger, type ProgressLogger } from "./log.ts";
+import { restGet, restPost } from "./rest.ts";
+
+/** Default timeout for waiting for a license change to propagate (ms). */
+const LICENSE_VERIFY_TIMEOUT = 90_000;
+
+/** Max attempts for the renew POST itself (retried on post-boot REST quirk). */
+const MAX_RENEW_ATTEMPTS = 3;
+
+/** Classify the response body from POST /rest/system/license/renew.
+ *
+ *  Observed RouterOS responses (confirmed via curl experiments):
+ *
+ *  SUCCESS:
+ *    [{".section":"0","status":"connecting"},{".section":"1","status":"done"}]
+ *    → Last entry status="done" — license server accepted the request.
+ *
+ *  ERROR (various):
+ *    [{".section":"0","status":"connecting"},{".section":"1","status":"ERROR: Licensing Error: too many trial licences"}]
+ *    [{".section":"0","status":"connecting"},{".section":"1","status":"ERROR: Unauthorized"}]
+ *    → Last entry status starts with "ERROR:" — server rejected. Do NOT retry, do NOT poll.
+ *
+ *  NOT-READY (post-boot REST quirk):
+ *    {"board-name":"CHR","architecture-name":"x86_64",...}
+ *    → System resource data leaked through. The endpoint isn't initialized. Retry the POST.
+ *
+ *  HTTP 400: {"detail":"missing =account=","error":400,"message":"Bad Request"}
+ *    → Caught before this function (HTTP status check).
+ */
+function classifyRenewResponse(text: string): "done" | "error" | "pending" | "not-ready" {
+	try {
+		const data = JSON.parse(text);
+
+		if (Array.isArray(data)) {
+			const last = data[data.length - 1];
+			if (last && typeof last === "object" && typeof last.status === "string") {
+				if (last.status === "done") return "done";
+				if (last.status.startsWith("ERROR:")) return "error";
+			}
+			return "pending";
+		}
+
+		if (data && typeof data === "object") {
+			if ("board-name" in data || "architecture-name" in data) return "not-ready";
+		}
+	} catch { /* unparseable — treat as pending */ }
+
+	return "pending";
+}
+
+/** Apply or renew a CHR trial license via /system/license/renew.
+ *  @param httpPort   REST API port (e.g. 9180)
+ *  @param opts       MikroTik account credentials + desired level
+ *  @param chrUser    RouterOS admin username (default "admin")
+ *  @param chrPass    RouterOS admin password (default "" for fresh CHR)
+ *  @param logger     Optional progress logger
+ *  @param authHeader Pre-built Authorization header (overrides chrUser/chrPass when provided)
+ */
+export async function renewLicense(
+	httpPort: number,
+	opts: LicenseOptions,
+	chrUser = "admin",
+	chrPass = "",
+	logger?: ProgressLogger,
+	authHeader?: string,
+): Promise<void> {
+	const log = logger ?? createLogger();
+	const auth = authHeader ?? `Basic ${btoa(`${chrUser}:${chrPass}`)}`;
+	const body: Record<string, string> = {};
+	if (opts.account) body.account = opts.account;
+	if (opts.password) body.password = opts.password;
+	if (opts.level) body.level = opts.level;
+	// duration=10s: ask RouterOS to wait up to 10s for the MikroTik license server
+	// before responding. Without this, RouterOS does one short internal poll (~1-2s)
+	// and returns before the activation has propagated, forcing a long polling loop.
+	body.duration = "10s";
+
+	// Wait for the license subsystem to be ready — right after boot, RouterOS may
+	// return system resource data for all REST endpoints (see waitForBoot stage 4).
+	await waitForLicenseApi(httpPort, chrUser, chrPass, 30_000, auth);
+
+	for (let attempt = 1; attempt <= MAX_RENEW_ATTEMPTS; attempt++) {
+		let status: number;
+		let text: string;
+		try {
+			const resp = await restPost(
+				`http://127.0.0.1:${httpPort}/rest/system/license/renew`,
+				auth,
+				body,
+				30_000, // 10s for RouterOS wait + 20s net overhead
+			);
+			status = resp.status;
+			text = resp.body;
+		} catch (e) {
+			throw new QuickCHRError(
+				"PROCESS_FAILED",
+				`License renewal request failed: ${e instanceof Error ? e.message : String(e)}`,
+			);
+		}
+
+		if (status < 200 || status >= 300) {
+			throw new QuickCHRError(
+				"PROCESS_FAILED",
+				`License renewal failed: HTTP ${status} — ${text}`,
+			);
+		}
+
+		log.debug(`License renew response body: ${text}`);
+		const result = classifyRenewResponse(text);
+
+		if (result === "error") {
+			// Extract the actual error message from the RouterOS response
+			let errorDetail = text;
+			try {
+				const data = JSON.parse(text);
+				if (Array.isArray(data)) {
+					const last = data[data.length - 1];
+					if (last?.status) errorDetail = last.status;
+				}
+			} catch { /* use raw text */ }
+			throw new QuickCHRError(
+				"PROCESS_FAILED",
+				`License renewal rejected by MikroTik: ${errorDetail}`,
+			);
+		}
+
+		if (result === "not-ready") {
+			if (attempt < MAX_RENEW_ATTEMPTS) {
+				log.warn(`License renew attempt ${attempt}: got system resource data instead of renew status — retrying`);
+				await Bun.sleep(5000);
+				continue;
+			}
+			throw new QuickCHRError(
+				"PROCESS_FAILED",
+				"License renew endpoint returned system resource data after multiple attempts — REST API not fully initialized",
+			);
+		}
+
+		if (!opts.level) return; // fire-and-forget, no level verification needed
+
+		// result is "done" or "pending" — poll until the level matches.
+		// "done" means the license server responded within the duration window;
+		// a single verification poll should suffice but we use the same loop.
+		const deadline = Date.now() + LICENSE_VERIFY_TIMEOUT;
+		let pollCount = 0;
+		while (Date.now() < deadline) {
+			try {
+				const info = await getLicenseInfo(httpPort, chrUser, chrPass, auth);
+				pollCount++;
+				log.debug(`License poll #${pollCount}: level=${info.level}, want=${opts.level}`);
+				if (info.level === opts.level) return;
+			} catch (e) {
+				pollCount++;
+				log.warn(`License poll #${pollCount} error: ${e instanceof Error ? e.message : String(e)}`);
+			}
+			await Bun.sleep(2000);
+		}
+		throw new QuickCHRError(
+			"PROCESS_FAILED",
+			`License renewal accepted but level did not change to "${opts.level}" within ${LICENSE_VERIFY_TIMEOUT / 1000}s`,
+		);
+	}
+}
+
+/** Wait until GET /rest/system/license returns actual license data.
+ *  Right after boot, RouterOS may return system resource data for all endpoints.
+ *  Real license data contains "system-id"; system resource data has "board-name". */
+async function waitForLicenseApi(
+	httpPort: number,
+	chrUser: string,
+	chrPass: string,
+	timeoutMs = 30_000,
+	authHeader?: string,
+): Promise<void> {
+	const auth = authHeader ?? `Basic ${btoa(`${chrUser}:${chrPass}`)}`;
+	const deadline = Date.now() + timeoutMs;
+
+	while (Date.now() < deadline) {
+		try {
+			const { status, body } = await restGet(
+				`http://127.0.0.1:${httpPort}/rest/system/license`,
+				auth,
+				5000,
+			);
+			if (status >= 200 && status < 300) {
+				const data = JSON.parse(body) as Record<string, unknown>;
+				if ("system-id" in data && !("board-name" in data)) return;
+			}
+		} catch { /* not ready */ }
+		await Bun.sleep(2000);
+	}
+	// Don't throw — the renew POST itself will detect and retry on bad responses.
+	console.warn("License API readiness check timed out — proceeding with renewal attempt");
+}
+
+/** Fetch the current license state from a running CHR.
+ *  Uses GET /rest/system/license (standard REST read for a single-object menu).
+ *  Normalises the response: RouterOS omits `level` for the implicit "free" tier,
+ *  so we fill it in when absent.
+ *  @param authHeader Pre-built Authorization header (overrides chrUser/chrPass when provided)
+ */
+export async function getLicenseInfo(
+	httpPort: number,
+	chrUser = "admin",
+	chrPass = "",
+	authHeader?: string,
+	retryMs = 15_000,
+): Promise<LicenseInfo> {
+	const auth = authHeader ?? `Basic ${btoa(`${chrUser}:${chrPass}`)}`;
+
+	// RouterOS briefly serves /system/resource data from /system/license immediately
+	// after boot (REST routing startup race). Retry for up to retryMs to let it settle.
+	// do-while ensures at least one attempt even when retryMs=0 (useful in tests).
+	const deadline = Date.now() + retryMs;
+	let lastError: unknown;
+
+	do {
+		let status: number;
+		let body: string;
+		try {
+			const resp = await restGet(
+				`http://127.0.0.1:${httpPort}/rest/system/license`,
+				auth,
+				10_000,
+			);
+			status = resp.status;
+			body = resp.body;
+		} catch (e) {
+			lastError = e;
+			// Skip the sleep when past the deadline (e.g. retryMs=0 in tests).
+			await Bun.sleep(Math.max(0, Math.min(1000, deadline - Date.now())));
+			continue;
+		}
+
+		if (status < 200 || status >= 300) {
+			throw new QuickCHRError(
+				"PROCESS_FAILED",
+				`Failed to get license info: HTTP ${status} — ${body}`,
+			);
+		}
+
+		let info: LicenseInfo;
+		try { info = JSON.parse(body) as LicenseInfo; } catch {
+			lastError = new Error(`Invalid JSON from /system/license: ${body}`);
+			await Bun.sleep(Math.max(0, Math.min(1000, deadline - Date.now())));
+			continue;
+		}
+		// Post-boot REST quirk: /system/license may return /system/resource data briefly.
+		// Retry until the endpoint stabilises rather than failing to the caller.
+		if ("board-name" in info || "architecture-name" in info) {
+			await Bun.sleep(Math.max(0, Math.min(1000, deadline - Date.now())));
+			continue;
+		}
+		// RouterOS REST omits default / empty fields. A CHR with no registered license
+		// is implicitly "free" — normalise to the explicit string so callers can always
+		// read info.level without special-casing undefined.
+		if (!info.level) info.level = "free";
+		return info;
+	} while (Date.now() < deadline);
+
+	const msg = lastError instanceof Error ? lastError.message : String(lastError ?? "timed out");
+	throw new QuickCHRError(
+		"PROCESS_FAILED",
+		`License info request failed after retries: ${msg}`,
+	);
+}
+
+/** Parsed response from /rest/system/license/get */
+export interface LicenseInfo {
+	/** License level: "free", "p1", "p10", "unlimited", etc. */
+	level?: LicenseLevel | "free" | string;
+	/** Deadline in ISO-8601 format if on a trial. */
+	deadline?: string;
+	/** System ID used for activation. */
+	"system-id"?: string;
+	/** Any other fields RouterOS returns. */
+	[key: string]: unknown;
+}

package/src/lib/log.ts

@@ -0,0 +1,41 @@
+/**
+ * Structured logging for quickchr library code.
+ * Routes messages through onProgress callback when provided,
+ * falls back to console.log/console.warn.
+ * Debug messages are suppressed unless QUICKCHR_DEBUG=1.
+ */
+
+const isDebug = () => process.env.QUICKCHR_DEBUG === "1";
+
+export interface ProgressLogger {
+	/** User-facing status message (e.g. "Uploading: foo.npk") */
+	status(message: string): void;
+	/** Debug message — only shown when QUICKCHR_DEBUG=1 */
+	debug(message: string): void;
+	/** Warning — always shown */
+	warn(message: string): void;
+}
+
+/** Create a logger from an optional onProgress callback. */
+export function createLogger(onProgress?: (message: string) => void): ProgressLogger {
+	return {
+		status(message: string) {
+			if (onProgress) {
+				onProgress(message);
+			} else {
+				console.log(message);
+			}
+		},
+		debug(message: string) {
+			if (!isDebug()) return;
+			if (onProgress) {
+				onProgress(`[debug] ${message}`);
+			} else {
+				console.error(`[debug] ${message}`);
+			}
+		},
+		warn(message: string) {
+			console.warn(message);
+		},
+	};
+}