Files

T

Joseph Doherty 6a4fa220de docs(health): oldest-Up-member is the active-node rule (0.3.0)

Rewrites the active-node sections of the spec and shared contract, which
described the leader-based design that both consumers rejected.

- SPEC §2.3 replaced: the rule, the ordered RolePreference, why a node holding
  none of the preferred roles is Unhealthy rather than Healthy, and the data
  payload. §4 (IActiveNodeGate) and the tier table follow.
- SPEC §6 marked historical: it still tells adopters to use
  ActiveNodeHealthCheck(role: "admin") and AkkaActiveNodeGate, which is the
  advice that produced the defect. Kept for provenance, annotated so nobody
  follows it again.
- GAPS: gaps L1/L2 recorded as closed the wrong way, reopened, then closed at
  0.3.0 — including the part worth remembering, that both apps adopted the
  shared check as specified, hit it live, and reverted to private copies, so the
  surface reached zero consumers by being avoided rather than unused.
- Index rows updated with the consumer-visible changes and both app branches.

2026-07-24 13:24:30 -04:00

current-state

docs(health): resolve spec/contract/gaps consistency (review fixes)

2026-06-01 06:33:42 -04:00

shared-contract

docs(health): oldest-Up-member is the active-node rule (0.3.0)

2026-07-24 13:24:30 -04:00

spec

docs(health): oldest-Up-member is the active-node rule (0.3.0)

2026-07-24 13:24:30 -04:00

GAPS.md

docs(health): oldest-Up-member is the active-node rule (0.3.0)

2026-07-24 13:24:30 -04:00

README.md

feat(health): pack ZB.MOM.WW.Health 0.1.0 + README + register health component in indexes

2026-06-01 07:09:14 -04:00

README.md

Health (readiness / liveness / active-node)

Second normalized component under the operability cluster. Goal: path to shared code — converge the three sister projects onto a common three-tier health endpoint convention and a set of shared probe implementations, proposed as the ZB.MOM.WW.Health library set (3 packages), while each project keeps its own probe registration and orchestrator wiring.

The one target: spec/SPEC.md
The proposed shared library: shared-contract/ZB.MOM.WW.Health.md
Divergences + backlog: GAPS.md
Current state, per project: current-state/

Why health is a strong normalization candidate

Both OtOpcUa and ScadaBridge trace their health-check structure to the same "ScadaLink three-tier pattern" (HealthEndpoints.cs:13 says so explicitly) but have already diverged in probe logic, status semantics, response writer, and endpoint registration style. MxAccessGateway has no shared ancestry here — it has a single hardcoded /health/live endpoint with no real probes at all. The common core (three tiers, database probe, Akka cluster probe, active-node probe) is re-implemented twice and absent once. Shared probe implementations with configurable policies close the gap without forcing identical behavior onto projects with legitimately different cluster semantics.

Status by project

Project	Endpoints today	Probes today	Response writer	`/healthz`	`IActiveNodeGate`	Adoption status
OtOpcUa	`/health/ready`, `/health/active`, `/healthz`	Database (query), AkkaCluster (2-way), AdminRoleLeader (role-filtered)	Default (plain-text/JSON)	✅ present	—	Not started
MxAccessGateway	`/health/live` only (raw `MapGet`; hardcoded `"Healthy"`)	None (`AddHealthChecks()` called but unused)	Bespoke `GatewayHealthReply` JSON	⛔ absent	—	Not started
ScadaBridge	`/health/ready`, `/health/active`	Database (`CanConnectAsync`), AkkaCluster (3-way), ActiveNode (role-less)	`HealthChecks.UI.Client` JSON	⛔ absent	`ActiveNodeGate` (backs Inbound API 503 gate)	Not started

See each project's current-state/<project>/CURRENT-STATE.md for the code-verified detail and its adoption plan.

Normalized vs. left per-project

Normalized (the shared target):

Three-tier endpoint convention: /health/ready (tag ready), /health/active (tag active), /healthz (bare liveness). Mapped by app.MapZbHealth() from ZB.MOM.WW.Health.
Canonical JSON response writer (lifted from HealthChecks.UI.Client style; no per-project writer wiring needed).
IActiveNodeGate seam — generalized from ScadaBridge's ActiveNodeGate; wired into MapZbHealth for automatic active-tier response.
GrpcDependencyHealthCheck — reachability probe for a downstream gRPC dependency (covers OtOpcUa → MxAccessGateway channel and MxAccessGateway → worker IPC).
AkkaClusterHealthCheck (in ZB.MOM.WW.Health.Akka) with a configurable status policy. Default = ScadaBridge's three-way policy; OtOpcUaCompat preset preserves OtOpcUa's two-way self-Up-among-members scan.
ActiveNodeHealthCheck (in ZB.MOM.WW.Health.Akka) with an optional role filter. Role-less = ScadaBridge's behavior (Up + cluster leader); role-filtered = OtOpcUa's AdminRoleLeader behavior.
DatabaseHealthCheck<TContext> (in ZB.MOM.WW.Health.EntityFrameworkCore) with default CanConnectAsync and an optional ProbeQuery delegate.
AllowAnonymous on all three tiers by default (consistent across all three projects today).

Left per-project (not forced together):

Which probes each app registers, their names, and which tags they carry.
Orchestrator / Traefik wiring (sidecars, route rules, upstreams).
ScadaBridge's HealthMonitoring/ distributed aggregation pipeline (SiteHealthCollector, CentralHealthAggregator, HealthReportSender, etc.) — domain-specific, no shared-library equivalent.
MxAccessGateway's GatewayHealthReply metadata (DefaultBackend, WorkerProtocolVersion) — keep as a bespoke /info endpoint.
The x86 worker process — out of process and out of scope; the gateway-side GrpcDependencyHealthCheck observes it indirectly.

Package structure

ZB.MOM.WW.Health ships as three dependency-split packages:

Package	Contents	Consumers
`ZB.MOM.WW.Health`	Core tiers, `MapZbHealth`, canonical writer, `IActiveNodeGate`, `GrpcDependencyHealthCheck`	All three
`ZB.MOM.WW.Health.Akka`	`AkkaClusterHealthCheck` + status presets, `ActiveNodeHealthCheck` + role filter	OtOpcUa, ScadaBridge
`ZB.MOM.WW.Health.EntityFrameworkCore`	`DatabaseHealthCheck<TContext>` + optional probe delegate	OtOpcUa, ScadaBridge

MxAccessGateway consumes the core package only (no Akka, no EF). OtOpcUa and ScadaBridge consume all three.

Component status

Status: Draft — library built at 0.1.0. Spec and shared-contract written; current-state docs verified; GAPS backlog populated. Library implemented and packed at ../../ZB.MOM.WW.Health/ (3 packages, 58 tests; ZB.MOM.WW.Health, ZB.MOM.WW.Health.Akka, ZB.MOM.WW.Health.EntityFrameworkCore). Adoption by the three apps is the next follow-on tracked in GAPS.md.