@tikoci/quickchr 0.4.0 → 0.4.1

package/DESIGN.md

@@ -46,6 +46,14 @@ Modules (src/lib/)      ← qemu, images, versions, network, state, ...
 
    How to tell it's firing: grep CI `qemu.log`/run logs for `respawning QEMU once`. A frequent occurrence, or a `BOOT_TIMEOUT` that *survives* the respawn (or appears on the `_launchExisting` path), is the signal to stop treating it as a flake and find the real cause. Tracked in `BACKLOG.md` (boot-respawn watch-item).
 
+9. **Resilient downloads via public DNS** — All fetches to MikroTik's `upgrade`/`download` hosts go through `fetchResilient()` (`src/lib/net.ts`), never bare `fetch()`. The real failure mode, confirmed by an on-runner probe (2026-06-16), is that **GitHub-hosted runners' system resolver returns `ESERVFAIL` for `*.mikrotik.com`** — slowly (2–26 s) — via *both* `getaddrinfo` and c-ares-over-`resolv.conf`. So a plain `fetch` either times out resolving or (when the stub hands back only the unreachable AAAA) fails with Bun's `errno: 0` `ConnectionRefused` / `FailedToOpenSocket`. A **direct query to a public resolver (1.1.1.1 / 8.8.8.8) answers in ~10 ms**, and the hosts have a reachable IPv4. The earlier "IPv6 happy-eyeballs" theory was a red herring — the primary fault is DNS resolution at the runner's stub, not IPv6 egress.
+
+   Measured on the CI runner: `lookup({family:4})` → `ESERVFAIL` ~9 s; `lookup({all})` → `ESERVFAIL`/`ETIMEOUT` 22–26 s; `resolve4` (resolv.conf) → `ESERVFAIL` 2–22 s; `Resolver([1.1.1.1,8.8.8.8]).resolve4` → **OK ~10 ms**.
+
+   `fetchResilient` resolves the A record by querying public DNS **directly** (a `dns.Resolver` with `setServers([1.1.1.1, 8.8.8.8, 1.0.0.1])`, bounded by a 3 s timeout so a blocked resolver doesn't stall), then connects to the IPv4 literal preserving the `Host` header and TLS SNI so certificate validation still passes. It falls back to a normal `fetch` (system resolver, dual-stack) only when public DNS is unavailable — e.g. a network that blocks public resolvers — so it stays correct off CI. HTTP responses and aborts/timeouts pass through unchanged, never retried. `dns.resolve4`/`getaddrinfo` are deliberately **not** used for the primary path because they inherit the runner's broken stub.
+
+   ⚠️ **Sister-project routing.** A download/version-resolve failure that only appears on CI (slow `ESERVFAIL`, or `errno: 0` from `resolveVersion`) is a **quickchr** concern, not the consuming project's — do not paper over it downstream with `/etc/hosts` pins or IPv6 toggles in the sister repo's workflow. The historical `getent ahostsv4` `/etc/hosts` workaround was both in the wrong layer and non-functional (it hit the same broken stub resolver, returning empty). Covered by `test/unit/net.test.ts`.
+
 ## Port Layout
 
 | Offset | Service    | Guest Port |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/quickchr",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "CLI and library to download, launch, and manage MikroTik CHR virtual machines via QEMU",
   "module": "src/index.ts",
   "main": "src/index.ts",

package/src/lib/images.ts

@@ -7,6 +7,7 @@ import { join, basename } from "node:path";
 import type { Arch } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
 import { chrDownloadUrl, chrImageBasename } from "./versions.ts";
+import { fetchResilient } from "./net.ts";
 import { getCacheDir, ensureDir } from "./state.ts";
 import { createLogger, type ProgressLogger } from "./log.ts";
 import { extractZip } from "./zip.ts";
@@ -46,7 +47,7 @@ export async function downloadImage(
 
 	for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
 		try {
-			const response = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+			const response = await fetchResilient(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

package/src/lib/net.ts

@@ -0,0 +1,123 @@
+/**
+ * Resilient HTTP fetch for MikroTik's download hosts.
+ *
+ * On GitHub-hosted CI runners the system DNS resolver returns `ESERVFAIL`
+ * (slowly — 2 to 26 s) for `upgrade.mikrotik.com` / `download.mikrotik.com` via
+ * both `getaddrinfo` and c-ares-over-resolv.conf, so a plain `fetch` either
+ * times out or (when the stub hands back only the unreachable AAAA) fails with
+ * Bun's `errno: 0` ConnectionRefused / FailedToOpenSocket. A direct query to a
+ * public resolver answers in ~10 ms, and the hosts are dual-stack with a
+ * reachable IPv4. quickchr is expected to run unattended in CI, so it resolves
+ * these hosts itself rather than trusting the runner's broken resolver.
+ *
+ * Strategy: resolve the A record by querying a public DNS server directly
+ * (bypassing the host's resolv.conf), then connect to the IPv4 literal,
+ * preserving the `Host` header and TLS SNI so certificate validation still
+ * passes. Fall back to a normal `fetch` (system resolver, dual-stack) when the
+ * public-DNS path is unavailable — e.g. a network that blocks public resolvers
+ * — so this stays correct off CI. HTTP responses and aborts/timeouts pass
+ * through unchanged; they are never retried.
+ */
+
+import { promises as dns } from "node:dns";
+
+const PUBLIC_DNS_SERVERS = ["1.1.1.1", "8.8.8.8", "1.0.0.1"];
+const DNS_TIMEOUT_MS = 3000;
+
+/**
+ * True for the connection-class failures raised when a socket cannot be opened
+ * (e.g. IPv4 blocked on an IPv6-only network, or Bun's `errno: 0`
+ * ConnectionRefused / FailedToOpenSocket against an unreachable address), plus
+ * the standard connect errors. Excludes aborts/timeouts and HTTP-level outcomes
+ * (those carry a Response and never throw here). Used to decide whether to fall
+ * back from the IPv4 attempt to a normal dual-stack fetch.
+ */
+export function isConnectionFailure(err: unknown): boolean {
+	if (!err || typeof err !== "object") return false;
+	const e = err as { name?: string; code?: string; cause?: { code?: string } };
+	if (e.name === "AbortError") return false;
+	const code = e.code ?? e.cause?.code;
+	if (
+		code === "ConnectionRefused" ||
+		code === "FailedToOpenSocket" ||
+		code === "ConnectionClosed" ||
+		code === "ECONNREFUSED" ||
+		code === "ECONNRESET" ||
+		code === "EHOSTUNREACH" ||
+		code === "ENETUNREACH" ||
+		code === "ETIMEDOUT"
+	) {
+		return true;
+	}
+	// Bun wraps low-level connect failures as a bare TypeError ("Unable to
+	// connect…"). Treat those as retriable too; a wrong guess only costs one
+	// normal fetch, which then surfaces the real error if it also fails.
+	return e.name === "TypeError";
+}
+
+/** Rewrite a URL to target an explicit IPv4 literal, preserving port/path/query. */
+export function toIpv4Url(url: string, address: string): string {
+	const u = new URL(url);
+	u.hostname = address;
+	return u.toString();
+}
+
+/**
+ * Resolve a host's A record via public DNS servers directly, bypassing the
+ * host's resolv.conf (which is broken for these names on CI runners). Returns
+ * undefined — never throws — when public DNS is unreachable or has no answer,
+ * so the caller can fall back to a normal fetch. Bounded by DNS_TIMEOUT_MS so a
+ * blocked resolver does not stall the request.
+ */
+async function resolveIpv4(host: string): Promise<string | undefined> {
+	const resolver = new dns.Resolver();
+	resolver.setServers(PUBLIC_DNS_SERVERS);
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	try {
+		const addresses = await Promise.race([
+			resolver.resolve4(host),
+			new Promise<string[]>((_, reject) => {
+				timer = setTimeout(() => reject(new Error("public DNS timeout")), DNS_TIMEOUT_MS);
+			}),
+		]);
+		return addresses[0];
+	} catch {
+		return undefined;
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+
+async function fetchOverIpv4(
+	url: string,
+	address: string,
+	init?: BunFetchRequestInit,
+): Promise<Response> {
+	const host = new URL(url).hostname;
+	const headers = new Headers(init?.headers);
+	headers.set("Host", host);
+	return fetch(toIpv4Url(url, address), {
+		...init,
+		headers,
+		tls: { serverName: host, ...init?.tls },
+	});
+}
+
+/**
+ * `fetch()` that resolves dual-stack hosts via public DNS and connects over
+ * IPv4, so it survives a broken/slow system resolver (e.g. GitHub-hosted CI
+ * runners). Falls back to a normal `fetch` when public DNS is unavailable.
+ * Behaves like `fetch` for HTTP responses and aborts.
+ */
+export async function fetchResilient(url: string, init?: BunFetchRequestInit): Promise<Response> {
+	const address = await resolveIpv4(new URL(url).hostname);
+	if (address) {
+		try {
+			return await fetchOverIpv4(url, address, init);
+		} catch (err) {
+			if (!isConnectionFailure(err)) throw err;
+			// IPv4 unreachable (e.g. IPv6-only egress) — fall through to a normal fetch.
+		}
+	}
+	return fetch(url, init);
+}

package/src/lib/packages.ts

@@ -7,6 +7,7 @@ import { join, basename } from "node:path";
 import type { Arch } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
 import { packagesDownloadUrl } from "./versions.ts";
+import { fetchResilient } from "./net.ts";
 import { getCacheDir, ensureDir } from "./state.ts";
 import { createLogger, type ProgressLogger } from "./log.ts";
 import { restPost } from "./rest.ts";
@@ -38,7 +39,7 @@ export async function downloadPackages(
 	if (!existsSync(zipPath)) {
 		const log = logger ?? createLogger();
 		log.status(`Downloading packages for ${version} (${arch})...`);
-		const response = await fetch(url);
+		const response = await fetchResilient(url);
 		if (!response.ok) {
 			throw new QuickCHRError(
 				"DOWNLOAD_FAILED",

package/src/lib/rest.ts

@@ -10,8 +10,8 @@
  * because Bun's node:http req.destroy() does not reliably emit the
  * "error" event, which would leave the Promise pending forever.
  *
- * External URLs (mikrotik.com, upgrade server) use fetch() — no pool
- * issue there. This module is ONLY for CHR REST calls (127.0.0.1).
+ * External URLs (mikrotik.com, upgrade server) use fetchResilient() (net.ts) —
+ * no pool issue there. This module is ONLY for CHR REST calls (127.0.0.1).
  */
 
 import { request as nodeRequest } from "node:http";

package/src/lib/versions.ts

@@ -4,6 +4,7 @@
 
 import type { Arch, Channel } from "./types.ts";
 import { QuickCHRError } from "./types.ts";
+import { fetchResilient } from "./net.ts";
 
 const UPGRADE_BASE = "https://upgrade.mikrotik.com/routeros/NEWESTa7";
 const DOWNLOAD_BASE = "https://download.mikrotik.com/routeros";
@@ -68,7 +69,7 @@ export function provisioningSupportHint(minimumVersion = MIN_PROVISION_VERSION):
 export async function resolveVersion(channel: Channel): Promise<string> {
 	const url = `${UPGRADE_BASE}.${channel}`;
 
-	const response = await fetch(url);
+	const response = await fetchResilient(url);
 	if (!response.ok) {
 		throw new QuickCHRError(
 			"DOWNLOAD_FAILED",