docs(code-reviews): review Secrets, LocalDb, GalaxyRepository, Overview; re-review changed libs (scadaproj#15)

First reviews of Secrets, LocalDb, GalaxyRepository and Overview, and
2026-11-09 re-reviews of Auth, Health, Theme, Telemetry, Audit and
Configuration, all at 91fb2b4. 49 new open findings, each with a P1/P2/P3
priority and a failure scenario: 1 P1, 13 P2, 35 P3. README regenerated;
REVIEW-PROCESS, template and regen script now cover all ten libraries and
the Priority field.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 14:33:14 -05:00
parent 91fb2b48dd
commit 477245f5db
14 changed files with 2602 additions and 52 deletions
+92 -5
View File
@@ -7,14 +7,36 @@
| Component spec | `components/health/spec/SPEC.md` |
| Shared contract | `components/health/shared-contract/ZB.MOM.WW.Health.md` |
| Status | Reviewed |
| Last reviewed | 2026-06-01 |
| Reviewer | Claude (automated baseline) |
| Commit reviewed | `5f75cd4` |
| Open findings | 0 |
| Last reviewed | 2026-11-09 (re-review; baseline 2026-06-01 at `5f75cd4`) |
| Reviewer | Claude (2026-11-09 re-review, scadaproj#15; baseline: Claude automated) |
| Commit reviewed | `91fb2b4` |
| Open findings | 1 |
## Summary
The library is small, cohesive, and well-documented, and it tracks the normalized spec closely:
**2026-11-09 re-review (`91fb2b4`, scadaproj#15).** Re-reviewed at `91fb2b4` (2026-11-09) against the 2026-06-01 baseline `5f75cd4`; the library is now
`0.3.0`. The headline change, the active tier now meaning "oldest `Up` member" through the new
`ClusterActiveNode` helper instead of `Leader`/`RoleLeader`, is correct. Only `MemberStatus.Up` members
are eligible, so `Joining`, `WeaklyUp`, `Leaving`, `Exiting`, `Down` and `Removed` are all excluded. Ties
fall through to Akka's `Member.IsOlderThan`, which breaks an equal up-number on address ordering, so the
choice is deterministic. Self-identity is compared on `UniqueAddress`, so a restarted incarnation on the
same host and port is never mistaken for the old one. An `Up`-but-unreachable oldest member is still
named active, which matches singleton placement until the split-brain resolver downs it. A role-scoped
node that carries none of the preferred roles answers `NoActiveRoleStatus` (default Unhealthy, i.e. 503).
Both startup-safety paths (no `ActorSystem`, cluster not yet accessible) still return Degraded (200), and
a container-built `AddCheck<ActiveNodeHealthCheck>` probe confirmed that `ActivatorUtilities` picks the
right constructor out of the three. The status mapping, the `data` JSON shape (emitted only when the
check supplies data, `description` always present) and the composite convention builder are correct.
All 76 tests pass (Health.Tests 25, Health.Akka.Tests 45, Health.EntityFrameworkCore.Tests 6).
`ClusterActiveNodeTests` runs a real two-node cluster whose age order and address order diverge, and
covers role scoping, role preference and the gate. The non-`Up` exclusions (`Leaving`/`WeaklyUp`/
`Joining`) and the restart-incarnation `UniqueAddress` comparison are verified by reading the code only:
no test exercises them. That is a test gap, not a defect. There is one new Low finding: the `AkkaActiveNodeGate` can only be scoped to a
single role, while the probe takes an ordered role-preference list. So the documented "gate and probe
can never disagree" guarantee does not hold for the fused-node configuration that OtOpcUa actually runs
(Health-007). It is latent, because no family app uses `AkkaActiveNodeGate` today.
**2026-06-01 baseline (`5f75cd4`).** The library is small, cohesive, and well-documented, and it tracks the normalized spec closely:
the three-tier endpoint convention, the canonical JSON writer, the `IActiveNodeGate` seam, the
configurable `AkkaClusterStatusPolicy` presets, and the role-filtered `ActiveNodeHealthCheck` all
match the contract. The package split is clean — Akka and EF Core stay out of the core package, so
@@ -36,6 +58,23 @@ and missing `GenerateDocumentationFile` so the (otherwise excellent) XML docs do
## Checklist coverage
2026-11-09 re-review at `91fb2b4`:
| # | Category | Examined | Notes |
|---|----------|----------|-------|
| 1 | Correctness & logic bugs | ☑ | `OldestUpMember`/`SelfIsActive`/`ResolveActiveRole` are correct for ties, non-Up states, role scoping, the no-Up-member case (Unhealthy) and restart incarnations (`UniqueAddress`). Gate/probe scope mismatch → Health-007. |
| 2 | Public API surface & compatibility | ☑ | 0.3.0 is a deliberate, documented behaviour break (standby 503, role-lacking node Unhealthy). `ActiveNodeDecision` was removed but was internal. New public `ClusterActiveNode` and `ActiveNodeHealthCheckOptions` are sealed/static and nullable-correct. The gate offers a single `role` where the probe offers `RolePreference` → Health-007. |
| 3 | Concurrency & thread safety | ☑ | Checks and gate hold no mutable state. Membership is read from a single `ClusterReadView` snapshot per call. No issues found. |
| 4 | Error handling & resilience | ☑ | Health-001/002 fixes hold: cluster access is wrapped and maps to Degraded (OCE excluded); the gate swallows to `false`. No issues found. |
| 5 | Security & secret handling | ☑ | Endpoints are anonymous by design. The `data` payload carries node addresses, roles and counts only. No issues found. |
| 6 | Performance & resource management | ☑ | One linear member scan per probe. No allocations of note and nothing disposable. No issues found. |
| 7 | Spec & shared-contract adherence | ☑ | Three tiers, status strings and JSON envelope match SPEC §3. The oldest-Up rule matches both Akka apps (OtOpcUa `RedundancyStateActor` and ScadaBridge `ActiveNodeEvaluator` delegate to it). No issues found. |
| 8 | Packaging, dependencies & project layout | ☑ | Version 0.3.0; Akka stays out of the core package. The NU1510 warning (explicit `HealthChecks.Abstractions` reference is now prunable) is cosmetic. No issues found. |
| 9 | Testing coverage | ☑ | 76 tests pass, including real-cluster `ClusterActiveNodeTests` (age order diverging from address order), startup safety, role resolution and the `data` writer shape. Untested: the `Leaving`/`WeaklyUp`/`Joining` exclusion and same-address restart incarnations (correct by code reading). A container-built `AddCheck<ActiveNodeHealthCheck>` was probed in the scratchpad and resolves correctly (Degraded with no ActorSystem). |
| 10 | Documentation & XML docs | ☑ | Thorough and accurate, apart from the gate's "can never disagree" claim (Health-007). |
<details><summary>2026-06-01 baseline checklist (<code>5f75cd4</code>)</summary>
| # | Category | Examined | Notes |
|---|----------|----------|-------|
| 1 | Correctness & logic bugs | ☑ | Tier predicates, policy presets, and `ActiveNodeDecision` matrices are correct and match the spec tables. No logic defects found. |
@@ -49,6 +88,8 @@ and missing `GenerateDocumentationFile` so the (otherwise excellent) XML docs do
| 9 | Testing coverage | ☑ | Strong: TestServer tier tests, real SQLite EF tests, table-driven policy/decision tests, gRPC probe + timeout + cancellation. Gaps noted inline in findings, not raised separately. |
| 10 | Documentation & XML docs | ☑ | Health-004, Health-006. Public API XML docs are thorough and accurate; the issues are recommended-tag drift and docs not being packed. |
</details>
## Findings
### Health-001 — Akka health checks throw (instead of returning Degraded) when cluster state is inaccessible
@@ -253,3 +294,49 @@ CS1591 warnings surface on currently-undocumented members.
**Resolution**
Resolved in `544a6dd`, 2026-06-01 — set `<GenerateDocumentationFile>true</GenerateDocumentationFile>` (plus `NoWarn=CS1591` for test/non-packed members) in `Directory.Build.props`; verified `dotnet pack -c Release` now ships `lib/net10.0/*.xml` in all three nupkgs.
<!-- 2026-11-09 re-review (scadaproj#15) findings below. -->
### Health-007 — `AkkaActiveNodeGate` cannot express the probe's `RolePreference`, so gate and `/health/active` can disagree despite the documented guarantee
| | |
|--|--|
| Severity | Low |
| Priority | P3 |
| Category | Public API surface & compatibility |
| Status | Open |
| Location | `ZB.MOM.WW.Health/src/ZB.MOM.WW.Health.Akka/AkkaActiveNodeGate.cs:46` (ctor `string? role`), `:14-17` (doc claim), vs `ZB.MOM.WW.Health/src/ZB.MOM.WW.Health.Akka/ActiveNodeHealthCheck.cs:114-115` |
**Description**
In 0.3.0 `ActiveNodeHealthCheck` resolves its scope from an ordered `RolePreference` list through
`ClusterActiveNode.ResolveActiveRole(self.Roles, …)`, so a fused node answers for `admin` and a
driver-only node answers for `driver`. `AkkaActiveNodeGate` accepts only a single fixed `string? role`
and calls `ClusterActiveNode.SelfIsActive(cluster, _role)` directly. Its XML remarks still promise that
"an endpoint gated by this type and the `/health/active` probe an orchestrator routes by can never
disagree about which node is in charge". That holds only when the probe is configured with zero or one
role. For the multi-role preference (the exact configuration OtOpcUa's `HealthEndpoints` uses,
`[admin, driver]`) no gate configuration matches the probe on every node.
**Failure scenario**
An app wires `/health/active` with `RolePreference = ["admin","driver"]` and gates its
`RequireActiveNode()` endpoints with `new AkkaActiveNodeGate(sp, "admin")`. On a driver-only pair, the
oldest `driver` member answers `/health/active` 200, so the load balancer routes traffic to it. The gate
evaluates the `admin` scope: the node has no `admin` role, so `SelfIsActive` returns false and every
gated request gets 503 from `ActiveNodeGateEndpointFilter`. The pair serves nothing. Using
`new AkkaActiveNodeGate(sp)` (unscoped) instead makes the gate follow the oldest member of the whole
mesh, which on a mixed mesh can be a different node from the probe's role-scoped answer. Today this is
latent: no family app constructs `AkkaActiveNodeGate`, because ScadaBridge and OtOpcUa use their own
evaluators over `ClusterActiveNode`.
**Recommendation**
Give `AkkaActiveNodeGate` an `ActiveNodeHealthCheckOptions` constructor, or factor the "resolve role,
then `SelfIsActive`" step into one shared `ClusterActiveNode` method that both the probe and the gate
call, so they share one scope definition. Until then, qualify the remarks: the guarantee holds only when
both are configured with the same single role or both unscoped.
**Resolution**
_Unresolved._