@usequark/quark-create-app 1.24.3 → 1.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-create-app",
-  "version": "1.24.3",
+  "version": "1.25.0",
   "description": "CLI to scaffold new Quark projects with Next.js, Prisma, BullMQ, and Railway deployment",
   "keywords": [
     "quark",

package/src/index.js

@@ -214,8 +214,23 @@ async function initializeGit(projectDir) {
 	}
 
 	try {
-		// Initialize git repo
-		await execa("git", ["init"], { cwd: projectDir });
+		// Initialize git repo.
+		//
+		// `-b main` pins the branch name rather than inheriting whatever the
+		// machine has in `init.defaultBranch`. Without it the scaffold is not
+		// reproducible: `git init` falls back to `master` wherever that setting
+		// is unset (the common case, and GitHub's own default until the hint
+		// is followed), so the same CLI produced `master` on one machine and
+		// `main` on another. `main` is the name GitHub defaults a new repository
+		// to, so it is also what the README's push instructions assume.
+		//
+		// `-b` needs git 2.28 (2020). If it is unavailable the bare `init` still
+		// produces a working repository, just with git's own default branch.
+		try {
+			await execa("git", ["init", "-b", "main"], { cwd: projectDir });
+		} catch {
+			await execa("git", ["init"], { cwd: projectDir });
+		}
 
 		// Add all files
 		await execa("git", ["add", "."], { cwd: projectDir });

package/templates/base-project/apps/web/src/app/api/health/route.js

@@ -1,7 +1,15 @@
 /**
  * Health Check Endpoint
- * Verifies the application and its dependencies are functioning correctly.
- * Times out after 5 seconds to prevent hanging.
+ *
+ * Reports the status of the application and its dependencies. Every dependency
+ * is probed concurrently, each under its own deadline, and the route always
+ * answers `200` — the verdict lives in the body's `status` field.
+ *
+ * Why always 200: this endpoint is the platform healthcheck. A non-200 here
+ * makes the orchestrator restart the container, which drops every warm
+ * connection and produces a fresh connection storm on the dependency that was
+ * already struggling. That turns a transient blip into a restart loop.
+ * Callers that need a hard verdict should read `status`, not the status code.
  */
 
 import {
@@ -15,146 +23,241 @@ import { NextResponse } from "next/server";
 
 const logger = createLogger("health");
 
-/** Overall timeout for the health check (ms). */
+/** Ceiling for the whole check (ms). */
 const HEALTH_CHECK_TIMEOUT = 5000;
 
+/** Ceiling for one dependency probe (ms). Clamped to the overall budget, so a
+ * single probe can never outlive the request. */
+const PROBE_TIMEOUT = 3000;
+
+/** Message returned in place of a real error when NODE_ENV is production. */
+const GENERIC_MESSAGES = {
+	database: "Database unavailable",
+	redis: "Redis unavailable",
+	storage: "Storage unavailable",
+	queue: "Queue unavailable",
+};
+
 export async function GET() {
 	try {
-		const result = await new Promise((resolve, reject) => {
-			const timer = setTimeout(
-				() => reject(new Error("Health check timed out")),
-				HEALTH_CHECK_TIMEOUT,
-			);
-			runHealthChecks().then(
-				(val) => {
-					clearTimeout(timer);
-					resolve(val);
-				},
-				(err) => {
-					clearTimeout(timer);
-					reject(err);
-				},
-			);
-		});
+		const result = await runHealthChecks();
 
+		// Always 200 — see the module comment. An orchestrator restarting this
+		// service is what turns a dependency blip into an outage.
 		return NextResponse.json(result, {
-			status: result.status === "error" ? 503 : 200,
+			status: 200,
+			headers: { "Cache-Control": "no-store" },
 		});
 	} catch (error) {
+		// Unreachable in practice: every probe below is individually settled and
+		// deadline-bounded, so runHealthChecks cannot reject. Kept so a future
+		// edit that reintroduces a throw still returns a parseable body.
 		logger.error("Health check failed", {
 			error: error.message,
 			stack: error.stack,
 		});
+
 		return NextResponse.json(
 			{
 				status: "error",
 				timestamp: new Date().toISOString(),
 				message: "Service health check failed",
 			},
-			{ status: 500 },
+			{ status: 200, headers: { "Cache-Control": "no-store" } },
 		);
 	}
 }
 
 /**
- * Runs all individual health checks and aggregates the results.
- * @returns {Promise<{ status: string, timestamp: string, checks: Record<string, object> }>}
+ * Runs every dependency probe concurrently and aggregates the results.
+ *
+ * Concurrency matters as much as the deadlines: run sequentially, a 3s database
+ * timeout plus a 3s Redis timeout exhausts the 5s budget before storage is even
+ * attempted, and the whole request falls through to the give-up path.
+ *
+ * @returns {Promise<{ status: string, timestamp: string, durationMs: number, checks: Record<string, object> }>}
  */
 async function runHealthChecks() {
-	const health = {
-		status: "ok",
+	const startedAt = performance.now();
+
+	// Every probe is wrapped in settleProbe(), so this Promise.all cannot reject
+	// and cannot outlast the deadline.
+	const [database, redis, storage, queues] = await Promise.all([
+		settleProbe("database", () => pingDatabase()),
+		settleProbe("redis", () => pingRedis()),
+		// `provider` rides along on the error result so a failure still names the
+		// provider that failed — settleProbe owns the message redaction.
+		settleProbe("storage", checkStorage, {
+			provider: process.env.STORAGE_PROVIDER || "local",
+		}),
+		settleProbe("queues", checkQueues),
+	]);
+
+	const checks = { database, redis, storage };
+	if (queues) checks.queues = queues;
+
+	return {
+		// "degraded" means at least one dependency failed. Both this and "ok"
+		// answer 200 — see the module comment.
+		status: Object.values(checks).some(isFailing) ? "degraded" : "ok",
 		timestamp: new Date().toISOString(),
-		checks: {},
+		durationMs: Math.round(performance.now() - startedAt),
+		checks,
 	};
+}
 
-	// Check database connectivity
-	const dbResult = await pingDatabase();
-	if (dbResult.status === "ok") {
-		health.checks.database = { status: "ok", latencyMs: dbResult.latencyMs };
-	} else {
-		health.checks.database = {
-			status: "error",
-			message: dbResult.message,
-		};
-		health.status = "degraded";
+/**
+ * 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}
+ */
+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 (/** @type {any} */ (check).status) === "string") {
+		return /** @type {any} */ (check).status === "error";
 	}
 
-	// Check Redis connectivity (actual PING)
-	const redisResult = await pingRedis();
-	if (redisResult.status === "ok") {
-		health.checks.redis = { status: "ok", latencyMs: redisResult.latencyMs };
-	} else {
-		health.checks.redis = {
+	return Object.values(/** @type {Record<string, any>} */ (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>} probe
+ * @param {object} [context] - Fields to merge into the error result.
+ * @returns {Promise<{ status: string } & Record<string, unknown>>}
+ */
+async function settleProbe(name, probe, context = {}) {
+	// 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(PROBE_TIMEOUT, HEALTH_CHECK_TIMEOUT),
+		);
+	});
+
+	try {
+		return withSafeMessage(name, await Promise.race([probe(), deadline]));
+	} catch (/** @type {any} */ error) {
+		return withSafeMessage(name, {
+			...context,
 			status: "error",
-			message: redisResult.message,
-		};
-		health.status = "degraded";
+			message: error?.message,
+		});
+	} finally {
+		clearTimeout(timer);
 	}
+}
 
-	// Check storage connectivity
-	const storageResult = await checkStorage();
-	health.checks.storage = storageResult;
-	if (storageResult.status === "error") {
-		health.status = "degraded";
-	}
+/**
+ * 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: `pingRedis` returned `{ status: "error" }` carrying the
+ * raw `REDIS_URL`, so a normaliser that only handled rejections would have let
+ * the password straight through.
+ *
+ * @param {string} name - Probe name.
+ * @param {object} [result]
+ * @returns {object}
+ */
+function withSafeMessage(name, result) {
+	if (result?.status !== "error") return result;
 
-	// Check queue depths (only when queues are registered in this process)
-	const registeredQueues = getRegisteredQueues();
-	if (registeredQueues.size > 0) {
-		const entries = [...registeredQueues.entries()];
-		const results = await Promise.allSettled(
-			entries.map(([, queue]) =>
-				Promise.all([
-					queue.getWaitingCount(),
-					queue.getActiveCount(),
-					queue.getFailedCount(),
-				]),
-			),
-		);
+	const { message, ...rest } = result;
+	return { ...rest, status: "error", message: safeMessage(name, message) };
+}
 
-		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 {
-				const message =
-					process.env.NODE_ENV === "production"
-						? "Queue unavailable"
-						: result.reason?.message;
-				queueChecks[name] = { status: "error", message };
-				health.status = "degraded";
-			}
-		}
-		health.checks.queues = queueChecks;
+/**
+ * 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. `pingRedis`/`pingDatabase` redact at the
+ * source regardless; this is the second layer.
+ *
+ * @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";
 	}
 
-	return health;
+	return source?.message ?? source ?? "Unknown error";
 }
 
 /**
  * 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).
- * @returns {Promise<{ status: string, provider: string, message?: string }>}
+ * @returns {Promise<{ status: string, provider: string }>}
  */
 async function checkStorage() {
 	const provider = process.env.STORAGE_PROVIDER || "local";
-	try {
-		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 };
-	} catch (error) {
-		const message =
-			process.env.NODE_ENV === "production"
-				? "Storage unavailable"
-				: error.message;
-		return { status: "error", provider, message };
+	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 — the web app registers none, so this resolves to null and the key is
+ * omitted from the response rather than reported as a false pass.
+ *
+ * @returns {Promise<Record<string, { status: string, waiting?: number, active?: number, failed?: number, message?: string }> | null>}
+ */
+async function checkQueues() {
+	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;
 }

package/templates/base-project/apps/web/src/lib/proxy-auth.js

@@ -7,6 +7,17 @@ const STRICT_AUTH_RATE_LIMIT_ROUTES = new Set([
 	"/api/auth/signin/credentials",
 ]);
 
+/**
+ * Routes that are never rate limited.
+ *
+ * `/api/health` is the platform healthcheck. It sits behind the same 100-req
+ * `api` bucket as everything else, so a probe that lands in an already-full
+ * bucket gets a 429 — the orchestrator reads that as unhealthy and restarts the
+ * container, which fills the bucket again on startup. Limiting the probe is how
+ * a healthy service gets killed.
+ */
+const RATE_LIMIT_EXEMPT_ROUTES = new Set(["/api/health"]);
+
 function getForwardedProtocol(request) {
 	const forwardedProto = request.headers.get("x-forwarded-proto");
 	if (!forwardedProto) return null;
@@ -78,3 +89,12 @@ export function getRateLimitBucket(pathname, method = "GET") {
 		? "auth"
 		: "api";
 }
+
+/**
+ * Whether a route bypasses rate limiting entirely.
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+export function isRateLimitExempt(pathname) {
+	return RATE_LIMIT_EXEMPT_ROUTES.has(pathname);
+}

package/templates/base-project/apps/web/src/proxy.js

@@ -5,14 +5,15 @@
  * Guards (in order):
  *   1. Metrics guard        - optionally protects /api/metrics with a bearer
  *                             token. Set METRICS_TOKEN in env to enable.
- *   2. Rate limiting, CORS, security headers for all API routes.
+ *   2. Rate limiting, CORS, security headers for all API routes, except the
+ *      rate-limit-exempt healthcheck (see lib/proxy-auth.js).
  */
 
 import { getAllowedOrigins } from "@usequark/quark-config/app-url";
 import { NextResponse } from "next/server";
 
 import { buildContentSecurityPolicy } from "./lib/analytics/umami-csp.js";
-import { getRateLimitBucket } from "./lib/proxy-auth";
+import { getRateLimitBucket, isRateLimitExempt } from "./lib/proxy-auth";
 
 // ─── 1. Metrics guard ────────────────────────────────────────────────────────
 
@@ -218,8 +219,9 @@ export async function proxy(request) {
 		}
 	}
 
-	// Apply rate limiting to API routes only
-	if (pathname.startsWith("/api/")) {
+	// Apply rate limiting to API routes only. Exempt routes (the healthcheck)
+	// skip the bucket entirely — no counter, no headers.
+	if (pathname.startsWith("/api/") && !isRateLimitExempt(pathname)) {
 		const ip = getClientIp(request);
 		const rateLimitBucket = getRateLimitBucket(pathname, request.method);
 		const maxRequests = RATE_LIMIT_CONFIG.maxRequests[rateLimitBucket];

package/templates/worker/src/index.js

@@ -9,7 +9,7 @@ import {
 	createLogger,
 	createQueue,
 	createWorker,
-	getRedisUrl,
+	getRedisEndpoint,
 	updateQueueDepths,
 } from "@usequark/quark-core";
 import { AppError } from "@usequark/quark-core/errors";
@@ -170,7 +170,7 @@ export async function waitForRedis(
 
 	// All retries exhausted
 	throw new AppError(
-		`Redis unavailable at ${getRedisUrl()} after ${maxRetries} attempts. Start Redis or check REDIS_URL/REDIS_HOST/REDIS_PORT.`,
+		`Redis unavailable at ${getRedisEndpoint()} after ${maxRetries} attempts. Start Redis or check REDIS_URL/REDIS_HOST/REDIS_PORT.`,
 		503,
 		"REDIS_UNAVAILABLE",
 	);
@@ -397,7 +397,7 @@ async function startWorker() {
 			isDevMode ? { maxRetries: 3, intervalMs: 500 } : {},
 		);
 
-		logger.info("Redis connected", { address: getRedisUrl() });
+		logger.info("Redis connected", { address: getRedisEndpoint() });
 
 		// Wait for database schema to be ready (migrations may still be running)
 		logger.info("Checking database schema readiness...");