From 138ea78ec7711135a828b95639cd3cd6f593adb7 Mon Sep 17 00:00:00 2001 From: Corey Blais Date: Thu, 22 Oct 2026 09:31:25 -0400 Subject: [PATCH] Return dependency readiness from the public API health endpoint --- README.md | 5 ++-- backend/src/app.ts | 26 +++++++------------ backend/src/health/readiness.test.ts | 38 ++++++++++++++++++++++++++++ backend/src/health/readiness.ts | 25 ++++++++++++++++++ 4 files changed, 75 insertions(+), 19 deletions(-) create mode 100644 backend/src/health/readiness.test.ts create mode 100644 backend/src/health/readiness.ts diff --git a/README.md b/README.md index 55a6394..5b00ee7 100644 --- a/README.md +++ b/README.md @@ -55,8 +55,9 @@ Monitor these production checks: - Verifies Nginx is serving the frontend container. - Backend liveness: `GET https://your-host/api/health/live` - Verifies the API process is running. -- Backend readiness: `GET https://your-host/api/health/ready` - - Verifies the API can reach Postgres and Redis. Returns `503` if either dependency is unavailable. +- Application health: `GET https://your-host/api/health` (alias: `/api/health/ready`) + - Use this endpoint for application availability monitoring. Verifies Postgres and Redis, returning HTTP `503` if a check fails or exceeds four seconds, and HTTP `200` only when all checks pass. Responses are not cacheable. + - Connection failures and timeouts also mean unavailable: during a startup database failure, the API may not be listening at all. - Backend metrics: `GET https://your-host/api/metrics` - Admin-authenticated process, request, and queue metrics. - Postgres and Redis: diff --git a/backend/src/app.ts b/backend/src/app.ts index b6e7005..64abe4d 100644 --- a/backend/src/app.ts +++ b/backend/src/app.ts @@ -1,3 +1,4 @@ +import { createReadinessHandler } from './health/readiness.js'; import { photoCacheControl } from './storage/photoCache.js'; import { canUpdateWorkspaceSettings, subscriptionAllowsWrite } from './workspaceAccess.js'; import { buildWorkspaceInviteEmail } from './emails/workspaceInviteEmail.js'; @@ -2210,28 +2211,19 @@ const writeBirdTimelineEvent = async ({ } }; -app.get('/api/health', (_req: Request, res: Response) => { - res.json({ ok: true }); -}); +const readinessHandler = createReadinessHandler([ + () => db.query('SELECT 1'), + () => getBirdMilestoneReminderQueueCounts(), + () => getMedicationReminderQueueCounts(), +]); + +app.get(['/api/health', '/api/health/ready'], readinessHandler); app.get('/api/health/live', (_req: Request, res: Response) => { + res.set('Cache-Control', 'no-store'); res.json({ ok: true, status: 'live' }); }); -app.get('/api/health/ready', async (_req: Request, res: Response) => { - try { - await Promise.all([ - db.query('SELECT 1'), - getBirdMilestoneReminderQueueCounts(), - getMedicationReminderQueueCounts(), - ]); - res.json({ ok: true, status: 'ready' }); - } catch (error) { - console.error('Readiness check failed', error); - res.status(503).json({ ok: false, status: 'not_ready' }); - } -}); - app.get('/api/metrics', requireAuth, requireAdmin, async (_req: Request, res: Response, next: NextFunction) => { const memoryUsage = process.memoryUsage(); const averageDurationMs = requestMetrics.totalRequests > 0 ? requestMetrics.totalDurationMs / requestMetrics.totalRequests : 0; diff --git a/backend/src/health/readiness.test.ts b/backend/src/health/readiness.test.ts new file mode 100644 index 0000000..bb7e4dd --- /dev/null +++ b/backend/src/health/readiness.test.ts @@ -0,0 +1,38 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import type { Request, Response } from 'express'; +import { createReadinessHandler } from './readiness.js'; + +async function probe(checks: Array<() => Promise>) { + const result = { code: 0, cache: '', body: {} }; + const response = { + set(_name: string, value: string) { result.cache = value; return this; }, + status(code: number) { result.code = code; return this; }, + json(body: unknown) { result.body = body as object; return this; }, + } as unknown as Response; + await createReadinessHandler(checks, 20, () => {} )({} as Request, response); + return result; +} + +test('healthy dependencies return uncached HTTP 200', async () => { + const result = await probe([async () => 1, async () => ({})]); + assert.equal(result.code, 200); + assert.equal(result.cache, 'no-store'); + assert.deepEqual(result.body, { ok: true, status: 'ready' }); +}); + +for (const dependency of ['postgres', 'redis']) { + test(`${dependency} failure returns HTTP 503`, async () => { + const checks = [async () => 1, async () => 1]; + checks[dependency === 'postgres' ? 0 : 1] = async () => { throw new Error('unavailable'); }; + const result = await probe(checks); + assert.equal(result.code, 503); + assert.equal(result.cache, 'no-store'); + assert.deepEqual(result.body, { ok: false, status: 'not_ready' }); + }); +} + +test('unresponsive dependencies return HTTP 503 within the deadline', async () => { + const result = await probe([() => new Promise(() => {})]); + assert.equal(result.code, 503); +}); diff --git a/backend/src/health/readiness.ts b/backend/src/health/readiness.ts new file mode 100644 index 0000000..ee98f40 --- /dev/null +++ b/backend/src/health/readiness.ts @@ -0,0 +1,25 @@ +import type { Request, Response } from 'express'; + +/** Dependency readiness shared by the public health and readiness endpoints. */ +export const createReadinessHandler = ( + checks: Array<() => Promise>, + timeoutMs = 4000, + reportError: (error: unknown) => void = (error) => console.error('Readiness check failed', error), +) => async (_req: Request, res: Response) => { + res.set('Cache-Control', 'no-store'); + let timer: ReturnType | undefined; + try { + await Promise.race([ + Promise.all(checks.map((check) => Promise.resolve().then(check))), + new Promise((_resolve, reject) => { + timer = setTimeout(() => reject(new Error('Readiness dependencies timed out')), timeoutMs); + }), + ]); + res.status(200).json({ ok: true, status: 'ready' }); + } catch (error) { + reportError(error); + res.status(503).json({ ok: false, status: 'not_ready' }); + } finally { + clearTimeout(timer); + } +};