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:
@@ -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._
|
||||
|
||||
Reference in New Issue
Block a user