@usequark/quark-core 2.5.7 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-core",
-  "version": "2.5.7",
+  "version": "2.6.0",
   "description": "Core utilities for Quark apps: auth, BullMQ queues, Redis, email, storage, rate limiting, logging, and error handling",
   "keywords": [
     "quark",
@@ -35,6 +35,7 @@
     "./db": "./src/db.js",
     "./email": "./src/email.js",
     "./errors": "./src/errors.js",
+    "./health": "./src/health.js",
     "./locale": "./src/locale.js",
     "./logger": "./src/logger.js",
     "./metrics": "./src/metrics.js",

package/src/exports.test.js

@@ -10,6 +10,7 @@ import * as coreLight from "@usequark/quark-core/core";
 import * as db from "@usequark/quark-core/db";
 import * as email from "@usequark/quark-core/email";
 import * as errors from "@usequark/quark-core/errors";
+import * as health from "@usequark/quark-core/health";
 import * as locale from "@usequark/quark-core/locale";
 import * as logger from "@usequark/quark-core/logger";
 import * as metrics from "@usequark/quark-core/metrics";
@@ -90,6 +91,22 @@ test("subpath './errors' exports error classes", () => {
 	assert.equal(typeof errors.ForbiddenError, "function");
 });
 
+test("subpath './health' exports the health-check API", () => {
+	assert.equal(typeof health.runHealthChecks, "function");
+	assert.equal(typeof health.checkStorage, "function");
+	assert.equal(typeof health.checkQueues, "function");
+	assert.equal(typeof health.createDefaultProbes, "function");
+	assert.equal(typeof health.isFailing, "function");
+});
+
+test("subpath '.' (full barrel) re-exports the health-check API", () => {
+	// The scaffolded route imports these from the barrel, so a subpath-only export
+	// would leave it broken.
+	assert.equal(typeof core.runHealthChecks, "function");
+	assert.equal(typeof core.checkStorage, "function");
+	assert.equal(typeof core.checkQueues, "function");
+});
+
 test("subpath './logger' exports the browser-safe logger", () => {
 	assert.equal(typeof logger.createLogger, "function");
 });

package/src/health.js

@@ -0,0 +1,315 @@
+/**
+ * @usequark/quark-core - Health Checks
+ *
+ * Dependency health probing for the platform healthcheck endpoint.
+ *
+ * Two invariants this module exists to hold:
+ *
+ * 1. **The aggregate completes inside one overall deadline.** Every probe runs
+ *    concurrently and under its own deadline, clamped to the overall budget, so
+ *    a hung dependency cannot hold the request open. Run sequentially, the sum
+ *    of three 3s timeouts exhausts a 5s budget before the last probe starts —
+ *    and an exhausted budget reads as a dead service.
+ *
+ * 2. **No message leaves carrying a credential.** Driver errors embed the
+ *    connection string they failed on. Probes are normalised in one place so
+ *    both failure shapes — rejecting, *and* resolving with
+ *    `{ status: "error", message }` — pass through redaction. Handling only
+ *    rejections is what let `pingRedis` publish the Redis password from an
+ *    unauthenticated endpoint once already.
+ *
+ * Usage:
+ *   const report = await runHealthChecks({
+ *     probes: { database: pingDatabase, storage: checkStorage },
+ *   });
+ *   // → { status: "ok" | "degraded", checks: { database: {...} } }
+ */
+
+import { createLogger } from "./logger.js";
+import { createStorage } from "./storage.js";
+import { redactUrl } from "./utils.js";
+
+const logger = createLogger("health");
+
+/** Ceiling for one dependency probe (ms). Clamped to the overall budget. */
+export const DEFAULT_PROBE_TIMEOUT = 3000;
+
+/** Ceiling for the whole check (ms). */
+export const DEFAULT_HEALTH_TIMEOUT = 5000;
+
+/**
+ * Message returned in place of a real error when NODE_ENV is production.
+ * Keyed by probe name.
+ */
+const GENERIC_MESSAGES = {
+	database: "Database unavailable",
+	redis: "Redis unavailable",
+	storage: "Storage unavailable",
+	queue: "Queue unavailable",
+};
+
+/**
+ * Runs every dependency probe concurrently and aggregates the results.
+ *
+ * Never rejects: each probe is individually settled and deadline-bounded, so a
+ * rejecting probe becomes a `{ status: "error" }` entry rather than an exception
+ * out of the aggregate.
+ *
+ * @param {object} options
+ * @param {Record<string, () => Promise<object>|object>} options.probes - Probe name → probe fn.
+ * @param {number} [options.timeout=5000] - Overall budget in ms.
+ * @param {number} [options.probeTimeout=3000] - Per-probe budget in ms.
+ * @returns {Promise<{ status: string, timestamp: string, durationMs: number, checks: Record<string, object> }>}
+ */
+export async function runHealthChecks({
+	probes,
+	timeout = DEFAULT_HEALTH_TIMEOUT,
+	probeTimeout = DEFAULT_PROBE_TIMEOUT,
+} = {}) {
+	const startedAt = performance.now();
+	const names = Object.keys(probes ?? {});
+
+	// Every probe is wrapped in settleProbe(), so this Promise.all cannot reject
+	// and cannot outlast the deadline. Concurrency is the point: three sequential
+	// 3s probes would exceed a 5s budget on their own.
+	const settled = await Promise.all(
+		names.map((name) =>
+			settleProbe(name, probes[name], { timeout, probeTimeout }),
+		),
+	);
+
+	const checks = {};
+	for (let i = 0; i < names.length; i++) {
+		const result = settled[i];
+		// A probe may return null to opt out (e.g. queues when none are registered
+		// in this process). Omitting the key is honest; reporting a false pass is not.
+		if (result !== null) checks[names[i]] = result;
+	}
+
+	return {
+		// "degraded" means at least one dependency failed. The HTTP status is the
+		// caller's decision — see the module comment on why it is not derived here.
+		status: Object.values(checks).some(isFailing) ? "degraded" : "ok",
+		timestamp: new Date().toISOString(),
+		durationMs: Math.round(performance.now() - startedAt),
+		checks,
+	};
+}
+
+/**
+ * Reports whether a check entry counts as a failure. Handles both a flat probe
+ * result (`{ status: "error" }`) and the nested queue map, where the verdict
+ * lives on each queue rather than on the map itself.
+ *
+ * @param {unknown} check
+ * @returns {boolean}
+ */
+export function isFailing(check) {
+	if (!check || typeof check !== "object") return false;
+
+	// A flat probe result carries its own `status`. The nested queue map does not,
+	// so fall through to its entries.
+	if (typeof check.status === "string") {
+		return check.status === "error";
+	}
+
+	return Object.values(check).some((entry) => entry?.status === "error");
+}
+
+/**
+ * Runs one dependency probe with its own deadline and normalises every failure
+ * mode — rejection, timeout, or a probe that never settles — into a result
+ * object. Never throws, so callers can rely on `Promise.all` resolving.
+ *
+ * @param {string} name - Probe name, also the key under `checks`.
+ * @param {() => Promise<object>|object} probe
+ * @param {object} [options]
+ * @param {number} [options.timeout]
+ * @param {number} [options.probeTimeout]
+ * @returns {Promise<object|null>}
+ */
+async function settleProbe(name, probe, { timeout, probeTimeout }) {
+	// A probe that hangs must not hold up the aggregate, and must never outlive
+	// the overall budget. The timer is always cleared, so it never leaks.
+	let timer;
+	const deadline = new Promise((resolve) => {
+		timer = setTimeout(
+			() => resolve({ status: "error", message: `${name} check timed out` }),
+			Math.min(probeTimeout, timeout),
+		);
+	});
+
+	try {
+		const result = await Promise.race([
+			Promise.resolve().then(probe),
+			deadline,
+		]);
+		// A probe that opts out (null/undefined) is reported as absent, not as a pass.
+		if (result === null || result === undefined) return null;
+		return withSafeMessage(name, result);
+	} catch (error) {
+		return withSafeMessage(name, { status: "error", message: error?.message });
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/**
+ * Returns a check result whose message is safe to serve publicly.
+ *
+ * A probe can signal failure two ways — by rejecting, or by *resolving* with
+ * `{ status: "error", message }`. Both are routed through here so neither can
+ * bypass the redaction.
+ *
+ * @param {string} name - Probe name.
+ * @param {object} [result]
+ * @returns {object}
+ */
+function withSafeMessage(name, result) {
+	if (result?.status !== "error") return result;
+
+	const { message, ...rest } = result;
+	return { ...rest, status: "error", message: safeMessage(name, message) };
+}
+
+/**
+ * Reduces a failure to a message safe to return from an unauthenticated route.
+ *
+ * Driver errors carry the connection string they failed on, so the raw text is
+ * only echoed outside production — and even then it goes through `redactUrl()`
+ * first, which strips any userinfo segment that survived the driver's own
+ * formatting. In production a fixed generic message is returned.
+ *
+ * @param {string} name - Probe name.
+ * @param {string|Error} [source] - The failure message or the error itself.
+ * @returns {string}
+ */
+function safeMessage(name, source) {
+	if (process.env.NODE_ENV === "production") {
+		return GENERIC_MESSAGES[name] ?? "Check unavailable";
+	}
+
+	const text = source?.message ?? (typeof source === "string" ? source : "");
+	if (!text) return "Unknown error";
+	return redactUrl(text);
+}
+
+/**
+ * Verifies storage is reachable and writable by writing then deleting a small
+ * sentinel object. Uses whichever provider is configured via STORAGE_PROVIDER
+ * (defaults to "local" when unset).
+ *
+ * Deliberately a real round-trip rather than a `stat`: `stat` only proves a
+ * path exists and cannot tell a read-only mount from a writable one, which is
+ * the only failure this check exists to catch. The sentinel also works
+ * unchanged for S3/R2, where a filesystem permission check means nothing.
+ *
+ * @returns {Promise<{ status: string, provider: string }>}
+ */
+export async function checkStorage() {
+	const provider = process.env.STORAGE_PROVIDER || "local";
+	const storage = createStorage();
+	const sentinelKey = ".health-check-sentinel";
+
+	await storage.put(sentinelKey, Buffer.from("ok"), {
+		contentType: "text/plain",
+	});
+	await storage.delete(sentinelKey);
+
+	return { status: "ok", provider };
+}
+
+/**
+ * Reports queue depths. Only meaningful in a process that registered the
+ * queues, so this resolves to null when none are registered and the key is
+ * omitted from the report rather than reported as a false pass.
+ *
+ * @returns {Promise<Record<string, { status: string, waiting?: number, active?: number, failed?: number, message?: string }> | null>}
+ */
+export async function checkQueues(getRegisteredQueues) {
+	const registeredQueues = getRegisteredQueues();
+	if (registeredQueues.size === 0) return null;
+
+	const entries = [...registeredQueues.entries()];
+	const results = await Promise.allSettled(
+		entries.map(([, queue]) =>
+			Promise.all([
+				queue.getWaitingCount(),
+				queue.getActiveCount(),
+				queue.getFailedCount(),
+			]),
+		),
+	);
+
+	const queueChecks = {};
+
+	for (let i = 0; i < entries.length; i++) {
+		const [name] = entries[i];
+		const result = results[i];
+
+		if (result.status === "fulfilled") {
+			const [waiting, active, failed] = result.value;
+			queueChecks[name] = { status: "ok", waiting, active, failed };
+		} else {
+			queueChecks[name] = withSafeMessage("queue", {
+				status: "error",
+				message: result.reason?.message,
+			});
+		}
+	}
+
+	return queueChecks;
+}
+
+/**
+ * Composes the default probe set for a Quark app: the dependencies in
+ * `@usequark/quark-core` itself.
+ *
+ * `pingDatabase` is not imported here — it lives in `@usequark/quark-db`, which
+ * depends on this package, so importing it here would be circular. Callers pass
+ * it in:
+ *
+ *   import { pingDatabase } from "@usequark/quark-db";
+ *   import { getRegisteredQueues, pingRedis } from "@usequark/quark-core";
+ *   import { runHealthChecks, checkStorage, checkQueues } from "@usequark/quark-core/health";
+ *
+ *   const report = await runHealthChecks({
+ *     probes: {
+ *       database: pingDatabase,
+ *       redis: pingRedis,
+ *       storage: checkStorage,
+ *       queues: () => checkQueues(getRegisteredQueues),
+ *     },
+ *   });
+ *
+ * @param {object} deps
+ * @param {() => Promise<object>} deps.pingDatabase
+ * @param {() => Promise<object>} [deps.pingRedis]
+ * @param {() => Map<string, object>} deps.getRegisteredQueues
+ * @returns {Record<string, () => Promise<object>>}
+ */
+export function createDefaultProbes({
+	pingDatabase,
+	pingRedis,
+	getRegisteredQueues,
+}) {
+	return {
+		database: pingDatabase,
+		...(pingRedis ? { redis: pingRedis } : {}),
+		storage: checkStorage,
+		queues: () => checkQueues(getRegisteredQueues),
+	};
+}
+
+/**
+ * Logs a health report. Useful for startup logging, where the report is wanted
+ * in the log stream but not returned to a caller.
+ *
+ * @param {{ status: string, checks: Record<string, object> }} report
+ */
+export function logHealthReport(report) {
+	logger.info("Health report", {
+		status: report.status,
+		checks: Object.keys(report.checks ?? {}),
+	});
+}

package/src/health.test.js

@@ -0,0 +1,388 @@
+import assert from "node:assert";
+import { afterEach, beforeEach, test } from "node:test";
+
+import {
+	checkQueues,
+	checkStorage,
+	isFailing,
+	runHealthChecks,
+} from "./health.js";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * A probe that records how many probes overlap it.
+ *
+ * `counter` is shared across every probe in one test — a per-probe counter could
+ * never observe more than one in flight, which would make the concurrency
+ * assertion vacuously pass.
+ */
+function counter() {
+	return { inFlight: 0, peak: 0 };
+}
+
+/** A probe that settles after `latencyMs`, sharing a single in-flight counter. */
+function tracked(c, status, latencyMs = 0) {
+	return async () => {
+		c.inFlight++;
+		c.peak = Math.max(c.peak, c.inFlight);
+		await new Promise((resolve) => setTimeout(resolve, latencyMs));
+		c.inFlight--;
+		return { status };
+	};
+}
+
+let originalNodeEnv;
+let originalDir;
+
+beforeEach(() => {
+	originalNodeEnv = process.env.NODE_ENV;
+	originalDir = process.env.STORAGE_LOCAL_DIR;
+});
+
+afterEach(() => {
+	if (originalNodeEnv === undefined) delete process.env.NODE_ENV;
+	else process.env.NODE_ENV = originalNodeEnv;
+
+	if (originalDir === undefined) delete process.env.STORAGE_LOCAL_DIR;
+	else process.env.STORAGE_LOCAL_DIR = originalDir;
+});
+
+// ── runHealthChecks ──────────────────────────────────────────────────────────
+
+test("runHealthChecks returns ok when every probe passes", async () => {
+	const report = await runHealthChecks({
+		probes: {
+			database: async () => ({ status: "ok", latencyMs: 1 }),
+			redis: async () => ({ status: "ok", latencyMs: 2 }),
+		},
+	});
+
+	assert.strictEqual(report.status, "ok");
+	assert.strictEqual(report.checks.database.status, "ok");
+	assert.strictEqual(report.checks.redis.status, "ok");
+	assert.ok(typeof report.timestamp === "string");
+	assert.ok(Number.isFinite(report.durationMs));
+});
+
+test("runHealthChecks probes concurrently, not one after another", async () => {
+	// The defect this exists to prevent. Sequentially, three probes at 80ms would
+	// never put more than one in flight, and their 240ms total is a real fraction
+	// of the budget.
+	const shared = counter();
+	const startedAt = Date.now();
+
+	await runHealthChecks({
+		probes: {
+			a: tracked(shared, "ok", 80),
+			b: tracked(shared, "ok", 80),
+			c: tracked(shared, "ok", 80),
+		},
+	});
+	const elapsed = Date.now() - startedAt;
+
+	assert.strictEqual(
+		shared.peak,
+		3,
+		"probes did not overlap — they are running sequentially",
+	);
+	// Overlap and duration together: 3x80ms serialised would also show peak 1, so
+	// the wall-clock bound is the independent check that the aggregate is the max
+	// of the probes rather than their sum.
+	assert.ok(
+		elapsed < 200,
+		`probes appear serialised (${elapsed}ms for 3x80ms)`,
+	);
+});
+
+test("runHealthChecks aggregates inside the overall deadline when probes hang", async () => {
+	// Never settles. Without a per-probe deadline the aggregate would hang until
+	// the caller gave up.
+	const startedAt = Date.now();
+	const report = await runHealthChecks({
+		timeout: 120,
+		probeTimeout: 120,
+		probes: {
+			database: () => new Promise(() => {}),
+			redis: async () => ({ status: "ok" }),
+		},
+	});
+	const elapsed = Date.now() - startedAt;
+
+	assert.strictEqual(report.status, "degraded");
+	assert.strictEqual(report.checks.database.status, "error");
+	assert.match(report.checks.database.message, /timed out/);
+	assert.ok(elapsed < 600, `aggregate outlived its budget (${elapsed}ms)`);
+});
+
+test("runHealthChecks clamps the probe deadline to the overall budget", async () => {
+	// A probeTimeout above the overall budget must not let a probe outlive the
+	// request: the clamp is what makes "the aggregate always completes inside
+	// the budget" true regardless of how the caller configured it.
+	const startedAt = Date.now();
+	await runHealthChecks({
+		timeout: 100,
+		probeTimeout: 60_000,
+		probes: { database: () => new Promise(() => {}) },
+	});
+	const elapsed = Date.now() - startedAt;
+
+	assert.ok(elapsed < 600, `probe outlived the overall budget (${elapsed}ms)`);
+});
+
+test("runHealthChecks does not reject when a probe throws", async () => {
+	const report = await runHealthChecks({
+		probes: {
+			database: async () => {
+				throw new Error("connect ECONNREFUSED 10.0.0.5:5432");
+			},
+			redis: async () => ({ status: "ok" }),
+		},
+	});
+
+	assert.strictEqual(report.status, "degraded");
+	assert.strictEqual(report.checks.database.status, "error");
+	assert.strictEqual(report.checks.redis.status, "ok");
+});
+
+test("runHealthChecks omits a key when a probe opts out", async () => {
+	// A probe returning null is absent, not passing. Reporting a false pass for a
+	// queue that was never registered would be worse than silence.
+	const report = await runHealthChecks({
+		probes: {
+			database: async () => ({ status: "ok" }),
+			queues: async () => null,
+		},
+	});
+
+	assert.ok(!("queues" in report.checks));
+	assert.strictEqual(report.status, "ok");
+});
+
+// ── Credential redaction ────────────────────────────────────────────────────
+
+test("runHealthChecks redacts credentials from a probe that REJECTS", async () => {
+	process.env.NODE_ENV = "development";
+
+	const report = await runHealthChecks({
+		probes: {
+			redis: async () => {
+				throw new Error(
+					"connect ECONNREFUSED redis://default:hunter2@cache.internal:6379",
+				);
+			},
+		},
+	});
+
+	assert.ok(
+		!JSON.stringify(report).includes("hunter2"),
+		`report leaked a credential: ${JSON.stringify(report)}`,
+	);
+});
+
+test("runHealthChecks redacts credentials from a probe that RESOLVES with an error", async () => {
+	// The shape that bit us before: `pingRedis` reported failure by resolving
+	// with { status: "error", message }, not by rejecting. A normaliser that
+	// handled only rejections would pass this straight through.
+	process.env.NODE_ENV = "development";
+
+	const report = await runHealthChecks({
+		probes: {
+			redis: async () => ({
+				status: "error",
+				message: "unreachable at redis://default:hunter2@cache.internal:6379",
+			}),
+		},
+	});
+
+	assert.ok(
+		!JSON.stringify(report).includes("hunter2"),
+		`report leaked a credential: ${JSON.stringify(report)}`,
+	);
+});
+
+test("runHealthChecks returns a generic message in production", async () => {
+	process.env.NODE_ENV = "production";
+
+	const report = await runHealthChecks({
+		probes: {
+			database: async () => {
+				throw new Error("password authentication failed for user admin");
+			},
+		},
+	});
+
+	assert.strictEqual(report.checks.database.message, "Database unavailable");
+});
+
+test("runHealthChecks keeps the real message outside production", async () => {
+	process.env.NODE_ENV = "development";
+
+	const report = await runHealthChecks({
+		probes: {
+			redis: async () => {
+				throw new Error("Redis unreachable at cache.internal:6379");
+			},
+		},
+	});
+
+	assert.strictEqual(
+		report.checks.redis.message,
+		"Redis unreachable at cache.internal:6379",
+	);
+});
+
+// ── isFailing ───────────────────────────────────────────────────────────────
+
+test("isFailing reads a flat probe result", () => {
+	assert.strictEqual(isFailing({ status: "ok" }), false);
+	assert.strictEqual(isFailing({ status: "error" }), true);
+});
+
+test("isFailing reads the nested queue map", () => {
+	// The verdict lives on each queue, not on the map itself.
+	assert.strictEqual(
+		isFailing({ emails: { status: "ok" }, reports: { status: "ok" } }),
+		false,
+	);
+	assert.strictEqual(
+		isFailing({ emails: { status: "ok" }, reports: { status: "error" } }),
+		true,
+	);
+});
+
+test("isFailing treats a missing check as not failing", () => {
+	assert.strictEqual(isFailing(null), false);
+	assert.strictEqual(isFailing(undefined), false);
+});
+
+// ── checkStorage ────────────────────────────────────────────────────────────
+
+test("checkStorage writes and removes a sentinel object", async () => {
+	const { mkdtemp, rm, readdir } = await import("node:fs/promises");
+	const { tmpdir } = await import("node:os");
+	const { join } = await import("node:path");
+
+	const dir = await mkdtemp(join(tmpdir(), "health-storage-"));
+	const previousProvider = process.env.STORAGE_PROVIDER;
+	process.env.STORAGE_LOCAL_DIR = dir;
+	process.env.STORAGE_PROVIDER = "local";
+
+	try {
+		const result = await checkStorage();
+
+		assert.strictEqual(result.status, "ok");
+		assert.strictEqual(result.provider, "local");
+		// The sentinel must not be left behind, or every probe leaks a file.
+		assert.deepStrictEqual(await readdir(dir), []);
+	} finally {
+		if (previousProvider === undefined) delete process.env.STORAGE_PROVIDER;
+		else process.env.STORAGE_PROVIDER = previousProvider;
+		await rm(dir, { recursive: true, force: true });
+	}
+});
+
+test("checkStorage fails when the directory is not writable", async () => {
+	// The defect the brief flags: a `stat`-based check passes here, because the
+	// directory exists. It is the only failure this probe exists to catch, so the
+	// sentinel round-trip is what distinguishes the two.
+	if (process.getuid?.() === 0) return; // root ignores the mode bits
+
+	const { mkdtemp, chmod, rm } = await import("node:fs/promises");
+	const { tmpdir } = await import("node:os");
+	const { join } = await import("node:path");
+
+	const dir = await mkdtemp(join(tmpdir(), "health-readonly-"));
+	const previousProvider = process.env.STORAGE_PROVIDER;
+	process.env.STORAGE_LOCAL_DIR = dir;
+	process.env.STORAGE_PROVIDER = "local";
+
+	try {
+		await chmod(dir, 0o500); // read + execute, no write
+		await assert.rejects(() => checkStorage());
+	} finally {
+		await chmod(dir, 0o700).catch(() => {});
+		if (previousProvider === undefined) delete process.env.STORAGE_PROVIDER;
+		else process.env.STORAGE_PROVIDER = previousProvider;
+		await rm(dir, { recursive: true, force: true });
+	}
+});
+
+// ── checkQueues ─────────────────────────────────────────────────────────────
+
+function fakeQueue({
+	waiting = 0,
+	active = 0,
+	failed = 0,
+	throwOn = null,
+} = {}) {
+	const count = (kind) => {
+		if (throwOn === kind) throw new Error(`queue gone (${kind})`);
+		return { waiting, active, failed }[kind];
+	};
+	return {
+		getWaitingCount: async () => count("waiting"),
+		getActiveCount: async () => count("active"),
+		getFailedCount: async () => count("failed"),
+	};
+}
+
+test("checkQueues reports depths for registered queues", async () => {
+	const result = await checkQueues(
+		() => new Map([["emails", fakeQueue({ waiting: 3, active: 1 })]]),
+	);
+
+	assert.deepStrictEqual(result.emails, {
+		status: "ok",
+		waiting: 3,
+		active: 1,
+		failed: 0,
+	});
+});
+
+test("checkQueues returns null when no queues are registered", async () => {
+	// The web app registers none, so this must be absent from the report rather
+	// than reported as a passing check.
+	assert.strictEqual(await checkQueues(() => new Map()), null);
+});
+
+test("checkQueues marks a failing queue without failing its siblings", async () => {
+	const result = await checkQueues(
+		() =>
+			new Map([
+				["emails", fakeQueue({ waiting: 1 })],
+				["reports", fakeQueue({ throwOn: "waiting" })],
+			]),
+	);
+
+	assert.strictEqual(result.emails.status, "ok");
+	assert.strictEqual(result.reports.status, "error");
+	assert.match(result.reports.message, /queue gone/);
+});
+
+test("checkQueues redacts a credential from a queue failure", async () => {
+	process.env.NODE_ENV = "development";
+
+	const result = await checkQueues(
+		() =>
+			new Map([
+				[
+					"emails",
+					{
+						getWaitingCount: async () => {
+							throw new Error(
+								"NOAUTH redis://default:hunter2@cache.internal:6379",
+							);
+						},
+						getActiveCount: async () => 0,
+						getFailedCount: async () => 0,
+					},
+				],
+			]),
+	);
+
+	assert.ok(
+		!JSON.stringify(result).includes("hunter2"),
+		`queue failure leaked a credential: ${JSON.stringify(result)}`,
+	);
+});

package/src/index.js

@@ -25,6 +25,8 @@ export * from "./error-reporter.js";
 export * from "./errors.js";
 // File validation exports
 export * from "./file-validation.js";
+// Health check exports
+export * from "./health.js";
 // Logger exports
 export * from "./logger.js";
 // Mail exports

package/src/storage.js

@@ -187,11 +187,16 @@ export function generateStorageKey(originalFilename, options = {}) {
  *
  * Checks `ASSET_CDN_URL` first - if set, prepends it to the key.
  * This is provider-agnostic: works with any CDN (CloudFront, Cloudflare,
- * Bunny, Fastly, etc.) as long as the CDN is pointed at the same bucket.
+ * Bunny, Fastly, etc.) provided the CDN is rooted at the bucket, so that a
+ * request for `<cdn>/<key>` maps to the object stored at `<key>`. That is the
+ * standard arrangement for a CDN in front of a bucket and needs no rewrite
+ * rules. If your CDN is not bucket-rooted, set `S3_PUBLIC_URL` instead and use
+ * the S3 adapter's `getPublicUrl()`.
  *
  * Falls back to the local API route (`/api/files/<key>`) when no CDN is
  * configured - covers local development and any environment where
- * `STORAGE_PROVIDER=local` is used.
+ * `STORAGE_PROVIDER=local` is used. The scaffolded `/api/files/[id]` route
+ * accepts a storage key as well as a database id, so this resolves.
  *
  * @param {string} key - Storage key (e.g. "uploads/2026/02/abc-photo.jpg")
  * @returns {string} Full CDN URL or local API route

package/src/storage.test.js

@@ -351,6 +351,55 @@ test("getAssetUrl - percent-encodes key in fallback URL", () => {
 	assert.strictEqual(url, "/api/files/uploads%2Ffile%20with%20spaces.jpg");
 });
 
+// ─── getAssetUrl / route contract ────────────────────────────────────────────
+//
+// The scaffolded GET /api/files/[id] route used to look up by database id only,
+// so every URL this function produced resolved to a 404. It now also resolves a
+// storage key. These tests pin the two halves of that contract from each side:
+// the shape produced here, and the lookup performed by the route (in
+// apps/web/src/app/api/files/[id]/route.test.js).
+test("getAssetUrl - fallback URL carries the key in a single path segment", () => {
+	delete process.env.ASSET_CDN_URL;
+	const url = getAssetUrl("uploads/2026/02/abc-photo.jpg");
+
+	// A key with slashes must stay inside ONE path segment, or the request never
+	// reaches the [id] route at all — it 404s as an unrouted path. `URL` keeps the
+	// percent-encoding in `pathname`, so it is the encoded slashes that hold the
+	// segment together.
+	const segments = new URL(url, "http://localhost").pathname.split("/");
+	assert.strictEqual(
+		segments.length,
+		4,
+		`key leaked into extra segments: ${url}`,
+	);
+	assert.strictEqual(segments[3], "uploads%2F2026%2F02%2Fabc-photo.jpg");
+	// And it must decode back to exactly the key, which is what the route looks up.
+	assert.strictEqual(
+		decodeURIComponent(segments[3]),
+		"uploads/2026/02/abc-photo.jpg",
+	);
+});
+
+test("getAssetUrl - CDN URL leaves the key path unencoded", () => {
+	// The CDN branch is a real URL space, not a path segment: encoding the slashes
+	// would ask the CDN for a single object literally named "uploads/2026/02/...".
+	// A bucket-rooted CDN maps the path straight onto the key.
+	process.env.ASSET_CDN_URL = "https://assets.example.com";
+	try {
+		const url = getAssetUrl("uploads/2026/02/abc-photo.jpg");
+		assert.strictEqual(
+			url,
+			"https://assets.example.com/uploads/2026/02/abc-photo.jpg",
+		);
+		assert.ok(
+			!url.includes("%2F"),
+			"CDN URL must not percent-encode the key path",
+		);
+	} finally {
+		delete process.env.ASSET_CDN_URL;
+	}
+});
+
 // ---------------------------------------------------------------------------
 // getSignedUploadUrl
 // ---------------------------------------------------------------------------

package/src/utils.js

@@ -232,29 +232,53 @@ const REDACTED_CREDENTIAL = "REDACTED";
  * of those is a credential disclosure, so nothing that embeds a URL in a
  * message should skip this.
  *
- * Parseable URLs are rewritten field by field. Anything else is run through a
- * regex that strips the userinfo segment of a URL-shaped string. A string that
- * matches neither has no recognisable credential segment and is returned
- * unchanged.
+ * Handles both shapes a connection string arrives in:
+ *
+ * - A bare, parseable URL — rewritten field by field.
+ * - A URL *embedded in a larger message*, which is what drivers actually
+ *   produce: `connect ECONNREFUSED redis://default:hunter2@cache:6379`. Every
+ *   URL-shaped substring is scanned and its userinfo segment replaced.
+ *
+ * Deciding between the two is not "did it parse" — `new URL()` accepts any
+ * string with a `<scheme>:` prefix, so a message like
+ * `Error: getaddrinfo ENOTFOUND postgres://u:p@db:5432/x` parses as a URL with
+ * protocol `error:` and *no* credentials of its own. Field-by-field rewriting
+ * then finds nothing to strip and returns the whole message untouched, with
+ * the embedded password intact. The field-by-field path is therefore gated on
+ * the string actually being a bare URL; everything else goes to the substring
+ * scan, which handles both embedded cases identically.
+ *
+ * A string with no recognisable credential segment is returned unchanged.
  *
  * @param {string} url
- * @returns {string} The URL with any username/password replaced
+ * @returns {string} The value with any username/password replaced
  */
 export const redactUrl = (url) => {
 	if (typeof url !== "string" || url.length === 0) return url;
 
-	try {
-		const parsed = new URL(url);
+	// A bare URL is exactly `scheme://...` with no leading text and no
+	// surrounding whitespace. Anything else is treated as a message.
+	const isBareUrl = url === url.trim() && /^[a-z][a-z0-9+.-]*:\/\//i.test(url);
+
+	if (isBareUrl) {
+		try {
+			const parsed = new URL(url);
 
-		if (!parsed.username && !parsed.password) return url;
+			if (!parsed.username && !parsed.password) return url;
 
-		parsed.username = parsed.username ? REDACTED_CREDENTIAL : "";
-		parsed.password = parsed.password ? REDACTED_CREDENTIAL : "";
-		return parsed.toString();
-	} catch {
-		return url.replace(
-			/^([a-z][a-z0-9+.-]*:\/\/)[^/?#@]*@/i,
-			`$1${REDACTED_CREDENTIAL}@`,
-		);
+			parsed.username = parsed.username ? REDACTED_CREDENTIAL : "";
+			parsed.password = parsed.password ? REDACTED_CREDENTIAL : "";
+			return parsed.toString();
+		} catch {
+			// Malformed enough that the serializer rejected it. Fall through to
+			// the substring scan, which still finds the credential segment.
+		}
 	}
+
+	// Redact every URL-shaped substring, wherever it sits: the scheme, then the
+	// userinfo segment, terminated by `@`.
+	return url.replace(
+		/([a-z][a-z0-9+.-]*:\/\/)[^/?#@\s]*@/gi,
+		`$1${REDACTED_CREDENTIAL}@`,
+	);
 };

package/src/utils.test.js

@@ -226,12 +226,71 @@ test("redactUrl", async (t) => {
 		assert(!result.includes("hunter2"), `password leaked: ${result}`);
 	});
 
+	await t.test("strips credentials from a URL embedded mid-message", () => {
+		// The shape drivers actually produce. The old regex was anchored to the
+		// start of the string, so a credential appearing after any prefix survived
+		// intact — which is exactly the form a failed connection reports.
+		const result = redactUrl(
+			"connect ECONNREFUSED redis://default:hunter2@cache.internal:6379",
+		);
+
+		assert(!result.includes("hunter2"), `password leaked: ${result}`);
+		assert(!result.includes("default"), `username leaked: ${result}`);
+		// The diagnostic value of the message survives.
+		assert(result.includes("connect ECONNREFUSED"));
+		assert(result.includes("cache.internal"));
+	});
+
+	await t.test("strips every embedded URL in a multi-URL message", () => {
+		const result = redactUrl(
+			"failed on redis://u1:p1@a:6379 and postgres://u2:p2@b:5432/db",
+		);
+
+		assert(!result.includes("p1"), `first password leaked: ${result}`);
+		assert(!result.includes("p2"), `second password leaked: ${result}`);
+		assert(result.includes("a:6379"));
+		assert(result.includes("b:5432"));
+	});
+
+	await t.test(
+		"strips credentials when the message itself parses as a URL",
+		() => {
+			// `new URL()` accepts any string with a `<scheme>:` prefix, so both of
+			// these "parse" — as protocol `error:` / `connect:`, with no credentials
+			// of their own. Rewriting field-by-field therefore found nothing to strip
+			// and returned the message whole, embedded password intact. This is the
+			// shape a driver error takes once something has prefixed it with a
+			// label, and it reached the unauthenticated /api/health body.
+			for (const message of [
+				"Error: getaddrinfo ENOTFOUND postgres://u:p@db.example.com:5432/x",
+				"connect: ECONNREFUSED redis://default:hunter2@cache.internal:6379",
+			]) {
+				const result = redactUrl(message);
+
+				assert(!result.includes(":p@"), `password leaked: ${result}`);
+				assert(!result.includes("hunter2"), `password leaked: ${result}`);
+				// The diagnostic value survives redaction.
+				assert(result.includes("ENOTFOUND") || result.includes("ECONNREFUSED"));
+				assert(
+					result.includes("db.example.com") ||
+						result.includes("cache.internal"),
+				);
+			}
+		},
+	);
+
 	await t.test("leaves a credential-free URL untouched", () => {
 		const url = "redis://cache.internal:6379";
 
 		assert(redactUrl(url) === url);
 	});
 
+	await t.test("leaves an embedded credential-free URL untouched", () => {
+		const message = "connected to redis://cache.internal:6379 in 3ms";
+
+		assert(redactUrl(message) === message);
+	});
+
 	await t.test("passes through non-URL and empty values", () => {
 		assert(redactUrl("not-a-url") === "not-a-url");
 		assert(redactUrl("") === "");