scadaproj/components/configuration/current-state/mxaccessgw/CURRENT-STATE.md

Configuration validation — current state: MxAccessGateway

Repo: ~/Desktop/MxAccessGateway (mxaccessgw). Stack: .NET 10 gateway (x64) + .NET 4.8 worker (x86), gRPC; solution src/MxGateway.sln. All paths relative to repo root. Verified 2026-06-01.

MxGateway has one large, well-structured options validator for a single composite GatewayOptions, wired through a bespoke DI extension. It is the textbook hand-rolled version of exactly what the shared library normalizes: a private List<string> accumulator, a stack of AddIfXxx helper methods, and an AddOptions().BindConfiguration().ValidateOnStart() registration — all of which collapse onto OptionsValidatorBase + AddValidatedOptions with the domain rules left untouched.

1. GatewayOptionsValidator — hand-rolled IValidateOptions<GatewayOptions>

src/ZB.MOM.WW.MxGateway.Server/Configuration/GatewayOptionsValidator.cs:

• :6 — public sealed class GatewayOptionsValidator : IValidateOptions<GatewayOptions> — implements the interface directly (no shared base).
• :17–34 — Validate(string? name, GatewayOptions options): creates List<string> failures (:19), dispatches to nine sub-validators (:21–29), and returns the failures.Count == 0 ? Success : Fail(failures) tail (:31–33). This is precisely the accumulate-all-then-decide convention the base owns.
• Sub-validators (each takes (section options, List<string> failures) and failures.Add(...)s):
  • :36 ValidateAuthentication — Enum.IsDefined on Mode; conditional required SqlitePath / PepperSecretName when Mode == ApiKey.
  • :61 ValidateLdap — short-circuits when !Enabled (:63); seven required-string checks (:68–89), Port positivity (:90), and a cross-field UseTls/AllowInsecureLdap rule (:92).
  • :98 ValidateWorker — required ExecutablePath (:100), valid-path + .exe-extension checks (:101–110), Enum.IsDefined on architecture (:120), eight positive-int checks (:125–152), and a cross-field HeartbeatGraceSeconds >= HeartbeatIntervalSeconds rule (:154), plus a MaxMessageBytes range (:160).
  • :167 ValidateSessions — five positive-int checks (:169–185) + an "unsupported feature" guard (:187).
  • :194 ValidateEvents — QueueCapacity positivity (:196) + Enum.IsDefined on policy (:198).
  • :204 ValidateDashboard — GroupToRole map shape (:211–224) + interval/limit bounds (:226–237).
  • :240 ValidateAlarms — short-circuits when !Enabled (:242); a "need expression or area" rule (:251) + a canonical-prefix rule (:258).
  • :269 ValidateTls — ValidityYears range (:271), required non-blank cert path + valid path (:278–285), non-blank DNS-name entries (:287).
  • :296 ValidateProtocol — exact WorkerProtocolVersion match (:298) + MaxGrpcMessageBytes range (:304).
• Private helpers that duplicate the shared primitives (:311–358):
  • :311 AddIfBlank → maps to ValidationBuilder.Required.
  • :319 AddIfNotPositive → maps to RequireThat(value > 0, ...).
  • :327 AddIfNegative → maps to RequireThat(value >= 0, ...).
  • :335 AddIfInvalidPath → app-specific; stays as a RequireThat/Add custom rule (filesystem-path validity is not a shared primitive).

Every failure message is the gateway's own ("MxGateway:<Section>:<Field> ...") — these are domain rules and stay per-project; only the accumulation plumbing and the trivial helpers move to the base.

2. DI wiring — AddGatewayConfiguration

src/ZB.MOM.WW.MxGateway.Server/Configuration/GatewayConfigurationServiceCollectionExtensions.cs:

• :10–21 — AddGatewayConfiguration(this IServiceCollection services):
  • :12–15 — services.AddOptions<GatewayOptions>().BindConfiguration(GatewayOptions.SectionName).ValidateOnStart();
  • :17 — services.AddSingleton<IValidateOptions<GatewayOptions>, GatewayOptionsValidator>();
  • :18 — also registers IGatewayConfigurationProvider (a separate concern; stays).

Lines :12–17 are exactly the bind + register-validator + ValidateOnStart triple that AddValidatedOptions<GatewayOptions, GatewayOptionsValidator> collapses into one call. (One nuance: the gateway uses BindConfiguration(SectionName) — which reads the section path off the type/const — whereas AddValidatedOptions takes an explicit sectionPath string; the adoption passes GatewayOptions.SectionName as that argument.)

A bad MxGateway section surfaces as OptionsValidationException at host start, via ValidateOnStart() — the same path AddValidatedOptions produces.

3. Summary

Surface	What exists	Shared-lib mapping
Options validator	GatewayOptionsValidator : IValidateOptions<GatewayOptions> (~360 LOC, 9 sub-validators)	→ OptionsValidatorBase<GatewayOptions>
Failure accumulation	private List<string> failures + Count == 0 ? Success : Fail tail	→ owned by base + ValidationBuilder
Rule helpers	AddIfBlank / AddIfNotPositive / AddIfNegative	→ Required / RequireThat primitives
App-specific helper	AddIfInvalidPath	→ stays as a custom RequireThat/Add rule
DI wiring	AddGatewayConfiguration (AddOptions().BindConfiguration().ValidateOnStart() + AddSingleton<IValidateOptions...>)	→ AddValidatedOptions<GatewayOptions, GatewayOptionsValidator>
Pre-host preflight	none (single host, no pre-Akka stage)	n/a — ConfigPreflight not needed

---

Adoption plan → ZB.MOM.WW.Configuration

Migrate the validator to the shared base:

• Change GatewayOptionsValidator : IValidateOptions<GatewayOptions> → GatewayOptionsValidator : OptionsValidatorBase<GatewayOptions> (GatewayOptionsValidator.cs:6).
• Replace the public Validate(string? name, GatewayOptions options) (:17) with the protected override void Validate(ValidationBuilder v, GatewayOptions options). Delete the List<string> failures and the Count == 0 ? Success : Fail tail (:19, :31–33) — the base supplies both.
• Keep the nine sub-validators but re-thread them to take the ValidationBuilder instead of List<string>. Map the helpers: AddIfBlank → v.Required(...), AddIfNotPositive(x, msg) → v.RequireThat(x > 0, msg), AddIfNegative(x, msg) → v.RequireThat(x >= 0, msg). Keep AddIfInvalidPath as a private helper that records via v.Add(...) (filesystem-path validity is app-specific; not a shared primitive). All gateway message strings are preserved verbatim — domain rules do not change.

Migrate the DI wiring:

• In AddGatewayConfiguration (GatewayConfigurationServiceCollectionExtensions.cs:12–17), replace the AddOptions().BindConfiguration().ValidateOnStart() + AddSingleton<IValidateOptions...> pair with:

  services.AddValidatedOptions<GatewayOptions, GatewayOptionsValidator>(
      configuration, GatewayOptions.SectionName);
  

  (The extension gains an IConfiguration parameter, or resolves it from the builder, since AddValidatedOptions binds from an explicit IConfiguration rather than the ambient BindConfiguration.) The IGatewayConfigurationProvider registration (:18) is unrelated and stays.

Keep bespoke (unchanged):

• Every "MxGateway:<Section>:<Field>" message and every domain rule (worker .exe extension, heartbeat grace ≥ interval, protocol-version exact match, \\-prefixed alarm expression, etc.).
• GatewayOptions and its section types — these are MxGateway's options classes; not shared.
• The net48 x86 worker — does no IConfiguration validation; excluded entirely.

Status: follow-on (tracked in ../GAPS.md). Medium-weight, low-risk — behaviour-preserving plumbing swap; one validator, one DI extension.