feat(miner): add AMS hosted-container health HTTP endpoint (#7177) (#7185)

Author: xfodev

packages/loopover-miner/lib/ams-health-server.d.ts

@@ -0,0 +1,19 @@
+import type { Server } from "node:http";
+
+export type ReadinessProbe = { name: string; check: () => Promise<boolean> };
+
+export type Readiness = {
+  ok: boolean;
+  checks: Record<string, boolean>;
+  durationsMs: Record<string, number>;
+};
+
+export function buildHealthBody(): { status: "ok" };
+
+export function readiness(probes?: ReadinessProbe[]): Promise<Readiness>;
+
+export function createAmsHealthHandler(
+  probes?: ReadinessProbe[],
+): (req: { method?: string; url?: string }, res: { writeHead: (status: number, headers: Record<string, string>) => void; end: (body: string) => void }) => Promise<void>;
+
+export function startAmsHealthServer(options?: { port?: number; host?: string; probes?: ReadinessProbe[] }): Promise<Server>;

packages/loopover-miner/lib/ams-health-server.js

@@ -0,0 +1,92 @@
+import { createServer } from "node:http";
+
+// Minimal HTTP health surface for a hosted AMS container (#7177). AMS is otherwise CLI-only (loopover-miner
+// status/doctor) and the operator UI reads its SQLite files directly -- but a hosted control-plane polling
+// container health across a fleet (#4933/#4934) needs each container to answer over HTTP. This deliberately
+// mirrors ORB's src/selfhost/health.ts SHAPE -- `/health` -> `{ status: "ok" }` liveness, `/ready` -> a
+// `{ ok, checks, durationsMs }` readiness built from injectable ReadinessProbes -- so the same aggregator can
+// poll both products identically. It runs ONLY from the hosted-container entry point; the self-host CLI never
+// starts it, so self-host behavior is unchanged. No HTTP framework dependency: node:http is enough for two routes.
+
+/** @typedef {{ name: string, check: () => Promise<boolean> }} ReadinessProbe */
+
+/** Bare liveness body: the process is up and answering, independent of any backend it depends on. */
+export function buildHealthBody() {
+  return { status: "ok" };
+}
+
+/**
+ * Readiness: run every injected probe and report per-probe pass/fail plus how long each took. `ok` is true only
+ * when every probe passed -- a container that can't reach a backend it depends on must stop reporting ready so
+ * the fleet aggregator can route around it. A probe that throws counts as failed (never crashes readiness), and
+ * its duration is still recorded. Mirrors src/selfhost/health.ts's `readiness`/`timedReadinessCheck` behavior.
+ *
+ * @param {ReadinessProbe[]} [probes]
+ * @returns {Promise<{ ok: boolean, checks: Record<string, boolean>, durationsMs: Record<string, number> }>}
+ */
+export async function readiness(probes = []) {
+  const checks = {};
+  const durationsMs = {};
+  let ok = true;
+  for (const probe of probes) {
+    const startedAt = performance.now();
+    let passed = false;
+    try {
+      passed = (await probe.check()) === true;
+    } catch {
+      passed = false;
+    } finally {
+      durationsMs[probe.name] = Math.max(0, performance.now() - startedAt);
+    }
+    checks[probe.name] = passed;
+    if (!passed) ok = false;
+  }
+  return { ok, checks, durationsMs };
+}
+
+function sendJson(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(payload);
+}
+
+/**
+ * Build the request handler for the AMS health surface: `GET /health` -> 200 liveness, `GET /ready` -> 200/503
+ * readiness (503 when any probe fails, so a load balancer stops routing to a degraded container), anything else
+ * -> 404. Exported separately from {@link startAmsHealthServer} so it can be exercised without binding a socket.
+ *
+ * @param {ReadinessProbe[]} [probes]
+ */
+export function createAmsHealthHandler(probes = []) {
+  return async (req, res) => {
+    const path = (req.url ?? "").split("?", 1)[0];
+    if (req.method === "GET" && path === "/health") {
+      sendJson(res, 200, buildHealthBody());
+      return;
+    }
+    if (req.method === "GET" && path === "/ready") {
+      const result = await readiness(probes);
+      sendJson(res, result.ok ? 200 : 503, result);
+      return;
+    }
+    sendJson(res, 404, { error: "not_found" });
+  };
+}
+
+/**
+ * Start the AMS health HTTP server. Resolves once it is listening. `port: 0` binds an ephemeral port (the caller
+ * reads `server.address()`), which is what the tests use. The hosted-container entry point owns the lifecycle and
+ * passes the AMS-specific probes (store reachable, loop cycle alive); the returned server is closed on shutdown.
+ *
+ * @param {{ port?: number, host?: string, probes?: ReadinessProbe[] }} [options]
+ * @returns {Promise<import("node:http").Server>}
+ */
+export function startAmsHealthServer(options = {}) {
+  const port = Number.isInteger(options.port) ? options.port : 0;
+  const host = typeof options.host === "string" && options.host ? options.host : "0.0.0.0";
+  const probes = Array.isArray(options.probes) ? options.probes : [];
+  const server = createServer(createAmsHealthHandler(probes));
+  return new Promise((resolve) => {
+    server.listen(port, host, () => resolve(server));
+  });
+}

test/unit/miner-ams-health-server.test.ts

@@ -0,0 +1,138 @@
+import { afterEach, describe, expect, it } from "vitest";
+import type { Server } from "node:http";
+import {
+  buildHealthBody,
+  createAmsHealthHandler,
+  readiness,
+  startAmsHealthServer,
+} from "../../packages/loopover-miner/lib/ams-health-server.js";
+
+const servers: Server[] = [];
+afterEach(() => {
+  for (const server of servers.splice(0)) server.close();
+});
+
+type CapturedRes = {
+  out: { status: number; headers: Record<string, string>; body: string };
+  writeHead(status: number, headers: Record<string, string>): void;
+  end(body: string): void;
+};
+
+function mockRes(): CapturedRes {
+  const out = { status: 0, headers: {} as Record<string, string>, body: "" };
+  return {
+    out,
+    writeHead(status, headers) {
+      out.status = status;
+      out.headers = headers;
+    },
+    end(body) {
+      out.body = body;
+    },
+  };
+}
+
+const passProbe = (name: string) => ({ name, check: async () => true });
+const failProbe = (name: string) => ({ name, check: async () => false });
+const throwProbe = (name: string) => ({
+  name,
+  check: async () => {
+    throw new Error("backend unreachable");
+  },
+});
+
+describe("ams-health-server buildHealthBody / readiness (#7177)", () => {
+  it("liveness body is a bare { status: 'ok' }", () => {
+    expect(buildHealthBody()).toEqual({ status: "ok" });
+  });
+
+  it("readiness with no probes is ok with empty check maps", async () => {
+    expect(await readiness()).toEqual({ ok: true, checks: {}, durationsMs: {} });
+  });
+
+  it("readiness is ok only when every probe passes, and times each one", async () => {
+    const result = await readiness([passProbe("store"), passProbe("loop")]);
+    expect(result.ok).toBe(true);
+    expect(result.checks).toEqual({ store: true, loop: true });
+    expect(typeof result.durationsMs.store).toBe("number");
+    expect(result.durationsMs.loop).toBeGreaterThanOrEqual(0);
+  });
+
+  it("readiness fails when any probe returns false or throws (never crashing)", async () => {
+    const result = await readiness([passProbe("store"), failProbe("loop"), throwProbe("queue")]);
+    expect(result.ok).toBe(false);
+    expect(result.checks).toEqual({ store: true, loop: false, queue: false });
+    expect(typeof result.durationsMs.queue).toBe("number"); // duration recorded even for the throwing probe
+  });
+});
+
+describe("ams-health-server request routing (#7177)", () => {
+  it("GET /health returns 200 liveness", async () => {
+    const res = mockRes();
+    await createAmsHealthHandler()({ method: "GET", url: "/health" }, res);
+    expect(res.out.status).toBe(200);
+    expect(res.out.headers["content-type"]).toBe("application/json");
+    expect(JSON.parse(res.out.body)).toEqual({ status: "ok" });
+  });
+
+  it("GET /ready returns 200 when probes pass, 503 when they don't", async () => {
+    const okRes = mockRes();
+    await createAmsHealthHandler([passProbe("store")])({ method: "GET", url: "/ready" }, okRes);
+    expect(okRes.out.status).toBe(200);
+    expect(JSON.parse(okRes.out.body).ok).toBe(true);
+
+    const degradedRes = mockRes();
+    await createAmsHealthHandler([failProbe("store")])({ method: "GET", url: "/ready?verbose=1" }, degradedRes);
+    expect(degradedRes.out.status).toBe(503); // query string stripped, still matched /ready
+    expect(JSON.parse(degradedRes.out.body).ok).toBe(false);
+  });
+
+  it("unknown paths, non-GET methods, and missing urls all 404", async () => {
+    const handler = createAmsHealthHandler();
+    const unknown = mockRes();
+    await handler({ method: "GET", url: "/metrics" }, unknown);
+    expect(unknown.out.status).toBe(404);
+
+    const wrongMethod = mockRes();
+    await handler({ method: "POST", url: "/health" }, wrongMethod);
+    expect(wrongMethod.out.status).toBe(404);
+
+    const noUrl = mockRes();
+    await handler({ method: "GET" }, noUrl); // url undefined -> "" -> 404
+    expect(noUrl.out.status).toBe(404);
+    expect(JSON.parse(noUrl.out.body)).toEqual({ error: "not_found" });
+  });
+});
+
+describe("ams-health-server listener (#7177)", () => {
+  async function base(server: Server) {
+    const address = server.address();
+    if (address === null || typeof address === "string") throw new Error("expected a bound TCP address");
+    return `http://127.0.0.1:${address.port}`;
+  }
+
+  it("serves /health, /ready, and 404s over a real socket on an ephemeral port", async () => {
+    const server = await startAmsHealthServer(); // all defaults: port 0, host 0.0.0.0, no probes
+    servers.push(server);
+    const url = await base(server);
+
+    const health = await fetch(`${url}/health`);
+    expect(health.status).toBe(200);
+    expect(await health.json()).toEqual({ status: "ok" });
+
+    const ready = await fetch(`${url}/ready`);
+    expect(ready.status).toBe(200);
+
+    const missing = await fetch(`${url}/nope`);
+    expect(missing.status).toBe(404);
+  });
+
+  it("reports 503 over the socket when a wired probe fails", async () => {
+    const server = await startAmsHealthServer({ port: 0, host: "127.0.0.1", probes: [failProbe("store")] });
+    servers.push(server);
+    const ready = await fetch(`${await base(server)}/ready`);
+    expect(ready.status).toBe(503);
+    const body = (await ready.json()) as { checks: Record<string, boolean> };
+    expect(body.checks).toEqual({ store: false });
+  });
+});