fix(docker): use lightweight /healthz for container lifecycle healthcheck instead of the heavy monitoring route (#10311) (#10504)

Co-authored-by: adevwithpurpose <adevwithpurpose@users.noreply.github.com>

changelog.d/fixes/10311-healthcheck-lifecycle-default.md

@@ -0,0 +1 @@
+- **fix(ops):** Docker HEALTHCHECK defaults to the lightweight `/healthz` lifecycle probe instead of the heavy `/api/monitoring/health` path, with an `OMNIROUTE_HEALTHCHECK_PATH` opt-in override ([#10311](https://github.com/diegosouzapw/OmniRoute/pull/10311))

docs/guides/DOCKER_GUIDE.md

@@ -329,10 +329,13 @@ prefix). Traefik should route `PathPrefix(`/omniroute`)` to the container withou
 `StripPrefix`, so Next.js receives `/omniroute/...` and serves assets from
 `/omniroute/_next/...`.
 
-The Docker healthcheck probes `/api/monitoring/health` prefixed with the active
-`OMNIROUTE_BASE_PATH`. That path is a **deep** check (DB + monitoring summary). It is
-appropriate for Docker’s infrequent `HEALTHCHECK`, but **not** for Kubernetes
-`livenessProbe` intervals.
+The Docker healthcheck probes the lightweight `/healthz` lifecycle endpoint prefixed
+with the active `OMNIROUTE_BASE_PATH`. `/api/monitoring/health` remains available for
+human/dashboard diagnostics; to point the container HEALTHCHECK back at it (for example
+for deep health enforcement), set `OMNIROUTE_HEALTHCHECK_PATH=/api/monitoring/health`.
+That path is a **deep** check (DB + monitoring summary) — appropriate for Docker's
+infrequent `HEALTHCHECK` if you opt back in, but **not** for Kubernetes `livenessProbe`
+intervals.
 
 For orchestrators (Kubernetes, Nomad, etc.):
 

docs/i18n/pl/docs/guides/DOCKER_GUIDE.md

@@ -224,8 +224,10 @@ prefiksu). Traefik powinien routować `PathPrefix(`/omniroute`)` do kontenera be
 `StripPrefix`, żeby Next.js otrzymywał `/omniroute/...` i serwował assety z
 `/omniroute/_next/...`.
 
-Healthcheck Dockera sonduje `/api/monitoring/health` z prefiksem aktywnego
-`OMNIROUTE_BASE_PATH`.
+Healthcheck Dockera sonduje lekki endpoint cyklu życia `/healthz` z prefiksem aktywnego
+`OMNIROUTE_BASE_PATH`. `/api/monitoring/health` pozostaje dostępny do diagnostyki
+człowieka/pulpit; aby ustawić HEALTHCHECK kontenera z powrotem na niego (np. dla
+głębokiej kontroli stanu), ustaw `OMNIROUTE_HEALTHCHECK_PATH=/api/monitoring/health`.
 
 ## Docker Compose z Caddy (HTTPS Auto-TLS)
 

scripts/dev/healthcheck.mjs

@@ -8,6 +8,15 @@
  * event loop is busy (#10052) and can restart the only replica mid-session.
  * Used by Dockerfile and docker-compose files.
  *
+ * #10311 — the container HEALTHCHECK previously probed the heavy
+ * /api/monitoring/health path (synchronous SQLite reads + deep monitoring
+ * aggregation) on the same single-process event loop as catalog rebuild /
+ * long-context compression. Under load that probe could stall past the 5s
+ * timeout and flip the container `unhealthy`, restarting it mid-session and
+ * killing active SSE streams. /healthz is a pure in-memory lifecycle check
+ * with no DB access. Operators who want the deep monitoring probe can opt
+ * back in with OMNIROUTE_HEALTHCHECK_PATH.
+ *
  * #3151 — in some Docker network setups the server binds to a container IP and
  * a probe against `127.0.0.1` is not reachable, while `localhost`/`::1` (or vice
  * versa) is. The previous version probed ONLY `127.0.0.1` and swallowed every
@@ -35,10 +44,34 @@ function normalizeBasePath(value) {
   return `/${segments.join("/")}`;
 }
 
-/** Prefixes the health route with the configured Next.js basePath. */
-export function resolveHealthPath(basePathValue) {
+/**
+ * Normalize an explicit health-check path override (OMNIROUTE_HEALTHCHECK_PATH).
+ * Returns "" when absent/invalid so callers fall back to DEFAULT_HEALTH_PATH.
+ * Mirrors normalizeBasePath's safety rules (no query/hash/backslash, no "." /
+ * ".." segments, must start with "/").
+ */
+function normalizeHealthPath(value) {
+  const trimmed = typeof value === "string" ? value.trim() : "";
+  if (!trimmed) return "";
+  if (!trimmed.startsWith("/") || /[?#\\]/.test(trimmed)) return "";
+  const segments = trimmed.split("/").filter(Boolean);
+  if (segments.some((segment) => segment === "." || segment === "..")) return "";
+  return `/${segments.join("/")}`;
+}
+
+/**
+ * Resolve the health route to probe. By default the lightweight /healthz
+ * lifecycle endpoint (pure in-memory, no DB reads). An explicit
+ * OMNIROUTE_HEALTHCHECK_PATH override opts back into the deep monitoring
+ * probe. The configured Next.js basePath is always prefixed.
+ *
+ * @param {string} [basePathValue] value of OMNIROUTE_BASE_PATH
+ * @param {string} [healthPathValue] value of OMNIROUTE_HEALTHCHECK_PATH
+ */
+export function resolveHealthPath(basePathValue, healthPathValue) {
   const basePath = normalizeBasePath(basePathValue);
-  return basePath ? `${basePath}${DEFAULT_HEALTH_PATH}` : DEFAULT_HEALTH_PATH;
+  const healthPath = normalizeHealthPath(healthPathValue) || DEFAULT_HEALTH_PATH;
+  return basePath ? `${basePath}${healthPath}` : healthPath;
 }
 
 /**
@@ -118,7 +151,10 @@ async function main() {
   }
 
   try {
-    const healthPath = resolveHealthPath(process.env.OMNIROUTE_BASE_PATH);
+    const healthPath = resolveHealthPath(
+      process.env.OMNIROUTE_BASE_PATH,
+      process.env.OMNIROUTE_HEALTHCHECK_PATH
+    );
     await probeHealth({ port, hosts, healthPath });
     process.exit(0);
   } catch (err) {

tests/unit/docker-healthcheck-base-path.test.ts

@@ -2,7 +2,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { resolveHealthPath } from "../../scripts/dev/healthcheck.mjs";
 
-test("resolveHealthPath keeps the default route at the domain root", () => {
+test("resolveHealthPath keeps the default lightweight /healthz route at the domain root (#10311)", () => {
   assert.equal(resolveHealthPath(""), "/healthz");
   assert.equal(resolveHealthPath(undefined), "/healthz");
 });
@@ -11,3 +11,17 @@ test("resolveHealthPath prefixes the health route with OMNIROUTE_BASE_PATH", ()
   assert.equal(resolveHealthPath("/omniroute/"), "/omniroute/healthz");
   assert.equal(resolveHealthPath("/omniroute"), "/omniroute/healthz");
 });
+
+test("resolveHealthPath honors an explicit OMNIROUTE_HEALTHCHECK_PATH override", () => {
+  assert.equal(resolveHealthPath(undefined, "/api/monitoring/health"), "/api/monitoring/health");
+  assert.equal(
+    resolveHealthPath("/omniroute", "/api/monitoring/health"),
+    "/omniroute/api/monitoring/health"
+  );
+});
+
+test("resolveHealthPath ignores an invalid/empty OMNIROUTE_HEALTHCHECK_PATH and falls back to /healthz", () => {
+  assert.equal(resolveHealthPath("", "  "), "/healthz");
+  assert.equal(resolveHealthPath("", "/../etc/passwd"), "/healthz");
+  assert.equal(resolveHealthPath("", "/health?utm=1"), "/healthz");
+});

tests/unit/probe-10311-healthcheck-lifecycle-default.test.ts

@@ -0,0 +1,12 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { resolveHealthPath } from "../../scripts/dev/healthcheck.mjs";
+
+// Issue #10311: the official Docker image's HEALTHCHECK (scripts/dev/healthcheck.mjs)
+// must default to the lightweight lifecycle probe (/healthz) rather than the heavy
+// /api/monitoring/health path (SQLite reads + deep monitoring aggregation on the same
+// event loop as catalog rebuild / compression). This test asserts the expected fix.
+test("resolveHealthPath defaults to the lightweight /healthz lifecycle probe, not the heavy monitoring path", () => {
+  assert.equal(resolveHealthPath(""), "/healthz");
+  assert.equal(resolveHealthPath(undefined), "/healthz");
+});