Backend: expose health checks via REST (GET /api/health) #108

Closed
opened 2026-07-02 19:44:03 +02:00 by timothy · 2 comments
Owner

From the ChicoryTV plan audit (epic #59, 2026-07-02).

A full health-check engine exists (GetAllHealthCheckResults + ErsatzTV.Core/Health/Checks/* — the exact checks the Dashboard prototype mocked) but it is a MediatR query consumed only by Blazor. The shipped SPA Dashboard consequently fabricates its health panel from entity counts, and the shell footer hardcodes "Healthy".

Scope

  • Add GET /api/health returning check results {title, status (pass/info/warn/fail), detail, link?} from GetAllHealthCheckResults.
  • Regenerate OpenAPI + SPA types.

Unblocks: Dashboard follow-up (real health panel + fail/warn badge counts), shell footer status dot. Related: #72 (channel lineup health — distinct, per-channel concept).
Effort: S (pure wrapper).

From the ChicoryTV plan audit (epic #59, 2026-07-02). A full health-check engine exists (`GetAllHealthCheckResults` + `ErsatzTV.Core/Health/Checks/*` — the exact checks the Dashboard prototype mocked) but it is a MediatR query consumed only by Blazor. The shipped SPA Dashboard consequently **fabricates** its health panel from entity counts, and the shell footer hardcodes "Healthy". **Scope** - Add `GET /api/health` returning check results `{title, status (pass/info/warn/fail), detail, link?}` from `GetAllHealthCheckResults`. - Regenerate OpenAPI + SPA types. **Unblocks:** Dashboard follow-up (real health panel + fail/warn badge counts), shell footer status dot. Related: #72 (channel lineup health — distinct, per-channel concept). Effort: S (pure wrapper).
timothy added the enhancementapi labels 2026-07-02 19:44:03 +02:00
Author
Owner

Picking this up. Reviewed the salvaged WIP on feat/108-health-api against the issue + API conventions:

Keeping: query/handler/mapper structure (delegates to IHealthCheckService.PerformHealthChecks, filters NotApplicable, maps enum → lowercase pass|fail|warn|info), handler tests, controller tests.

Fixing:

  • HealthCheckResponseModel.Link should be string? (with file-scoped #nullable enable — Core has Nullable=disable) since the mapper emits null when no link.
  • Controller needs the established endpoint attributes (Name on the route, [Tags], [EndpointSummary], [EndpointGroupName("general")]) per the #97/#105 pattern.
  • Rebase onto main (post-#113) + OpenAPI regen.

Design note: each GET /api/health re-runs all ~14 checks (same as the Blazor dashboard per page load; only the warn/error summary is cached). Fine for on-demand loads, but the SPA footer/dashboard should not poll this endpoint aggressively — noting this for #109.

Picking this up. Reviewed the salvaged WIP on `feat/108-health-api` against the issue + API conventions: **Keeping**: query/handler/mapper structure (delegates to `IHealthCheckService.PerformHealthChecks`, filters `NotApplicable`, maps enum → lowercase `pass|fail|warn|info`), handler tests, controller tests. **Fixing**: - `HealthCheckResponseModel.Link` should be `string?` (with file-scoped `#nullable enable` — Core has Nullable=disable) since the mapper emits null when no link. - Controller needs the established endpoint attributes (`Name` on the route, `[Tags]`, `[EndpointSummary]`, `[EndpointGroupName("general")]`) per the #97/#105 pattern. - Rebase onto main (post-#113) + OpenAPI regen. **Design note**: each `GET /api/health` re-runs all ~14 checks (same as the Blazor dashboard per page load; only the warn/error summary is cached). Fine for on-demand loads, but the SPA footer/dashboard should not poll this endpoint aggressively — noting this for #109.
Author
Owner

Closing summary (PR #114, merged to main, CI green):

What was done: GET /api/health (route name GetHealthChecks, group general) returning [{title, status, detail, link?}] with status ∈ pass|fail|warn|info, sourced from IHealthCheckService.PerformHealthChecks — identical semantics to the Blazor dashboard (NotApplicable filtered, cancellation returns empty list, detail = the long Message field). Started from the salvaged WIP, rebased onto post-#113 main.

Root cause of WIP bug: the draft used Option<HealthCheckLink>.Match with a null-returning branch — LanguageExt guards Match against null results (ResultIsNullException), so every check without a link would have thrown at runtime. Fixed with MatchUnsafe (the sanctioned nullable-result variant). Caught because the tests were actually run (3/4 handler tests failed on the draft).

Files changed: ErsatzTV.Application/Health/{Mapper,Queries/GetAllHealthCheckResultsForApi,Queries/GetAllHealthCheckResultsForApiHandler}.cs, ErsatzTV.Core/Api/Health/HealthCheckResponseModel.cs (first #nullable enable DTO in Core/Api — pattern for future nullable fields), ErsatzTV/Controllers/Api/HealthController.cs, handler + controller tests, v1.json regen. 278/278 tests pass.

Review: adversarial review verdict APPROVE (no blockers/majors); applied the one minor — the unreachable NotApplicable→\"info\" mapper arm now throws instead of masking a missing filter.

Deferred / notes for #109: each request re-runs all ~14 health checks (same as Blazor per page load; only the warn/error summary is cached in memory) — the SPA footer/Dashboard should load on demand or poll gently, not aggressively. No caching added (kept scope to the issue; add a TTL later if polling needs it).

Docs: none needed beyond the OpenAPI regen (endpoint is self-describing in /docs); handoff queue doc updated for the next session.

**Closing summary** (PR #114, merged to main, CI green): **What was done**: `GET /api/health` (route name `GetHealthChecks`, group `general`) returning `[{title, status, detail, link?}]` with `status` ∈ `pass|fail|warn|info`, sourced from `IHealthCheckService.PerformHealthChecks` — identical semantics to the Blazor dashboard (`NotApplicable` filtered, cancellation returns empty list, `detail` = the long `Message` field). Started from the salvaged WIP, rebased onto post-#113 main. **Root cause of WIP bug**: the draft used `Option<HealthCheckLink>.Match` with a null-returning branch — LanguageExt guards `Match` against null results (`ResultIsNullException`), so every check *without* a link would have thrown at runtime. Fixed with `MatchUnsafe` (the sanctioned nullable-result variant). Caught because the tests were actually run (3/4 handler tests failed on the draft). **Files changed**: `ErsatzTV.Application/Health/{Mapper,Queries/GetAllHealthCheckResultsForApi,Queries/GetAllHealthCheckResultsForApiHandler}.cs`, `ErsatzTV.Core/Api/Health/HealthCheckResponseModel.cs` (first `#nullable enable` DTO in Core/Api — pattern for future nullable fields), `ErsatzTV/Controllers/Api/HealthController.cs`, handler + controller tests, `v1.json` regen. 278/278 tests pass. **Review**: adversarial review verdict APPROVE (no blockers/majors); applied the one minor — the unreachable `NotApplicable→\"info\"` mapper arm now throws instead of masking a missing filter. **Deferred / notes for #109**: each request re-runs all ~14 health checks (same as Blazor per page load; only the warn/error summary is cached in memory) — the SPA footer/Dashboard should load on demand or poll gently, not aggressively. No caching added (kept scope to the issue; add a TTL later if polling needs it). **Docs**: none needed beyond the OpenAPI regen (endpoint is self-describing in `/docs`); handoff queue doc updated for the next session.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: timothy/ersatztv#108