Seam: wire OSRM reachability probe into /healthz and /metrics #89

New issue

Closed

opened 2026-09-11 13:58:10 +00:00 by patrick · 0 comments

patrick commented

2026-09-11 13:58:10 +00:00

Owner

Context

PH6.1 (#42) ships polaris.core.health.check_osrm() — a standalone OSRM reachability probe (backend/src/polaris/core/health.py) — per its acceptance criterion "OSRM down → /healthz degraded, plan still produced, W_TRAVEL_FALLBACK finding".

That ticket's owned paths (docs/12-implementation-plan.md row PH6.1) are only engine/travel/osrm.py and core/health.py. The actual /healthz route (backend/src/polaris/api/routers/platform/health.py) and /metrics (backend/src/polaris/api/metrics.py) are outside those owned paths — both were created by PH0.2 and are not listed as PH6.1's to touch — so PH6.1 could not wire the probe into either endpoint without violating the "don't edit files you haven't edited before" rule in CLAUDE.md.

api/routers/platform/health.py's own docstring already anticipated this: "Keycloak JWKS and OSRM reachability checks ... are added by the tickets that introduce those dependencies (PH0.4, PH6.1)" — but its CheckStatus today is a two-state Literal["green", "red"], and docs/07-architecture.md calls for OSRM-down to read as degraded, not failed ("osrm reachable → degraded not failed"), alongside db/Keycloak staying green. That needs a third state.

What this seam needs to do

Widen HealthResponse's CheckStatus (or add a sibling type) to a three-state shape so osrm: red doesn't force overall: red when db/Keycloak are fine — osrm should push overall to a new yellow/degraded value instead.
Call polaris.core.health.check_osrm() from GET /healthz, add checks["osrm"].
Fold the same check into /metrics (a polaris_osrm_reachable gauge, matching the style of the existing polaris_task_queue_depth etc. in api/metrics.py).
PH0.4 (#7, Keycloak JWKS reachability) has the identical shape of problem for the keycloak check — worth doing both in the same PR since they touch the same two files and the same CheckStatus widening.

Acceptance criteria

CheckStatus (or equivalent) has a degraded/yellow state distinct from red
GET /healthz reports checks.osrm using polaris.core.health.check_osrm(), and overall is yellow/degraded (not red) when only OSRM is down
/metrics exposes OSRM reachability
Existing /healthz//metrics tests still pass; new tests cover the degraded-not-failed case

Blocks nothing further from #42 shipping (the provider itself is complete and independently useful — see #42's PR); this closes the remaining gap in its third acceptance criterion.

## Context PH6.1 (#42) ships `polaris.core.health.check_osrm()` — a standalone OSRM reachability probe (`backend/src/polaris/core/health.py`) — per its acceptance criterion "OSRM down → `/healthz` degraded, plan still produced, `W_TRAVEL_FALLBACK` finding". That ticket's owned paths (`docs/12-implementation-plan.md` row PH6.1) are only `engine/travel/osrm.py` and `core/health.py`. The actual `/healthz` route (`backend/src/polaris/api/routers/platform/health.py`) and `/metrics` (`backend/src/polaris/api/metrics.py`) are outside those owned paths — both were created by PH0.2 and are not listed as PH6.1's to touch — so PH6.1 could not wire the probe into either endpoint without violating the "don't edit files you haven't edited before" rule in `CLAUDE.md`. `api/routers/platform/health.py`'s own docstring already anticipated this: "Keycloak JWKS and OSRM reachability checks ... are added by the tickets that introduce those dependencies (PH0.4, PH6.1)" — but its `CheckStatus` today is a two-state `Literal["green", "red"]`, and `docs/07-architecture.md` calls for OSRM-down to read as **degraded**, not failed ("osrm reachable → degraded not failed"), alongside db/Keycloak staying green. That needs a third state. ## What this seam needs to do - Widen `HealthResponse`'s `CheckStatus` (or add a sibling type) to a three-state shape so `osrm: red` doesn't force `overall: red` when db/Keycloak are fine — `osrm` should push `overall` to a new `yellow`/`degraded` value instead. - Call `polaris.core.health.check_osrm()` from `GET /healthz`, add `checks["osrm"]`. - Fold the same check into `/metrics` (a `polaris_osrm_reachable` gauge, matching the style of the existing `polaris_task_queue_depth` etc. in `api/metrics.py`). - PH0.4 (#7, Keycloak JWKS reachability) has the identical shape of problem for the `keycloak` check — worth doing both in the same PR since they touch the same two files and the same `CheckStatus` widening. ## Acceptance criteria - [ ] `CheckStatus` (or equivalent) has a degraded/yellow state distinct from red - [ ] `GET /healthz` reports `checks.osrm` using `polaris.core.health.check_osrm()`, and `overall` is `yellow`/`degraded` (not `red`) when only OSRM is down - [ ] `/metrics` exposes OSRM reachability - [ ] Existing `/healthz`/`/metrics` tests still pass; new tests cover the degraded-not-failed case ## Related Blocks nothing further from #42 shipping (the provider itself is complete and independently useful — see #42's PR); this closes the remaining gap in its third acceptance criterion.

patrick added the

seam-request

label

2026-09-11 13:58:10 +00:00

patrick referenced this issue

2026-09-11 13:58:55 +00:00

PH6.1 — OSRM travel provider with cache, degraded health and W_TRAVEL_FALLBACK #42

patrick added a new dependency

2026-09-11 13:59:13 +00:00

#42 PH6.1 — OSRM travel provider with cache, degraded health and W_TRAVEL_FALLBACK

patrick referenced this issue

2026-09-11 13:59:59 +00:00