[CollinsKRO]

Closes #334

The gap

/status answers neither question a platform asks, and the two are not the same question:

	Question	Cost of a wrong answer
/live	Is this process wedged and in need of a kill?	Restarting healthy processes turns a dependency blip into a fleet-wide cold-start storm
/ready	Should this process receive traffic yet?	Sending traffic to a process that cannot answer it

/status reads indexer_state, so it fails when Postgres is unreachable — useless as a liveness signal — and it says nothing about boot state. That gap is real here: app.listen() runs part-way through main(), before the ingesters, the retention worker and the websocket fan-out start. Between listening and those loops running, the process accepts requests it cannot yet answer correctly.

What was added

GET /live — 200 { ok, uptimeSeconds }, touching no dependency. Reaching the handler is the signal. It stays healthy while Postgres is down and while the app is still booting, because a starting instance needs to be held out of rotation, not killed.

GET /ready — 200 with ok: true when it can serve, 503 with ok: false otherwise, plus a per-dependency breakdown:

{
  "ok": false, "booted": true,
  "checks": {
    "postgres": { "status": "down", "latencyMs": 2001, "reason": "unreachable or not migrated" },
    "redis":    { "status": "up", "latencyMs": 1, "reason": null }
  },
  "checkedAt": "2026-10-19T10:00:00.000Z"
}

Unhealthy until markBootComplete() runs at the end of main(). While not booted it probes nothing at all — no dependency check can make a not-yet-booted process ready, so polling it costs nothing.

Acceptance criteria

• /live returns healthy without touching Postgres or Redis — asserted directly (mockQuery/mockPing never called), and again with both dependencies rejecting, so a database outage provably cannot fail liveness on every instance at once.
• /ready returns unhealthy before boot completes and healthy after — 503 with booted: false before, 200 with booted: true after markBootComplete().
• /ready reports unhealthy when Postgres is unreachable — plus a separate case for reachable-but-unmigrated, since connectivity alone would report a process with no tables as ready.
• Both excluded from rate limiting and from httpMetrics route cardinality — PROBE_PATHS in src/app.ts and EXCLUDED_ROUTES in src/middleware/httpMetrics.ts. Each has a control test so neither can pass vacuously: an ordinary route still 429s under the same limiter, and /status still gets counted.
• /status is unchanged — its allow-listing, its public, max-age=15 policy and its shape are all asserted to be unaffected.

Three decisions worth flagging

Redis in readiness, but optional. It is included by default because the snapshot retention worker and the aggregate refresh queue are Redis-backed and stop silently without it. But main() already treats an unavailable Redis as non-fatal and serves prices uncached from Postgres — so on a deliberately Redis-less deployment, failing readiness would pull a healthy instance out of rotation. READINESS_REDIS_CHECK=false opts out; the response reports skipped rather than pretending it passed.

Probes are bounded, but the timeout is shorter than the house 10s. node-postgres exposes no AbortSignal on query(), so the deadline is applied by racing. A 10s probe on a 5s poll interval would answer from the past, so the default is 2s. A probe that exceeds it reports down without cancelling the query underneath — READINESS_CACHE_MS is what bounds how many such queries can be outstanding, which is why answers are cached and concurrent polls share one in-flight run.

Errors are not echoed in the response. A connection error carries the host and port, and these are public endpoints. The response carries a fixed reason phrase and the underlying error goes to the log. There is a test asserting no host, port or errno reaches the body.

Also updated

The deployed smoke check previously skipped /ready when absent, with a message pointing at this issue. A smoke check that silently tolerates a missing probe is how a deployment ends up unmonitored while still green, so it now fails on a 404 and also asserts /live. Both new probe paths are documented in openapi.yaml/openapi.json (the OpenAPI coverage test enforces that), and written up in docs/health.md.

npm test — 829 passed, 1 skipped (806 before, +23 new). npx tsc --noEmit, npm run build and npm run test:smoke all clean.

[drips-wave]

@CollinsKRO Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Miracle656]

Merged. You got the distinction that actually matters, and wrote down why.

/live not touching Postgres or Redis is the whole thing. A liveness probe that checks dependencies fails on every instance at once during a database blip, and the orchestrator responds by restarting the entire fleet — so a brief dependency outage becomes a cold-start storm, which is strictly worse than the outage. Plenty of real services ship that bug. Having the reason in the module comment means the next person won't "improve" /live by adding a database check to it.

The boot-state half is the subtler catch and you got that too: app.listen() happens part-way through main(), before the ingesters, the retention worker and the websocket fan-out start. In that window the process answers connections but cannot serve a price, so "listening" is not "ready" — and markBootComplete() at the end of the sequence is the right place to flip it.

Also right to use tighter deadlines than the house AbortSignal.timeout pattern, with the reason stated: pg has no per-query abort, and a probe slower than the platform's own poll interval reports staleness as health.

Merge notes: README conflicted twice, both additive. /snapshot and the websocket-backpressure doc link both landed on main while this was open, so the route table keeps all three rows and the operational-docs line keeps all four links. Nothing of yours changed.

Verified on the merge result rather than your branch: tsc --noEmit silent, 879 tests across 82 suites, nothing red.

One thing to know: #553 (issue #352, database schema verification at startup) also adds a /ready route, in src/api/rest.ts. Yours holds #334 and landed first, so that overlap resolves in your favour — I'll be asking that PR to drop its own /ready and surface its schema check through your readiness path instead, which is where a "the schema doesn't match the code" signal belongs anyway.

Closes #334.