feat(health): canonical JSON health response writer

2026-06-01 06:42:24 -04:00
parent 5fb579c2f0
commit d1b837e718
4 changed files with 207 additions and 3 deletions
@@ -22,8 +22,10 @@ public static class ZbHealthEndpointExtensions
    /// </summary>
    /// <remarks>
    /// Does NOT call <c>services.AddHealthChecks()</c> — the caller registers probes and their tags.
-    /// The response writer is the framework default (plain-text status); a later task swaps in a
-    /// canonical JSON writer via <see cref="HealthCheckOptions.ResponseWriter"/> (see <paramref name="options"/>).
+    /// The readiness and active tiers use the canonical JSON writer
+    /// (<see cref="ZbHealthWriter.WriteJsonAsync"/>) unless overridden via
+    /// <see cref="ZbHealthEndpointOptions.ResponseWriter"/>. The liveness tier runs no checks and
+    /// emits a minimal <c>200 OK</c> body.
    /// </remarks>
    /// <returns>
    /// The <see cref="IEndpointConventionBuilder"/> for the readiness (<c>/health/ready</c>) endpoint.
@@ -37,17 +39,23 @@ public static class ZbHealthEndpointExtensions
        ArgumentNullException.ThrowIfNull(endpoints);
        options ??= new ZbHealthEndpointOptions();

+        var responseWriter = options.ResponseWriter ?? ZbHealthWriter.WriteJsonAsync;
+
        var ready = endpoints.MapHealthChecks(options.ReadyPath, new HealthCheckOptions
        {
            Predicate = static c => c.Tags.Contains(ZbHealthTags.Ready),
+            ResponseWriter = responseWriter,
        }).AllowAnonymous();

        endpoints.MapHealthChecks(options.ActivePath, new HealthCheckOptions
        {
            Predicate = static c => c.Tags.Contains(ZbHealthTags.Active),
+            ResponseWriter = responseWriter,
        }).AllowAnonymous();

        // Liveness: run no checks. The endpoint returns 200 as long as the process can respond.
+        // No JSON writer — the empty report would carry no useful data, so the framework default
+        // (a minimal plain-text body) is sufficient.
        endpoints.MapHealthChecks(options.LivePath, new HealthCheckOptions
        {
            Predicate = static _ => false,
@@ -55,4 +63,23 @@ public static class ZbHealthEndpointExtensions

        return ready;
    }
+
+    /// <summary>
+    /// Maps the three health tiers, configuring options inline. See the other
+    /// <see cref="MapZbHealth(IEndpointRouteBuilder, ZbHealthEndpointOptions?)"/> overload for tier semantics.
+    /// </summary>
+    /// <param name="endpoints">The endpoint route builder to map onto.</param>
+    /// <param name="configure">Callback that mutates a fresh <see cref="ZbHealthEndpointOptions"/>.</param>
+    /// <returns>The <see cref="IEndpointConventionBuilder"/> for the readiness endpoint.</returns>
+    public static IEndpointConventionBuilder MapZbHealth(
+        this IEndpointRouteBuilder endpoints,
+        Action<ZbHealthEndpointOptions> configure)
+    {
+        ArgumentNullException.ThrowIfNull(endpoints);
+        ArgumentNullException.ThrowIfNull(configure);
+
+        var options = new ZbHealthEndpointOptions();
+        configure(options);
+        return endpoints.MapZbHealth(options);
+    }
 }
@@ -1,8 +1,11 @@
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+
 namespace ZB.MOM.WW.Health;

 /// <summary>
 /// Options for <see cref="ZbHealthEndpointExtensions.MapZbHealth"/>. Lets callers override the
-/// three tier route paths. The default paths match the ZB.MOM.WW health contract.
+/// three tier route paths and the JSON response writer. The defaults match the ZB.MOM.WW health contract.
 /// </summary>
 public sealed class ZbHealthEndpointOptions
 {
@@ -14,4 +17,11 @@ public sealed class ZbHealthEndpointOptions

    /// <summary>Path for the bare liveness tier (runs no checks; 200 while the process is up).</summary>
    public string LivePath { get; set; } = "/healthz";
+
+    /// <summary>
+    /// Response writer for the readiness and active tiers. Defaults to
+    /// <see cref="ZbHealthWriter.WriteJsonAsync"/> (canonical JSON). The liveness tier runs no checks
+    /// and emits a minimal body, so this writer is not applied to it.
+    /// </summary>
+    public Func<HttpContext, HealthReport, Task>? ResponseWriter { get; set; }
 }
@@ -0,0 +1,75 @@
+using System.Text.Json;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+
+namespace ZB.MOM.WW.Health;
+
+/// <summary>
+/// Canonical JSON response writer for the ZB.MOM.WW health endpoints.
+/// </summary>
+/// <remarks>
+/// Self-contained — it has no runtime dependency on <c>AspNetCore.HealthChecks.UI.Client</c>;
+/// the JSON shape is modelled after that library's <c>UIResponseWriter</c> output but written here
+/// with <see cref="System.Text.Json"/>. The body shape is:
+/// <code>
+/// {
+///   "status": "Healthy|Degraded|Unhealthy",
+///   "totalDurationMs": 12.34,
+///   "entries": {
+///     "&lt;name&gt;": { "status": "...", "description": "...", "durationMs": 1.23 }
+///   }
+/// }
+/// </code>
+/// The HTTP status code is left to the ASP.NET Core health-checks middleware (Healthy/Degraded → 200,
+/// Unhealthy → 503); this writer only renders the body and sets <c>Content-Type: application/json</c>.
+/// </remarks>
+public static class ZbHealthWriter
+{
+    private static readonly JsonSerializerOptions SerializerOptions = new()
+    {
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+    };
+
+    /// <summary>
+    /// Writes <paramref name="report"/> to the response as canonical ZB.MOM.WW health JSON.
+    /// </summary>
+    /// <param name="context">The current HTTP context. Its <see cref="HttpResponse"/> is written to.</param>
+    /// <param name="report">The aggregated health report for the tier that ran.</param>
+    public static Task WriteJsonAsync(HttpContext context, HealthReport report)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+        ArgumentNullException.ThrowIfNull(report);
+
+        context.Response.ContentType = "application/json; charset=utf-8";
+
+        var payload = new HealthReportDto
+        {
+            Status = report.Status.ToString(),
+            TotalDurationMs = report.TotalDuration.TotalMilliseconds,
+            Entries = report.Entries.ToDictionary(
+                static e => e.Key,
+                static e => new HealthEntryDto
+                {
+                    Status = e.Value.Status.ToString(),
+                    Description = e.Value.Description,
+                    DurationMs = e.Value.Duration.TotalMilliseconds,
+                }),
+        };
+
+        return context.Response.WriteAsync(JsonSerializer.Serialize(payload, SerializerOptions));
+    }
+
+    private sealed class HealthReportDto
+    {
+        public string Status { get; init; } = string.Empty;
+        public double TotalDurationMs { get; init; }
+        public Dictionary<string, HealthEntryDto> Entries { get; init; } = new();
+    }
+
+    private sealed class HealthEntryDto
+    {
+        public string Status { get; init; } = string.Empty;
+        public string? Description { get; init; }
+        public double DurationMs { get; init; }
+    }
+}
@@ -0,0 +1,92 @@
+using System.Net;
+using System.Net.Http.Json;
+using System.Text.Json;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.TestHost;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+using Microsoft.Extensions.DependencyInjection;
+using ZB.MOM.WW.Health;
+
+namespace ZB.MOM.WW.Health.Tests;
+
+/// <summary>
+/// Verifies the canonical JSON response writer (<see cref="ZbHealthWriter.WriteJsonAsync"/>):
+/// the JSON body shape, the <c>application/json</c> content type, and that the framework's
+/// status-to-HTTP mapping (Healthy/Degraded → 200, Unhealthy → 503) is preserved when the
+/// writer is wired onto the ready/active tiers by <see cref="ZbHealthEndpointExtensions.MapZbHealth"/>.
+/// </summary>
+public sealed class ResponseWriterTests
+{
+    private sealed class StubHealthCheck : IHealthCheck
+    {
+        private readonly HealthCheckResult _result;
+
+        public StubHealthCheck(HealthStatus status, string? description = null) =>
+            _result = new HealthCheckResult(status, description);
+
+        public Task<HealthCheckResult> CheckHealthAsync(
+            HealthCheckContext context,
+            CancellationToken cancellationToken = default) => Task.FromResult(_result);
+    }
+
+    private static async Task<HttpResponseMessage> GetReadyAsync(
+        HealthStatus status, string description = "db reachable")
+    {
+        var builder = WebApplication.CreateBuilder();
+        builder.WebHost.UseTestServer();
+        builder.Services.AddHealthChecks()
+            .AddCheck("db", new StubHealthCheck(status, description), tags: new[] { ZbHealthTags.Ready });
+
+        await using var app = builder.Build();
+        app.MapZbHealth();
+        await app.StartAsync();
+
+        var client = app.GetTestClient();
+        return await client.GetAsync("/health/ready");
+    }
+
+    [Fact]
+    public async Task ReadyEndpoint_Healthy_WritesJsonBody_With200()
+    {
+        var response = await GetReadyAsync(HealthStatus.Healthy);
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+        Assert.Equal("application/json", response.Content.Headers.ContentType?.MediaType);
+
+        using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
+        var root = doc.RootElement;
+
+        Assert.Equal("Healthy", root.GetProperty("status").GetString());
+        Assert.Equal(JsonValueKind.Number, root.GetProperty("totalDurationMs").ValueKind);
+
+        var entries = root.GetProperty("entries");
+        var db = entries.GetProperty("db");
+        Assert.Equal("Healthy", db.GetProperty("status").GetString());
+        Assert.Equal("db reachable", db.GetProperty("description").GetString());
+    }
+
+    [Fact]
+    public async Task ReadyEndpoint_Degraded_Returns200_WithDegradedStatus()
+    {
+        var response = await GetReadyAsync(HealthStatus.Degraded);
+
+        Assert.Equal(HttpStatusCode.OK, response.StatusCode);
+        Assert.Equal("application/json", response.Content.Headers.ContentType?.MediaType);
+
+        using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
+        Assert.Equal("Degraded", doc.RootElement.GetProperty("status").GetString());
+    }
+
+    [Fact]
+    public async Task ReadyEndpoint_Unhealthy_Returns503_WithUnhealthyStatus()
+    {
+        var response = await GetReadyAsync(HealthStatus.Unhealthy);
+
+        Assert.Equal(HttpStatusCode.ServiceUnavailable, response.StatusCode);
+        Assert.Equal("application/json", response.Content.Headers.ContentType?.MediaType);
+
+        using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
+        Assert.Equal("Unhealthy", doc.RootElement.GetProperty("status").GetString());
+    }
+}