feat(health): canonical JSON health response writer

ZB.MOM.WW.Health/src/ZB.MOM.WW.Health/ZbHealthEndpointExtensions.cs

@@ -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);
+    }
 }

ZB.MOM.WW.Health/src/ZB.MOM.WW.Health/ZbHealthEndpointOptions.cs

@@ -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; }
 }

ZB.MOM.WW.Health/src/ZB.MOM.WW.Health/ZbHealthResponseWriter.cs

@@ -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; }
+    }
+}