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
- 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.
284 lines
11 KiB
TypeScript
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");
|
|
}
|