Fix all baseline code-review findings across the six shared libraries

Resolves the 35 findings from the 2026-06-01 baseline (commit 26ba1c7), test-first for every behavioral change. +51 tests (331 -> 382 passing, 0 failed). - Telemetry-001 (HIGH): RedactionEnricher now honours property removal, so a redactor that drops a key actually scrubs the secret from the event. - Auth: LDAP validator ValidateOnStart; API-key verify no longer fails on a best-effort MarkUsed write or a corrupt scopes column (fail-closed); LDAP cert validation hook; KeyPrefix persistence aligned; README algorithm corrected. - Health: Akka checks return Degraded (not throw) when the cluster isn't up yet; GrpcDependencyHealthCheck catch-all; null 'description' rendered; composite endpoint builder; XML docs shipped. - Audit: CompositeAuditWriter no longer re-throws OperationCanceledException; TruncatingAuditRedactor over-redact scrubs Target + safe negative max; options record; XML docs shipped. - Configuration: TryAddEnumerable idempotent registration; consistent port quoting; strict invariant port parsing; XML docs + README packaged. - Theme: mobile toggle is now CSS-only (no Bootstrap JS); token/CSS hygiene; XML docs on the public parameter surface. Shared-contract/spec docs updated where the code was the source of truth (observability service.instance.id, MapZbMetrics, redactor reach). All changes additive/back-compatible at v0.1.0. code-reviews bookkeeping follows separately.
2026-06-01 11:22:14 -04:00
parent 26ba1c7215
commit 544a6ddb77
72 changed files with 1539 additions and 191 deletions
@@ -103,27 +103,41 @@ public sealed class ActiveNodeHealthCheck : IHealthCheck
        if (system is null)
            return Task.FromResult(HealthCheckResult.Degraded("ActorSystem not yet available."));

-        var cluster = Cluster.Get(system);
-        var self = cluster.SelfMember;
-        var selfUp = self.Status == MemberStatus.Up;
-
+        MemberStatus selfStatus;
+        bool selfUp;
        bool hasRole;
        bool isLeader;
-        if (_role is null)
+        try
        {
-            hasRole = false;
-            var leader = cluster.State.Leader;
-            isLeader = leader is not null && leader == self.Address;
+            // Reading cluster membership can throw while the ActorSystem exists but the cluster has
+            // not finished initialising (e.g. Akka.Cluster not yet configured →
+            // ConfigurationException). The spec's startup-safety rule maps this to Degraded rather
+            // than letting the exception escape (which the host would record as Unhealthy).
+            var cluster = Cluster.Get(system);
+            var self = cluster.SelfMember;
+            selfStatus = self.Status;
+            selfUp = selfStatus == MemberStatus.Up;
+
+            if (_role is null)
+            {
+                hasRole = false;
+                var leader = cluster.State.Leader;
+                isLeader = leader is not null && leader == self.Address;
+            }
+            else
+            {
+                hasRole = self.HasRole(_role);
+                var roleLeader = cluster.State.RoleLeader(_role);
+                isLeader = roleLeader is not null && roleLeader == self.Address;
+            }
        }
-        else
+        catch (Exception ex) when (ex is not OperationCanceledException)
        {
-            hasRole = self.HasRole(_role);
-            var roleLeader = cluster.State.RoleLeader(_role);
-            isLeader = roleLeader is not null && roleLeader == self.Address;
+            return Task.FromResult(HealthCheckResult.Degraded("Akka cluster state not yet accessible.", ex));
        }

        var health = ActiveNodeDecision.Evaluate(selfUp, isLeader, hasRole, _role);
-        var description = DescribeResult(health, self.Status, selfUp, isLeader);
+        var description = DescribeResult(health, selfStatus, selfUp, isLeader);
        var result = health switch
        {
            HealthStatus.Healthy   => HealthCheckResult.Healthy(description),
@@ -8,7 +8,8 @@ namespace ZB.MOM.WW.Health.Akka;
 /// <summary>
 /// Health check that maps the local node's Akka cluster membership status to a
 /// <see cref="HealthStatus"/> through a configurable <see cref="AkkaClusterStatusPolicy"/>.
-/// Register to the <see cref="ZbHealthTags.Ready"/> tag (recommended <c>[ready, active]</c>).
+/// Register to the <see cref="ZbHealthTags.Ready"/> tag only — cluster membership is a readiness
+/// concern; the <see cref="ZbHealthTags.Active"/> tier is reserved for the leader / active-node probe.
 /// </summary>
 /// <remarks>
 /// The <see cref="ActorSystem"/> is resolved lazily from the service provider. If it is not yet
@@ -42,7 +43,21 @@ public sealed class AkkaClusterHealthCheck : IHealthCheck
        if (system is null)
            return Task.FromResult(HealthCheckResult.Degraded("ActorSystem not yet available."));

-        var status = Cluster.Get(system).SelfMember.Status;
+        MemberStatus status;
+        try
+        {
+            // Cluster.Get(system).SelfMember can throw while the ActorSystem exists but the cluster
+            // has not finished initialising (e.g. Akka.Cluster not yet configured →
+            // ConfigurationException). The spec's startup-safety rule maps this to Degraded, not an
+            // escaping exception (which the host would record as Unhealthy and pull the node from
+            // rotation).
+            status = Cluster.Get(system).SelfMember.Status;
+        }
+        catch (Exception ex) when (ex is not OperationCanceledException)
+        {
+            return Task.FromResult(HealthCheckResult.Degraded("Akka cluster state not yet accessible.", ex));
+        }
+
        var health = _policy.Evaluate(status);
        var description = $"Akka cluster member status: {status}";
        var result = health switch
@@ -13,14 +13,15 @@ namespace ZB.MOM.WW.Health;
 /// The probe is injectable via <see cref="GrpcDependencyOptions.Probe"/>; the default drives the
 /// channel to a connected state with <see cref="GrpcChannel.ConnectAsync"/>. The result is
 /// <see cref="HealthStatus.Healthy"/> when the probe returns <c>true</c>, and
-/// <see cref="HealthStatus.Unhealthy"/> when it returns <c>false</c>, throws an
-/// <see cref="RpcException"/>, or times out / is cancelled within
-/// <see cref="GrpcDependencyOptions.Timeout"/>.
+/// <see cref="HealthStatus.Unhealthy"/> when it returns <c>false</c>, throws any exception
+/// (<see cref="RpcException"/> or otherwise), or times out within
+/// <see cref="GrpcDependencyOptions.Timeout"/>. External cancellation of the supplied
+/// <see cref="CancellationToken"/> propagates as an <see cref="OperationCanceledException"/>.
 /// </para>
 /// <para>
-/// Recommended registration tags: <see cref="ZbHealthTags.Ready"/> and
-/// <see cref="ZbHealthTags.Active"/> — a missing downstream gRPC dependency makes the node both
-/// not-ready and not-able-to-act. The registrant applies the tags.
+/// Recommended registration tag: <see cref="ZbHealthTags.Ready"/> only — downstream gRPC
+/// reachability is a readiness concern; the <see cref="ZbHealthTags.Active"/> tier is reserved for
+/// the leader / active-node probe. The registrant applies the tag.
 /// </para>
 /// </remarks>
 public sealed class GrpcDependencyHealthCheck : IHealthCheck
@@ -74,6 +75,15 @@ public sealed class GrpcDependencyHealthCheck : IHealthCheck
        {
            return HealthCheckResult.Unhealthy($"{name} probe timed out after {_options.Timeout}.", ex);
        }
+        catch (Exception ex)
+        {
+            // Catch-all to match the sibling DatabaseHealthCheck: any other probe error
+            // (e.g. InvalidOperationException / HttpRequestException / SocketException from the
+            // transport, or anything a custom probe throws) maps to Unhealthy rather than escaping
+            // the IHealthCheck boundary. The OCE/Rpc external-cancellation handlers above run first,
+            // so caller cancellation still propagates.
+            return HealthCheckResult.Unhealthy($"{name} probe failed: {ex.Message}", ex);
+        }
    }

    /// <summary>
@@ -28,9 +28,9 @@ public static class ZbHealthEndpointExtensions
    /// emits a minimal <c>200 OK</c> body.
    /// </remarks>
    /// <returns>
-    /// The <see cref="IEndpointConventionBuilder"/> for the readiness (<c>/health/ready</c>) endpoint.
-    /// A single tier is returned (rather than a composite) to keep the API simple; conventions
-    /// applied to the result affect only the readiness endpoint.
+    /// A composite <see cref="IEndpointConventionBuilder"/> that fans every chained convention out to
+    /// <em>all three</em> health endpoints (readiness, active, and liveness). For example,
+    /// <c>endpoints.MapZbHealth().RequireHost("…")</c> gates all three endpoints, as a caller expects.
    /// </returns>
    public static IEndpointConventionBuilder MapZbHealth(
        this IEndpointRouteBuilder endpoints,
@@ -47,7 +47,7 @@ public static class ZbHealthEndpointExtensions
            ResponseWriter = responseWriter,
        }).AllowAnonymous();

-        endpoints.MapHealthChecks(options.ActivePath, new HealthCheckOptions
+        var active = endpoints.MapHealthChecks(options.ActivePath, new HealthCheckOptions
        {
            Predicate = static c => c.Tags.Contains(ZbHealthTags.Active),
            ResponseWriter = responseWriter,
@@ -56,12 +56,38 @@ public static class ZbHealthEndpointExtensions
        // 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
+        var live = endpoints.MapHealthChecks(options.LivePath, new HealthCheckOptions
        {
            Predicate = static _ => false,
        }).AllowAnonymous();

-        return ready;
+        return new CompositeEndpointConventionBuilder(ready, active, live);
+    }
+
+    /// <summary>
+    /// An <see cref="IEndpointConventionBuilder"/> that forwards each convention to several
+    /// underlying builders, so conventions chained onto the result of
+    /// <see cref="MapZbHealth(IEndpointRouteBuilder, ZbHealthEndpointOptions?)"/> apply to all three
+    /// health endpoints rather than just one.
+    /// </summary>
+    private sealed class CompositeEndpointConventionBuilder : IEndpointConventionBuilder
+    {
+        private readonly IEndpointConventionBuilder[] _builders;
+
+        public CompositeEndpointConventionBuilder(params IEndpointConventionBuilder[] builders) =>
+            _builders = builders;
+
+        public void Add(Action<EndpointBuilder> convention)
+        {
+            foreach (var builder in _builders)
+                builder.Add(convention);
+        }
+
+        public void Finally(Action<EndpointBuilder> finalConvention)
+        {
+            foreach (var builder in _builders)
+                builder.Finally(finalConvention);
+        }
    }

    /// <summary>
@@ -70,7 +96,10 @@ public static class ZbHealthEndpointExtensions
    /// </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>
+    /// <returns>
+    /// A composite <see cref="IEndpointConventionBuilder"/> that fans chained conventions out to all
+    /// three health endpoints.
+    /// </returns>
    public static IEndpointConventionBuilder MapZbHealth(
        this IEndpointRouteBuilder endpoints,
        Action<ZbHealthEndpointOptions> configure)
@@ -1,5 +1,4 @@
 using System.Text.Json;
-using System.Text.Json.Serialization;
 using Microsoft.AspNetCore.Http;
 using Microsoft.Extensions.Diagnostics.HealthChecks;

@@ -21,15 +20,21 @@ namespace ZB.MOM.WW.Health;
 ///   }
 /// }
 /// </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>.
+/// The <c>description</c> key is always present; when a check supplies no description it is emitted
+/// as JSON <c>null</c> (not omitted), matching the spec example and the <c>HealthChecks.UI.Client</c>
+/// shape. 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
 {
+    // Null properties are emitted (not omitted) so a null `description` renders as
+    // "description": null — matching the SPEC §3 example and the HealthChecks.UI.Client shape this
+    // writer mirrors. Consumers can then read entries.<name>.description without handling a missing
+    // property. (Do not set DefaultIgnoreCondition = WhenWritingNull here.)
    private static readonly JsonSerializerOptions SerializerOptions = new()
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
-        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
    };

    /// <summary>