Files
0pt/lib/health-checks.ts
admin b3239487b7
CI (SIAX Cloud) / integration (push) Skipped
CI (SIAX Cloud) / sonar (push) Skipped
masterplan-lock / check (push) Successful in 10s
CI (SIAX Cloud) / sonar (pull_request) Skipped
Security Scan (SIAX Cloud) / security (push) Successful in 13s
masterplan-lock / check (pull_request) Successful in 7s
CI (SIAX Cloud) / security (push) Successful in 26s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 17s
CI (SIAX Cloud) / security (pull_request) Successful in 19s
CI (SIAX Cloud) / quality (push) Successful in 1m9s
CI (SIAX Cloud) / quality (pull_request) Successful in 2m26s
CI (SIAX Cloud) / integration (pull_request) Successful in 2m33s
feat(document-workbench): wire customer upload, structuring, credits and readiness
- POST /api/0pt/documents/upload: real multipart bytes into DOC0 through the
  durable attempt journal and the existing coordinator; verified tenant/actor
  only, project authorization fail-closed.
- POST /api/0pt/documents/structure: DOC0 segments -> INF0 -> evidence-bound
  validation -> optional JSON/CSV export, with credit reserve/settle.
- Credits: balance, server-owned price book, Stripe Checkout and idempotent
  webhook reconciliation via a Stripe re-read of session + payment intent.
- /portal/dokument and /portal/krediter: SIAX-styled workspace.
- @siax/access: universal, framework-neutral OpenFGA project relationship
  primitive reusable by DOC0/N0D/other products.
- Readiness: real Redis PING probe instead of presence-only; queue is now a
  live dependency when configured.
- Dockerfile: copy every workspace manifest so --frozen-lockfile works.
- Format/build hygiene: .prettierignore, .worktrees ignored, valid manifest YAML.
2026-11-02 14:46:10 +01:00

284 lines
11 KiB
TypeScript

// Dependency health probes shared by GET /api/health (liveness) and
// GET /api/ready (readiness). See docs/architecture/ARCHITECTURE.md
// "Hälsokontroll" and BACKLOG P0-3 for the finding this fixes: the old
// /api/health handler only ever checked *presence* of an env var and
// hardcoded `ok: true` regardless of whether anything was actually
// reachable -- "an uptime monitor watching HTTP 200 would show green for a
// dying instance". Each check below returns one of four honest states:
//
// "ok" -- configured AND a live round trip succeeded.
// "error" -- configured but the round trip failed (bad creds,
// host unreachable, timeout, ...). detail carries the
// underlying error message.
// "not_configured" -- no env var set. Not a failure by itself (0pt is
// designed to build/boot with everything unset).
// "not_integrated" -- env var IS set, but no client code in this repo
// actually uses it (currently only REDIS_URL/queue --
// see .env.example). Reporting "ok" here would be a
// fabricated check; reporting "not_configured" would
// hide that a value was provided. This is its own
// honest state rather than either of those two.
import net from "node:net";
import tls from "node:tls";
import { dbUrl, getSql } from "./db";
import { getStripe } from "./stripe";
import { hasEngine } from "./engine";
export type DepStatus = "ok" | "error" | "not_configured" | "not_integrated";
export interface DepResult {
status: DepStatus;
detail?: string;
latencyMs?: number;
}
export const DEFAULT_TIMEOUT_MS = 2000;
function errMessage(err: unknown): string {
return err instanceof Error ? err.message : String(err);
}
function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
return new Promise<T>((resolve, reject) => {
const timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
promise.then(
(v) => {
clearTimeout(timer);
resolve(v);
},
(e) => {
clearTimeout(timer);
reject(e);
},
);
});
}
// Minimal shape of the one call site needs from the postgres client --
// matches `postgres`'s tagged-template callable, but kept narrow so tests
// can inject a fake without constructing a real `postgres.Sql`.
export type SqlPing = (strings: TemplateStringsArray, ...values: unknown[]) => Promise<unknown>;
/**
* Postgres reachability. `select 1` is the standard zero-cost liveness query
* -- it never touches application tables, so it can't fail on schema drift.
*/
export async function checkDatabase(
sqlClient: SqlPing | null = getSql() as unknown as SqlPing | null,
timeoutMs: number = DEFAULT_TIMEOUT_MS,
): Promise<DepResult> {
if (!dbUrl() || !sqlClient) return { status: "not_configured" };
const start = Date.now();
try {
await withTimeout(sqlClient`select 1`, timeoutMs, "database ping");
return { status: "ok", latencyMs: Date.now() - start };
} catch (err) {
return { status: "error", detail: errMessage(err), latencyMs: Date.now() - start };
}
}
/**
* FastAPI data engine (services/api) reachability via its own `GET /health`
* (services/api/orchestrator/main.py). Uses a real HTTP round trip, not just
* `hasEngine()` presence -- ENGINE_URL pointing at a dead host used to read
* as healthy.
*/
export async function checkEngine(
fetchImpl: typeof fetch = fetch,
timeoutMs: number = DEFAULT_TIMEOUT_MS,
): Promise<DepResult> {
if (!hasEngine()) return { status: "not_configured" };
const base = process.env.ENGINE_URL as string;
const start = Date.now();
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const res = await fetchImpl(`${base}/health`, {
signal: controller.signal,
cache: "no-store",
headers: { "X-Internal-Token": process.env.INTERNAL_TOKEN ?? "" },
});
if (!res.ok) {
return { status: "error", detail: `HTTP ${res.status}`, latencyMs: Date.now() - start };
}
return { status: "ok", latencyMs: Date.now() - start };
} catch (err) {
return { status: "error", detail: errMessage(err), latencyMs: Date.now() - start };
} finally {
clearTimeout(timer);
}
}
// Minimal shape of the one Stripe call this needs -- matches
// `Stripe#balance.retrieve`, kept narrow so tests can inject a fake instead
// of constructing a real Stripe client.
export interface StripeBalanceClient {
balance: { retrieve(): Promise<unknown> };
}
/**
* Stripe reachability. `balance.retrieve()` is Stripe's documented
* lightweight "is this key valid and can I reach the API" call -- it makes
* one real API round trip (catching e.g. a revoked/placeholder key) without
* mutating anything or touching a specific resource.
*/
export async function checkStripe(
client: StripeBalanceClient | null = getStripe() as unknown as StripeBalanceClient | null,
timeoutMs: number = DEFAULT_TIMEOUT_MS,
): Promise<DepResult> {
if (!client) return { status: "not_configured" };
const start = Date.now();
try {
await withTimeout(client.balance.retrieve(), timeoutMs, "stripe balance.retrieve");
return { status: "ok", latencyMs: Date.now() - start };
} catch (err) {
return { status: "error", detail: errMessage(err), latencyMs: Date.now() - start };
}
}
/**
* Redis/queue reachability.
*
* This used to report `not_integrated` because no code opened REDIS_URL. The
* readiness probe now performs a real round trip (AUTH when the URL carries a
* password, then PING -> +PONG) using only `node:net`/`node:tls`, so a queue
* that is configured but dead fails readiness instead of hiding behind
* `not_integrated`. The probe is injectable for tests.
*/
export type QueueProbe = (redisUrl: string, timeoutMs: number) => Promise<void>;
export function redisPing(redisUrl: string, timeoutMs: number): Promise<void> {
return new Promise<void>((resolve, reject) => {
let url: URL;
try {
url = new URL(redisUrl);
} catch {
reject(new Error("Invalid REDIS_URL"));
return;
}
if (url.protocol !== "redis:" && url.protocol !== "rediss:") {
reject(new Error("Unsupported REDIS_URL scheme"));
return;
}
const port = url.port ? Number(url.port) : 6379;
if (!Number.isSafeInteger(port) || port <= 0 || port > 65535) {
reject(new Error("Invalid REDIS_URL port"));
return;
}
const socket =
url.protocol === "rediss:"
? tls.connect({ host: url.hostname, port, servername: url.hostname })
: net.connect({ host: url.hostname, port });
let settled = false;
const done = (error?: Error) => {
if (settled) return;
settled = true;
clearTimeout(timer);
socket.destroy();
if (error) reject(error);
else resolve();
};
const timer = setTimeout(() => done(new Error("redis ping timed out")), timeoutMs);
let buffer = "";
socket.on("error", (error: Error) => done(error));
socket.on("close", () => {
if (!settled) done(new Error("redis connection closed before PONG"));
});
socket.on("data", (chunk: Buffer) => {
buffer += chunk.toString("utf8");
if (buffer.includes("+PONG")) {
done();
return;
}
if (buffer.startsWith("-")) {
done(new Error(`redis error: ${buffer.trim()}`));
return;
}
// AUTH succeeded (or was unnecessary) but PING has not answered yet.
});
socket.on("connect", () => {
const password = url.password ? decodeURIComponent(url.password) : "";
if (url.username && url.username !== "default" && !password) {
done(new Error("redis username without password is not supported"));
return;
}
// RESP arrays: correct for any password content, unlike inline commands.
const encode = (parts: string[]): string =>
`*${parts.length}\r\n${parts
.map((part) => `$${Buffer.byteLength(part, "utf8")}\r\n${part}\r\n`)
.join("")}`;
const payload =
(password ? encode(["AUTH", password]) : "") + encode(["PING"]);
socket.write(payload);
});
});
}
export async function checkQueue(
probe: QueueProbe = redisPing,
timeoutMs: number = DEFAULT_TIMEOUT_MS,
): Promise<DepResult> {
const redisUrl = process.env.REDIS_URL;
if (!redisUrl) return { status: "not_configured" };
const start = Date.now();
try {
await withTimeout(probe(redisUrl, timeoutMs), timeoutMs + 250, "redis ping");
return { status: "ok", latencyMs: Date.now() - start };
} catch (err) {
return { status: "error", detail: errMessage(err), latencyMs: Date.now() - start };
}
}
export interface DependencyResults {
db: DepResult;
engine: DepResult;
stripe: DepResult;
queue: DepResult;
}
export async function checkAllDependencies(): Promise<DependencyResults> {
const [db, engine, stripe, queue] = await Promise.all([
checkDatabase(),
checkEngine(),
checkStripe(),
checkQueue(),
]);
return { db, engine, stripe, queue };
}
/** True when any dependency that IS configured/integrated is broken. */
export function hasDegradedDependency(deps: DependencyResults): boolean {
return Object.values(deps).some((d) => d.status === "error");
}
/**
* Readiness (unlike liveness) treats "not configured" for the deps this app
* cannot serve real traffic without as not-ready too. `db` is the only
* dependency that is load-bearing merely by being absent -- engine/stripe/
* queue are optional integrations the app is designed to run WITHOUT (see
* .env.example), so "not_configured" for those stays ready.
*
* But "optional to run without" is not the same as "optional to run BROKEN".
* A dependency in the "error" state was deliberately configured by an
* operator AND then failed a live round trip -- somebody asked for it and it
* is not answering. Readiness fails closed on that too.
*
* Measured 2026-09-25 on the production deployment (0pt.app / api.0pt.app),
* which is exactly the hole this closes:
*
* GET /api/health -> HTTP 200 {"ok":false, ..., "engine":"error",
* "detail":{"engine":"This operation was aborted"}}
* GET /api/ready -> HTTP 200 {"ready":true, "db":"ok", "engine":"error"}
*
* ENGINE_URL pointed at `http://0pt-engine:8000`, a hostname with no DNS
* record anywhere on the fleet (`getent hosts 0pt-engine` -> nothing; no such
* container on server5-11). The data engine -- 0pt's whole product -- had
* been absent for the container's entire 17.9 h uptime, and every signal
* above it was green. `ok:false` in a 200 body is not a signal; nothing reads
* bodies.
*/
export function isReady(deps: DependencyResults): boolean {
if (deps.db.status !== "ok") return false;
return !Object.values(deps).some((d) => d.status === "error");
}