scadaproj/docs/plans/2026-06-01-deploy-zb-configuration-design.md

# Design: Deploy `ZB.MOM.WW.Configuration` fleet-wide

**Date:** 2026-06-01
**Status:** Approved — ready for implementation planning (writing-plans).
**Scope:** Adopt the shared `ZB.MOM.WW.Configuration` library into all three sister apps
(OtOpcUa, MxAccessGateway, ScadaBridge).

> Every state claim below was **code-verified on 2026-06-01**, not taken from the
> `components/*/GAPS.md` prose — those docs proved unreliable in both directions (they
> claimed Health was un-adopted when it is fully adopted, and claimed Telemetry was
> adopted before it was). See memory `component-status-claims-are-optimistic`.

---

## 0. Why this module

Verified fleet-wide adoption state (real `PackageReference` + usage scan of the three
sister-app `src/` trees, plus Gitea-feed `curl`):

| Module | OtOpcUa | MxAccessGateway | ScadaBridge | Status |
|---|---|---|---|---|
| Health | ✅ | ✅ | ✅ | already deployed fleet-wide |
| Telemetry (observability) | ✅ | ✅ | ✅ | already deployed fleet-wide |
| **Configuration** | — | — | — | **chosen: not adopted anywhere** |
| Auth | — | — | — | not adopted |
| UI Theme | — | — | — | not adopted |
| Audit | — | — | — | not adopted |

Configuration was chosen as the next fleet-wide adoption because it is the same
cross-cutting-infra flavour as the already-done Health + Telemetry, it is the
lowest-risk (behaviour-preserving for the two heavy consumers), and it still delivers
real new value (OtOpcUa gains fail-fast startup validation it lacks entirely today).

### Decisions locked during brainstorming
- **Module:** Configuration.
- **OtOpcUa depth:** add **real** validators (net-new `Ldap`/`OpcUa` startup validation),
  not just a package reference.
- **Rollout:** per-repo **sequential**, increasing risk order: Foundation → MxGateway →
  OtOpcUa → ScadaBridge; each repo on its own branch, verified green before the next.
- **ScadaBridge `StartupValidator` → `ConfigPreflight`:** included in this pass.

---

## 1. Goal & scope

Move the config-validation **plumbing** (failure accumulation, the bind+validate+
`ValidateOnStart` triple, the pre-host raw-config aggregator) into the shared library so
it is written once; leave every **domain rule and failure message** per-project.

**Out of scope:**
- OtOpcUa's `DraftValidator` / `sp_ValidateDraft` — domain *content* validation over
  database draft rows, dormant in `src/`, not the host-config concern this library owns.
- Any change to rule wording or validation semantics (behaviour-preserving except the
  *additive* OtOpcUa validators).

---

## 2. The contract being adopted (verified public API)

From `ZB.MOM.WW.Configuration/src/ZB.MOM.WW.Configuration/`:

- **`OptionsValidatorBase<TOptions>`** — abstract `IValidateOptions<TOptions>`. Override
  `protected abstract void Validate(ValidationBuilder, TOptions)`; the base creates the
  builder, runs the override, and returns `Success` only when no failures were recorded
  (else `Fail(builder.Failures)`).
- **`ValidationBuilder`** — rule primitives `Required`, `Port`, `HostPort`,
  `PositiveTimeSpan`, `OneOf`, `MinCount`, plus `RequireThat(bool, message)` and
  `Add(message)` for custom / cross-field rules. `Failures` / `IsValid` expose state.
- **`ServiceCollectionExtensions.AddValidatedOptions<TOptions, TValidator>(config, sectionPath)`**
  — `TryAddEnumerable` the validator (singleton) + `AddOptions().Bind(section).ValidateOnStart()`
  in one call; returns the `OptionsBuilder` for chaining.
- **`ConfigPreflight.For(IConfiguration)`** — fluent pre-host checker for raw config
  before the DI container exists: `RequireValue(key)`, `RequirePort(key)`,
  `Require(key, predicate, reason)`, `When(condition, block)`, terminating in
  `ThrowIfInvalid()` (throws `InvalidOperationException` listing all failures).

Library health: `dotnet test` → **42 passed, 0 failed** (the `CLAUDE.md` "27 tests" line
is stale-low; the suite passes regardless).

---

## 3. Foundation phase (must land before any repo adopts)

This is the part the status docs hide. Verified 2026-06-01:

1. **Pack + push the package.** `ZB.MOM.WW.Configuration` is **404 on the Gitea feed**
   (`registration/zb.mom.ww.configuration/index.json`), while the known-adopted Health
   package returns 200. `dotnet pack -c Release` then push the `.nupkg` to
   `https://gitea.dohertylan.com/api/packages/dohertj2/nuget`.
2. **Per-app feed wiring** (all three `nuget.config` files): the `dohertj2-gitea`
   `packageSourceMapping` currently routes only `ZB.MOM.WW.MxGateway.*`,
   `ZB.MOM.WW.Health*`, `ZB.MOM.WW.Telemetry*`. Add
   `<package pattern="ZB.MOM.WW.Configuration" />`. Without this, restore fails even with
   the package on the feed.
3. **Central version pin** in each app's `Directory.Packages.props`:
   `<PackageVersion Include="ZB.MOM.WW.Configuration" Version="0.1.0" />`.
4. **Verify gate:** `curl` the registration index → **200** before any repo work begins.

---

## 4. Per-repo adoption (sequential)

Each repo: branch `feat/adopt-zb-configuration`, `PackageReference` (no version — central
package management), migrate, `dotnet build` + `dotnet test` green, then move on.

### Repo 1 — MxAccessGateway (medium; pure refactor)
- `PackageReference Include="ZB.MOM.WW.Configuration"` in
  `src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj`.
- `GatewayOptionsValidator : IValidateOptions<GatewayOptions>` →
  `: OptionsValidatorBase<GatewayOptions>`. Drop the private `List<string>` and the
  `Count == 0 ? Success : Fail` tail (now the base's job). Map private helpers:
  `AddIfBlank` → `Required`; `AddIfNotPositive` / `AddIfNegative` → `RequireThat(... , msg)`.
  Keep `AddIfInvalidPath`, the `.exe`-extension rule, the cross-field
  `HeartbeatGraceSeconds >= HeartbeatIntervalSeconds`, range checks, and all nine
  sub-validators as `RequireThat`/`Add` custom rules. **Every message string unchanged.**
- `AddGatewayConfiguration`'s `AddOptions().BindConfiguration(SectionName).ValidateOnStart()`
  + `AddSingleton<IValidateOptions<GatewayOptions>, GatewayOptionsValidator>()` →
  `services.AddValidatedOptions<GatewayOptions, GatewayOptionsValidator>(config, GatewayOptions.SectionName)`.
  Keep the separate `IGatewayConfigurationProvider` registration.

### Repo 2 — OtOpcUa (lightest base, but net-new validation added)
- `PackageReference` in
  `src/Server/ZB.MOM.WW.OtOpcUa.Host/ZB.MOM.WW.OtOpcUa.Host.csproj`.
- New `LdapOptionsValidator : OptionsValidatorBase<LdapOptions>`
  (`LdapOptions` lives in `ZB.MOM.WW.OtOpcUa.Security/Ldap/`): `Required` on Server /
  SearchBase (and other not-optional fields). `Program.cs:99`
  `AddOptions<LdapOptions>().Bind(GetSection("Ldap"))` →
  `AddValidatedOptions<LdapOptions, LdapOptionsValidator>(config, "Ldap")`.
- New validator for the `OpcUa` section; replace the imperative
  `GetSection("OpcUa").Bind(options)` at `OtOpcUaServerHostedService.cs:63` with validated
  options resolved from DI. Exact rule list finalized in the implementation plan from the
  real `OpcUaOptions` fields (ports → `Port`, endpoints → `HostPort`, required strings →
  `Required`, durations → `PositiveTimeSpan`).
- New unit tests for both validators (valid config passes; each missing/invalid field
  produces its message).

### Repo 3 — ScadaBridge (heaviest; refactor + preflight)
- `PackageReference` in `src/ZB.MOM.WW.ScadaBridge.Host/...csproj` and the module projects
  that own validators (ClusterInfrastructure, Security, HealthMonitoring, AuditLog).
- Four `*OptionsValidator` → `OptionsValidatorBase<T>`:
  - `ClusterOptionsValidator`: `SeedNodes` ≥ 2 → `MinCount`; strategy ∈ set → `OneOf`;
    three positive `TimeSpan` → `PositiveTimeSpan`; cross-field heartbeat/threshold and
    `DownIfAlone`/`MinNrOfMembers` → `RequireThat`.
  - `SecurityOptionsValidator`: `Required` LdapServer / LdapSearchBase (JwtSigningKey stays
    validated in `JwtTokenService` ctor — unchanged).
  - `HealthMonitoringOptionsValidator`: three `PositiveTimeSpan` + cross-field
    `CentralOfflineTimeout >= OfflineTimeout` → `RequireThat`. Preserve the idempotent
    registration called from all three `Add*HealthMonitoring` entry points.
  - `AuditLogOptionsValidator`: positive/`>=`/range checks → `RequireThat`.
  - Each module `AddXxx` → `AddValidatedOptions<T, TValidator>` where the section binding
    shape allows (preserve `ValidateOnStart` + `TryAddEnumerable` semantics).
- `StartupValidator.Validate(configuration)` at `Program.cs:41` → `ConfigPreflight.For(
  configuration).RequireValue(...)/RequirePort(...)/When(...).ThrowIfInvalid()`. **Must
  keep `StartupValidatorTests` green** — the thrown message is byte-compatible with
  `ConfigPreflight.ThrowIfInvalid()`.

---

## 5. Error handling / behaviour preservation

- Failure surface is unchanged everywhere: `OptionsValidationException` thrown at host
  start via `ValidateOnStart`; `ConfigPreflight.ThrowIfInvalid()` throws the same
  `InvalidOperationException` text ScadaBridge's `StartupValidator` throws today.
- MxGateway + ScadaBridge: **zero message changes** — the existing validator tests and
  `StartupValidatorTests` are the regression guard.
- OtOpcUa: **additive** — a config that was silently accepted (then failed late as an LDAP
  error on first login, or an OPC UA bind error) now fails fast at startup. That is the
  intended improvement, called out so it is not mistaken for a regression.

---

## 6. Testing & verification (gate per repo, before moving on)

- Library: re-run `dotnet test` (already 42 green).
- Each repo on its branch: `dotnet build` + `dotnet test` green.
  - MxGateway: `src/MxGateway.Tests` (fake worker — no MXAccess needed).
  - OtOpcUa: full solution test + the new validator unit tests.
  - ScadaBridge: four validator tests + `StartupValidatorTests` still green.
- **Restore proof** per repo: a clean restore pulls `ZB.MOM.WW.Configuration 0.1.0` from
  Gitea — confirms both the push and the source-mapping edit.

---

## 7. Risks & mitigations

| Risk | Mitigation |
|---|---|
| Package 404 / source-mapping omission breaks restore | Foundation phase + per-repo restore proof gate. |
| A "trivial" message tweak during refactor changes behaviour | Behaviour-preserving rule; existing tests fail loudly if a message drifts. |
| ScadaBridge preflight message drift | `StartupValidatorTests` must pass unchanged. |
| OtOpcUa `OpcUa`/`Ldap` rule set guesses wrong fields | Plan finalizes rules from the actual options classes; additive-only. |
| `AddValidatedOptions` singleton constraint (no scoped deps in validators) | All four ScadaBridge + the gateway validators are already stateless singletons. |

---

## 8. Deliverable & next step

This design doc, then a step-by-step implementation plan produced via the **writing-plans**
skill. No source changes in any repo until the plan is approved and execution begins.

> Note: `~/Desktop/scadaproj` is **not** a git repository, so this design is not committed
> here; it is saved under `docs/plans/`. (Per memory, do not `git init` it without asking.)