seam(api): wire OSRM reachability into /healthz and /metrics #102

Merged

patrick merged 1 commit from seam/wire-osrm-health-metrics into main

2026-09-11 14:20:27 +00:00

patrick commented

2026-09-11 14:18:44 +00:00

Owner

Description

Resolves seam request #89: wires OSRM reachability (polaris.core.health.check_osrm(), shipped
by PH6.1/#42) into GET /healthz and /metrics, which #42 could not touch itself — neither
file was in its owned paths.

What changed

api/routers/platform/health.py: CheckStatus widens from Literal["green", "red"] to
Literal["green", "yellow", "red"]. checks.osrm reports green/yellow from
check_osrm(); overall is the worst check by severity, so OSRM down alone reaches yellow
(200, not 503 — the engine'''s haversine fallback means this isn'''t an outage) while db down
still forces red/503 (no fallback exists for the database).
api/metrics.py: polaris_osrm_reachable gauge (1/0), same live-probe-per-scrape style as
the existing task/solver gauges.
Tests updated/added for both files, including the degraded-not-failed case and that db-red
still outranks osrm-yellow.

Test Plan

Full backend suite green: 682 unit + 9 integration tests, ruff/ruff format --check/
mypy --strict all clean.

Checklist

Conventional commit
Tests added/updated, all passing
No hard deletes; no direct status updates outside polaris.domain
No new dependency

Note

Keycloak JWKS reachability has the identical shape of problem per #89'''s own notes, but is left
for a follow-up — out of scope for what was actually blocking #42.

Closes #89

🤖 Generated with Claude Code

https://claude.ai/code/session_01LoNrSy7Reyp7evkfcdHeLX

## Description Resolves seam request #89: wires OSRM reachability (`polaris.core.health.check_osrm()`, shipped by PH6.1/#42) into `GET /healthz` and `/metrics`, which #42 could not touch itself — neither file was in its owned paths. ## What changed - `api/routers/platform/health.py`: `CheckStatus` widens from `Literal["green", "red"]` to `Literal["green", "yellow", "red"]`. `checks.osrm` reports `green`/`yellow` from `check_osrm()`; `overall` is the worst check by severity, so OSRM down alone reaches `yellow` (200, not 503 — the engine'''s haversine fallback means this isn'''t an outage) while `db` down still forces `red`/503 (no fallback exists for the database). - `api/metrics.py`: `polaris_osrm_reachable` gauge (1/0), same live-probe-per-scrape style as the existing task/solver gauges. - Tests updated/added for both files, including the degraded-not-failed case and that db-red still outranks osrm-yellow. ## Test Plan Full backend suite green: 682 unit + 9 integration tests, `ruff`/`ruff format --check`/ `mypy --strict` all clean. ## Checklist - [x] Conventional commit - [x] Tests added/updated, all passing - [x] No hard deletes; no direct status updates outside `polaris.domain` - [x] No new dependency ## Note Keycloak JWKS reachability has the identical shape of problem per #89'''s own notes, but is left for a follow-up — out of scope for what was actually blocking #42. Closes #89 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01LoNrSy7Reyp7evkfcdHeLX

patrick added 1 commit

2026-09-11 14:18:44 +00:00

seam(api): wire OSRM reachability into /healthz and /metrics (#89 ) 6dab3d830a

PH6.1 (#42) shipped polaris.core.health.check_osrm() as a standalone
probe but couldn't wire it into /healthz or /metrics itself — neither
file is in that ticket's owned paths, and the router's CheckStatus was
a two-state Literal["green", "red"] that can't express "degraded"
(docs/07-architecture.md: "osrm reachable -> degraded not failed").

- api/routers/platform/health.py: CheckStatus widens to
  green/yellow/red. GET /healthz calls check_osrm(), adds
  checks["osrm"]; overall is the worst of the individual checks
  (severity-ordered), so db down still forces red (no fallback) while
  osrm down alone only reaches yellow (200, not 503 - the engine's
  haversine fallback means this isn't an outage).
- api/metrics.py: polaris_osrm_reachable gauge (1/0), same
  live-probe-per-scrape style as the existing task/solver gauges.
- Tests: the existing healthz tests now monkeypatch check_osrm for
  determinism (previously implicit on OSRM being reachable, which it
  never is in CI); new cases cover the degraded-not-failed path and
  that db red still outranks osrm yellow.

Keycloak JWKS reachability has the identical shape of problem (per
#89's own notes) but is left for a follow-up - out of scope for what
was actually blocking #42.

Closes #89

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LoNrSy7Reyp7evkfcdHeLX