ekklesiaandClaude Opus 5.5
aaec9789c4
Add GET /api/v1/health/live and GET /api/v1/health/ready per ADR 0044.
- live returns a fixed 200 {"status":"live"} whenever the process serves.
- ready returns 200 {"status":"ready"} only when module startup has
completed (and shutdown has not begun) and a database ping succeeds
within 2s; otherwise a fixed 503 {"code":"NOT_READY"}.
- The ping runs on the shared pool as one simple-protocol message with
a transaction-local statement_timeout, so PostgreSQL cancels a stalled
statement; the pool discards the connection on failure.
- At most one ping is ever unsettled: probes share its outcome and, once
its deadline passes, answer 503 immediately until it settles.
- Both routes set Cache-Control: no-store, accept GET only (405 with
Allow: GET otherwise, HEAD included), never resolve a principal, and
are mounted in app.ts beside, never inside, /api/v1/modules/.
- createApiApp gains a required `health` option; startApi supplies it
and clears module readiness when shutdown begins.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
86 lines
4.1 KiB
TypeScript
86 lines
4.1 KiB
TypeScript
import type { ModuleDatabase } from "@ekklesia/contracts";
|
|
import {
|
|
type AuthorizationDrizzleDatabase,
|
|
createAuthorizationDrizzleView,
|
|
} from "@ekklesia/core/authorization";
|
|
import {
|
|
createDashboardDrizzleView,
|
|
type DashboardDrizzleDatabase,
|
|
} from "@ekklesia/core/dashboard";
|
|
import { createValidatedPostgresPool, type PostgresPoolOptions } from "@ekklesia/core/database";
|
|
import { createDeviceDrizzleView, type DeviceDrizzleDatabase } from "@ekklesia/core/devices";
|
|
import { createIdentityDrizzleView, type IdentityDrizzleDatabase } from "@ekklesia/core/identity";
|
|
import {
|
|
createModuleConfigurationView,
|
|
createModuleDatabaseView,
|
|
createModuleLifecycleView,
|
|
type ModuleConfigurationDrizzleDatabase,
|
|
type ModuleLifecycleDrizzleDatabase,
|
|
} from "@ekklesia/core/modules";
|
|
|
|
export interface ApiDatabaseHandle {
|
|
readonly authorization: AuthorizationDrizzleDatabase;
|
|
readonly devices: DeviceDrizzleDatabase;
|
|
readonly dashboard: DashboardDrizzleDatabase;
|
|
readonly identity: IdentityDrizzleDatabase;
|
|
readonly module: ModuleDatabase;
|
|
readonly moduleConfiguration: ModuleConfigurationDrizzleDatabase;
|
|
readonly moduleLifecycle: ModuleLifecycleDrizzleDatabase;
|
|
/**
|
|
* One trivial round trip on the shared pool, for readiness (`./health-routes.js`). The `SELECT 1`
|
|
* runs in a read-only transaction carrying its own `SET LOCAL statement_timeout`, so PostgreSQL
|
|
* cancels a stalled statement itself rather than the caller merely abandoning it; the pool's
|
|
* session-wide `statement_timeout`/`query_timeout` remain the outer bound. The four statements
|
|
* travel as one simple-protocol message, so the check costs a single round trip. On any failure
|
|
* the pool discards that connection instead of returning it, so a transaction left open by a
|
|
* cancelled statement never reaches another caller. Rejects with whatever the driver raised; no
|
|
* caller may surface it.
|
|
*/
|
|
readonly ping: (statementTimeoutMs: number) => Promise<void>;
|
|
/** Closes the one shared pool exactly once, regardless of how many typed views were created
|
|
* over it. Safe to call from both a startup-failure cleanup path and normal shutdown. */
|
|
readonly close: () => Promise<void>;
|
|
}
|
|
|
|
function pingStatement(statementTimeoutMs: number): string {
|
|
// Interpolated rather than bound: neither SET nor a multi-statement simple query accepts
|
|
// parameters. Only a positive safe integer can ever reach the SQL text.
|
|
if (!Number.isSafeInteger(statementTimeoutMs) || statementTimeoutMs <= 0) {
|
|
throw new RangeError("The ping statement timeout must be a positive integer.");
|
|
}
|
|
return `BEGIN READ ONLY; SET LOCAL statement_timeout = ${statementTimeoutMs}; SELECT 1; COMMIT`;
|
|
}
|
|
|
|
/**
|
|
* Composes the one physical PostgreSQL pool this process uses for Core's identity and
|
|
* authorization schemas plus the module database facade: one validated, timeout-bounded
|
|
* `pg.Pool` (`createValidatedPostgresPool`, `@ekklesia/core/database`), wrapped by independent
|
|
* typed Drizzle views (`createIdentityDrizzleView`, `createAuthorizationDrizzleView`,
|
|
* `createDashboardDrizzleView`, `createModuleLifecycleView`, `createModuleConfigurationView`,
|
|
* `createModuleDatabaseView`). No domain
|
|
* owns or closes the pool in this composition — `close()`
|
|
* here is the only thing that ever calls `pool.end()`. `createIdentityDrizzleDatabase`/
|
|
* `createAuthorizationDrizzleDatabase` remain available, unaffected, and independently testable
|
|
* for callers that only need one domain.
|
|
*/
|
|
export function createApiDatabase(
|
|
databaseUrl: string,
|
|
options: PostgresPoolOptions = {},
|
|
): ApiDatabaseHandle {
|
|
const { close, pool } = createValidatedPostgresPool(databaseUrl, options);
|
|
|
|
return Object.freeze({
|
|
authorization: createAuthorizationDrizzleView(pool),
|
|
close,
|
|
devices: createDeviceDrizzleView(pool),
|
|
dashboard: createDashboardDrizzleView(pool),
|
|
identity: createIdentityDrizzleView(pool),
|
|
module: createModuleDatabaseView(pool),
|
|
moduleConfiguration: createModuleConfigurationView(pool),
|
|
moduleLifecycle: createModuleLifecycleView(pool),
|
|
ping: async (statementTimeoutMs: number) => {
|
|
await pool.query(pingStatement(statementTimeoutMs));
|
|
},
|
|
});
|
|
}
|