test(api): cover /health ResponseWriter; map Degraded/Unhealthy to 503

[thomasluizon]

What

Closes a /prod-readiness tests-audit gap: the /health ResponseWriter had no direct test coverage and its status-code behaviour was wrong for degraded reports.

Source fix (minimal, required to make the writer testable and correct)

• Extracted the inline /health ResponseWriter lambda into an internal WriteHealthCheckResponseAsync(HttpContext, HealthReport) method so it can be unit-tested in isolation.
• The writer now sets the HTTP status explicitly: 200 for Healthy, 503 for Degraded and Unhealthy. Previously it relied on the default ResultStatusCodes map, which returns 200 for Degraded — so stale background services (BackgroundServiceHealthCheck returns Degraded) read as fully live to a load balancer or uptime monitor.
• Enriched the per-check body with description; the raw entry.Exception is still never serialized, so failure detail (messages, stack traces) can't leak.

Tests — tests/Orbit.Infrastructure.Tests/Health/HealthCheckResponseTests.cs

Each builds a HealthReport in-memory and invokes the writer directly against a DefaultHttpContext:

• Healthy → 200, JSON content type, status: "Healthy", and every check's name/status/description surfaced.
• Unhealthy (DB unreachable) → 503, failing check + description surfaced.
• Degraded → 503 (this is the mapping the old code got wrong).
• Exception-carrying check → description surfaced, but the exception message (SUPERSECRET_TOKEN), type name, and stackTrace are absent from the body.
• Empty report → 200 with no checks.

All 5240 API tests pass locally; no narration comments (ORBIT0001).

Refs thomasluizon/orbit-ui-mobile#243

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[claude]

Code Review: PR #379 (thomasluizon/orbit-api)

Scope: PR #379 — test(api): cover /health ResponseWriter; map Degraded/Unhealthy to 503
Recommendation: APPROVE

Summary

Small, well-scoped PR: extracts the inline /health ResponseWriter lambda into a testable internal static WriteHealthCheckResponseAsync(HttpContext, HealthReport) method in src/Orbit.Api/Extensions/WebApplicationExtensions.cs, fixes the previously-wrong status-code mapping (framework default returned 200 for Degraded; now Healthy→200, Degraded/Unhealthy→503), and adds description to each check in the JSON body. Adds 6 focused unit tests in tests/Orbit.Infrastructure.Tests/Health/HealthCheckResponseTests.cs. No prior reviews or review comments exist on this PR — nothing being re-flagged.

Findings

Critical

None.

High

None.

Medium

None.

Low / Info

• [Info] Test class lives in Orbit.Infrastructure.Tests even though it tests Orbit.Api code — this is the established, intentional pattern: Orbit.Api.csproj already declares InternalsVisibleTo Include="Orbit.Infrastructure.Tests" (pre-existing, not added by this PR), and tests/CLAUDE.md documents Orbit.Infrastructure.Tests as the home for "services, prompt sections, controllers, MCP tools." No action needed.
• [Info, from security-reviewer] The newly-serialized Description field is safe today — both registered health checks (DatabaseHealthCheck, BackgroundServiceHealthCheck) only ever populate Description with static strings or internal background-job names, never exception messages or connection strings. The data dictionary (per-service tick timestamps) is confirmed not serialized by the writer — only .Description is read. Worth keeping in mind for future IHealthCheck authors (don't put ex.Message into Description), but not a defect in this diff.

Subagents

Agent	Verdict
security-reviewer	PASS — no data-exposure or auth issues; /health stays AllowAnonymous() per documented exemption; entry.Exception never serialized
contract-aligner	N/A — no DTO, Controller route, or packages/shared type changed; /health's JSON shape is an internal ops/monitoring surface, not part of the cross-repo contract

Validation

Check	Result
Build (dotnet)	N/A — covered by separate required CI checks (Build / Unit Tests / SonarCloud)
Tests (dotnet)	N/A — covered by separate required CI checks (Build / Unit Tests / SonarCloud)

What's good

• Root-causes the actual bug (wrong Degraded→200 mapping) rather than patching around it; matches how HealthCheckMiddleware pre-sets StatusCode from ResultStatusCodes before invoking ResponseWriter — the explicit override in the writer is the correct fix point.
• Test suite is genuinely thorough for the surface: covers all three HealthStatus values, the JSON content-type, per-check field surfacing, an empty-report edge case, and a dedicated test proving an Exception's message/type/stack trace never leak into the public unauthenticated response body.
• No narration comments; the one comment present is an XML ///-style doc block, which is allowed by the comment-policy dimension.
• Minimal diff, single responsibility, no scope creep.

Recommendation

Merge as-is. No blocking issues found.