feat(ops): add /readyz readiness probe for Postgres and Redis

Public readiness endpoint for HAProxy blue/green cutover. /healthz stays
liveness-only; /readyz returns 503 when Postgres or Redis is unavailable.

Author: Ferryx349

.changeset/readyz-endpoint.md

@@ -0,0 +1,7 @@
+---
+"nostream": patch
+---
+
+feat(ops): add /readyz readiness probe for Postgres and Redis
+
+Adds a public readiness endpoint for zero-downtime deploy workflows. HAProxy (or similar) can use `/readyz` to confirm an instance can serve traffic before cutover, while `/healthz` remains a lightweight liveness check.

deploy/README.md

@@ -98,8 +98,23 @@ Or use the admin API/UI once `admin.enabled` is configured.
 ```bash
 docker compose ps
 curl -s -H 'Accept: application/nostr+json' http://127.0.0.1:8008/
+curl -s http://127.0.0.1:8008/readyz
 ```
 
+## Health checks
+
+Use the relay HTTP port (default `8008`) for deploy and load-balancer probes:
+
+| Endpoint   | Type       | Behavior                                                 | Typical use                   |
+|------------|------------|----------------------------------------------------------|-------------------------------|
+| `/healthz` | Liveness   | Always `200 OK` if the process is running                | Restart unhealthy containers  |
+| `/readyz`  | Readiness  | `200` when Postgres and Redis respond; `503` otherwise   | HAProxy blue/green cutover    |
+
+`/readyz` is unauthenticated and intended for infrastructure. It reuses the same
+Postgres and Redis checks as `/admin/health` without requiring admin auth.
+Use readiness before routing traffic to a new instance during deploys; graceful
+WebSocket draining on shutdown is planned as a follow-up.
+
 ## Image delivery on restricted networks
 
 Some hosts cannot reach GHCR over IPv4:

src/handlers/request-handlers/get-readyz-request-handler.ts

@@ -0,0 +1,42 @@
+import { NextFunction, Request, Response } from 'express'
+
+import { AdminDependencyHealth, collectAdminHealthSnapshot } from '../../utils/admin-health'
+
+// Public readiness probe for load balancers (e.g. HAProxy blue/green). Unlike /healthz
+// (liveness), /readyz returns non-200 when Postgres or Redis is unavailable.
+export interface ReadyzSnapshot {
+  status: 'ok' | 'unavailable'
+  database: AdminDependencyHealth
+  redis: AdminDependencyHealth
+}
+
+export const buildReadyzSnapshot = (database: AdminDependencyHealth, redis: AdminDependencyHealth): ReadyzSnapshot => {
+  const ready = database.ok && redis.ok
+
+  return {
+    status: ready ? 'ok' : 'unavailable',
+    database,
+    redis,
+  }
+}
+
+export const getReadyzRequestHandler = async (_req: Request, res: Response, next: NextFunction) => {
+  try {
+    const health = await collectAdminHealthSnapshot()
+    const snapshot = buildReadyzSnapshot(health.database, health.redis)
+    const statusCode = snapshot.status === 'ok' ? 200 : 503
+
+    res.status(statusCode).setHeader('content-type', 'application/json; charset=utf-8').send(snapshot)
+  } catch {
+    res
+      .status(503)
+      .setHeader('content-type', 'application/json; charset=utf-8')
+      .send({
+        status: 'unavailable',
+        database: { ok: false },
+        redis: { ok: false },
+      } satisfies ReadyzSnapshot)
+  }
+
+  next()
+}

src/routes/index.ts

@@ -5,6 +5,7 @@ import adminRouter from './admin'
 import admissionRouter from './admissions'
 import callbacksRouter from './callbacks'
 import { getHealthRequestHandler } from '../handlers/request-handlers/get-health-request-handler'
+import { getReadyzRequestHandler } from '../handlers/request-handlers/get-readyz-request-handler'
 import { getPrivacyRequestHandler } from '../handlers/request-handlers/get-privacy-request-handler'
 import { getTermsRequestHandler } from '../handlers/request-handlers/get-terms-request-handler'
 import invoiceRouter from './invoices'
@@ -24,7 +25,10 @@ router.use((req, res, next) => {
 
 // codeql[js/missing-rate-limiting]
 router.get('/', rootRequestHandler)
+// Liveness: process is running (always 200). Used for "is the container up?" checks.
 router.get('/healthz', getHealthRequestHandler)
+// Readiness: Postgres + Redis must respond. Used before routing traffic during deploys.
+router.get('/readyz', getReadyzRequestHandler)
 router.get('/terms', getTermsRequestHandler)
 router.get('/privacy', getPrivacyRequestHandler)
 

test/integration/features/response-types/response-types.feature

@@ -10,6 +10,7 @@ Feature: HTTP response types
       | /                      | application/nostr+json  | 200        | application/nostr+json |
       | /                      | text/html               | 200        | text/html              |
       | /healthz               | */*                     | 200        | text/plain             |
+      | /readyz                | */*                     | 200        | application/json       |
       | /terms                 | */*                     | 200        | text/html              |
       | /.well-known/nodeinfo  | */*                     | 200        | application/json       |
       | /nodeinfo/2.1          | */*                     | 200        | application/json       |

test/unit/handlers/request-handlers/get-readyz-request-handler.spec.ts

@@ -0,0 +1,123 @@
+import chai from 'chai'
+import sinon from 'sinon'
+import sinonChai from 'sinon-chai'
+
+import * as adminHealth from '../../../../src/utils/admin-health'
+import {
+  buildReadyzSnapshot,
+  getReadyzRequestHandler,
+} from '../../../../src/handlers/request-handlers/get-readyz-request-handler'
+
+chai.use(sinonChai)
+const { expect } = chai
+
+describe('buildReadyzSnapshot', () => {
+  it('returns ok when database and redis are healthy', () => {
+    expect(buildReadyzSnapshot({ ok: true }, { ok: true })).to.deep.equal({
+      status: 'ok',
+      database: { ok: true },
+      redis: { ok: true },
+    })
+  })
+
+  it('returns unavailable when either dependency is unhealthy', () => {
+    expect(buildReadyzSnapshot({ ok: false }, { ok: true })).to.deep.equal({
+      status: 'unavailable',
+      database: { ok: false },
+      redis: { ok: true },
+    })
+  })
+})
+
+describe('getReadyzRequestHandler', () => {
+  let sandbox: sinon.SinonSandbox
+  let collectAdminHealthSnapshotStub: sinon.SinonStub
+
+  beforeEach(() => {
+    sandbox = sinon.createSandbox()
+    collectAdminHealthSnapshotStub = sandbox.stub(adminHealth, 'collectAdminHealthSnapshot')
+  })
+
+  afterEach(() => {
+    sandbox.restore()
+  })
+
+  it('responds with 200 JSON when dependencies are ready', async () => {
+    collectAdminHealthSnapshotStub.resolves({
+      status: 'ok',
+      uptimeSeconds: 42,
+      worker: { type: 'primary' },
+      database: { ok: true },
+      redis: { ok: true },
+    })
+
+    const req = {} as any
+    const res = {
+      status: sinon.stub().returnsThis(),
+      setHeader: sinon.stub().returnsThis(),
+      send: sinon.stub().returnsThis(),
+    } as any
+    const next = sinon.stub()
+
+    await getReadyzRequestHandler(req, res, next)
+
+    expect(res.status).to.have.been.calledOnceWithExactly(200)
+    expect(res.setHeader).to.have.been.calledOnceWithExactly('content-type', 'application/json; charset=utf-8')
+    expect(res.send).to.have.been.calledOnceWithExactly({
+      status: 'ok',
+      database: { ok: true },
+      redis: { ok: true },
+    })
+    expect(next).to.have.been.calledOnce
+  })
+
+  it('responds with 503 JSON when a dependency is unavailable', async () => {
+    collectAdminHealthSnapshotStub.resolves({
+      status: 'degraded',
+      uptimeSeconds: 42,
+      worker: { type: 'primary' },
+      database: { ok: true },
+      redis: { ok: false },
+    })
+
+    const req = {} as any
+    const res = {
+      status: sinon.stub().returnsThis(),
+      setHeader: sinon.stub().returnsThis(),
+      send: sinon.stub().returnsThis(),
+    } as any
+    const next = sinon.stub()
+
+    await getReadyzRequestHandler(req, res, next)
+
+    expect(res.status).to.have.been.calledOnceWithExactly(503)
+    expect(res.send).to.have.been.calledOnceWithExactly({
+      status: 'unavailable',
+      database: { ok: true },
+      redis: { ok: false },
+    })
+    expect(next).to.have.been.calledOnce
+  })
+
+  it('responds with 503 JSON when dependency collection throws', async () => {
+    collectAdminHealthSnapshotStub.rejects(new Error('boom'))
+
+    const req = {} as any
+    const res = {
+      status: sinon.stub().returnsThis(),
+      setHeader: sinon.stub().returnsThis(),
+      send: sinon.stub().returnsThis(),
+    } as any
+    const next = sinon.stub()
+
+    await getReadyzRequestHandler(req, res, next)
+
+    expect(res.status).to.have.been.calledOnceWithExactly(503)
+    expect(res.send).to.have.been.calledOnceWithExactly({
+      status: 'unavailable',
+      database: { ok: false },
+      redis: { ok: false },
+    })
+    expect(next).to.have.been.calledOnce
+  })
+})