scadaproj/code-reviews/Configuration/findings.md

Code Review — Configuration

Field	Value
Library	ZB.MOM.WW.Configuration/
Packages	ZB.MOM.WW.Configuration
Component spec	components/configuration/spec/SPEC.md
Shared contract	components/configuration/shared-contract/ZB.MOM.WW.Configuration.md
Status	Reviewed
Last reviewed	2026-06-01
Reviewer	Claude (automated baseline)
Commit reviewed	5f75cd4
Open findings	0

Summary

The library is small (five source files, ~230 LOC) and in good health. Its core promise — accumulate every failure, never short-circuit — holds across all three entry points (ValidationBuilder, OptionsValidatorBase, ConfigPreflight): the override never returns early, each primitive appends to a List<string> and returns this, and the Success/Fail decision is taken only after every rule has run. The boundary cases that matter are correct: Port rejects 0 and 65536 and accepts 1/65535; HostPort correctly rejects bare hosts, empty ports, out-of-range ports, and (deliberately) unbracketed IPv6; Required treats null / empty / whitespace alike; OneOf is case-insensitive and treats null as a failure (documented); MinCount treats null as zero. Null-guarding is consistent (ArgumentNullException/ ArgumentException.ThrowIfNullOrWhiteSpace on every public entry point). The ConfigPreflight.ThrowIfInvalid() envelope is byte-compatible with the ScadaBridge StartupValidator format the SPEC pins ("Configuration validation failed:\n - <field> <reason>", \n-joined), and the validator created by OptionsValidatorBase is stateless (fresh ValidationBuilder per call), so the singleton-registration requirement in SPEC §3 is honoured. Dependency footprint is minimal and exactly as documented (four Microsoft.Extensions.* abstractions, no ASP.NET Core). The four findings are all Low: a non-idempotent DI registration (AddSingleton vs TryAddEnumerable), a small wording inconsistency in the raw-port check, over-permissive integer port parsing, and the XML-doc-not-shipped packaging gap (which is fleet-wide, not specific to this library). Test coverage (27 tests across the four public surfaces) is solid for the happy and primary-failure paths; a few edge cases noted below are untested.

Checklist coverage

#	Category	Examined	Notes
1	Correctness & logic bugs	☑	Accumulation never short-circuits; port/host:port/duration/min-count boundaries correct. Port parsing over-permissive (003).
2	Public API surface & compatibility	☑	Surface matches the shared contract exactly; nullability annotations correct; sealed/abstract deliberate; internal Checks does not leak. No issues.
3	Concurrency & thread safety	☑	Validator is stateless (fresh builder per Validate); ValidationBuilder/ConfigPreflight are per-call locals. Safe as a singleton. No issues.
4	Error handling & resilience	☑	Guard clauses on every public entry; correct exception types (OptionsValidationException via ValidateOnStart, InvalidOperationException from ConfigPreflight); no swallowed exceptions. No issues.
5	Security & secret handling	☑	No secrets handled; failure messages echo config values (port/host/role), which are non-sensitive by design. No issues.
6	Performance & resource management	☑	Startup-only, no hot path, nothing disposable, no async. No issues.
7	Spec & shared-contract adherence	☑	ConfigPreflight envelope byte-compatible with StartupValidator; primitives match §2 table. Minor wording inconsistency in PortValue (002).
8	Packaging, dependencies & project layout	☑	Single package, minimal closure, central versions, .gitignore present, no tracked build output. XML docs / README not packaged (004).
9	Testing coverage	☑	27 tests cover the four public surfaces + accumulation + byte-format. Untested: AddValidatedOptions null guards, double-registration, exact wording strings.
10	Documentation & XML docs	☑	Public XML docs present and accurate on every type/member. Not emitted into the nupkg (004).

Findings

Configuration-001 — AddValidatedOptions uses AddSingleton, so a double call registers (and runs) the validator twice

Severity	Low
Category	Correctness & logic bugs
Status	Resolved
Location	ZB.MOM.WW.Configuration/src/ZB.MOM.WW.Configuration/ServiceCollectionExtensions.cs:36

Description

AddValidatedOptions registers the validator with services.AddSingleton<IValidateOptions<TOptions>, TValidator>(). IValidateOptions<TOptions> is a multi-registration (enumerable) service — the options pipeline resolves all registered IValidateOptions<TOptions> and runs each. Because AddSingleton appends unconditionally, calling AddValidatedOptions<TOptions, TValidator> twice for the same TOptions/TValidator pair (e.g. two modules both guarding the same section, or an accidental duplicate during refactoring) registers the validator twice, so it executes twice and every accumulated failure is reported twice in the resulting OptionsValidationException. The framework-idiomatic registration for IValidateOptions<T> is TryAddEnumerable(ServiceDescriptor.Singleton<IValidateOptions<TOptions>, TValidator>()), which is idempotent. Impact is limited (consumers normally call once per section, and duplicate messages are cosmetic, not a correctness break of the accumulate-all contract), hence Low — but the deviation from the .NET idiom is real and easy to fix. The SPEC §3 wording ("registers the validator as a singleton") is satisfied either way.

Recommendation

Replace services.AddSingleton<IValidateOptions<TOptions>, TValidator>() with services.TryAddEnumerable(ServiceDescriptor.Singleton<IValidateOptions<TOptions>, TValidator>()) (via Microsoft.Extensions.DependencyInjection.Extensions). Add a test asserting that calling AddValidatedOptions twice yields a single set of failure messages.

Resolution

Resolved in 544a6dd, 2026-06-01 — AddValidatedOptions now registers the validator via TryAddEnumerable(ServiceDescriptor.Singleton<...>()), so a double call is idempotent (test: AddValidatedOptionsTests.Calling_twice_registers_validator_once).

Configuration-002 — Checks.PortValue quotes the raw value on a parse failure but not on a range failure

Severity	Low
Category	Spec & shared-contract adherence
Status	Resolved
Location	ZB.MOM.WW.Configuration/src/ZB.MOM.WW.Configuration/Checks.cs:21

Description

PortValue produces two different message shapes for the same field depending on why the port is invalid. When the raw string parses but is out of range (e.g. "0" or "70000"), it delegates to Checks.Port(int, field), which renders "<field> must be between 1 and 65535 (was 0)" — unquoted. When the raw string does not parse (e.g. "notaport", null), it renders "<field> must be between 1 and 65535 (was 'notaport')" — quoted. So two failures of the same rule, from the same raw-config caller, read with inconsistent quoting. The shared contract (shared-contract/ZB.MOM.WW.Configuration.md, "Internal Checks seam") states Checks is "the single source of failure wording" so "a port failure reads the same whether it came from a bound options object or a raw config key" — this inconsistency is in mild tension with that claim. It is cosmetic (no consumer parses the text) and the overlapping integer case does match the bound-options wording, so it is Low.

Recommendation

Make the two branches use a consistent quoting convention for the offending value — e.g. have the range-failure branch also quote ((was '0')), or have the parse-failure branch route through a shared formatter. Lock the exact strings down with a wording assertion test.

Resolution

Resolved in 544a6dd, 2026-06-01 — Checks.PortValue now quotes the offending raw value on both the parse-failure and range-failure branches ((was '0')), wording pinned by test (test: ChecksWordingTests.PortValue_range_failure_quotes_the_value).

Configuration-003 — Port parsing accepts leading sign and surrounding whitespace and is culture-sensitive

Severity	Low
Category	Correctness & logic bugs
Status	Resolved
Location	ZB.MOM.WW.Configuration/src/ZB.MOM.WW.Configuration/Checks.cs:22, ZB.MOM.WW.Configuration/src/ZB.MOM.WW.Configuration/Checks.cs:36

Description

Both PortValue (int.TryParse(raw, out var port)) and HostPort (int.TryParse(value[(idx + 1)..], out var port)) use the default int.TryParse overload, which applies NumberStyles.Integer (AllowLeadingWhite | AllowTrailingWhite | AllowLeadingSign) and the current culture. As a result strings the documentation describes as "integer TCP port" are accepted more loosely than intended: "+5000", " 5000 ", and "host: 5000" (space after the colon) all parse and pass, and parsing is locale-dependent. A leading - parses to a negative number that the subsequent range check rejects (so "-1" is correctly rejected), but the whitespace/leading-+ cases silently pass. This is a robustness nuance rather than a security or correctness break — a port that survives the loose parse is still in 1..65535 — so it is Low.

Recommendation

Parse with an explicit, culture-invariant, strict style, e.g. int.TryParse(raw, NumberStyles.None, CultureInfo.InvariantCulture, out var port) (rejects sign and whitespace), in both PortValue and HostPort. Add Theory cases for "+5000", " 5000 ", and a space-after-colon endpoint to pin the behaviour.

Resolution

Resolved in 544a6dd, 2026-06-01 — both PortValue and HostPort now parse with int.TryParse(s, NumberStyles.None, CultureInfo.InvariantCulture, ...), rejecting leading sign/whitespace and culture-dependent formats (test: ChecksWordingTests.PortValue_rejects_loose_inputs, HostPort_rejects_loose_port_inputs).

Configuration-004 — XML documentation and README are not packaged into the nupkg

Severity	Low
Category	Documentation & XML docs
Status	Resolved
Location	ZB.MOM.WW.Configuration/src/ZB.MOM.WW.Configuration/ZB.MOM.WW.Configuration.csproj:1, ZB.MOM.WW.Configuration/Directory.Build.props:1

Description

Every public type and member carries accurate XML doc comments, but neither the project nor Directory.Build.props sets <GenerateDocumentationFile>true</GenerateDocumentationFile>, so no .xml doc file is produced or included in the dotnet pack output. Consumers of the package therefore get no IntelliSense documentation for OptionsValidatorBase, ValidationBuilder, AddValidatedOptions, or ConfigPreflight, despite the docs existing in source. The project also does not set PackageReadmeFile, so the README is not embedded in the package for display on the NuGet feed. Category 10 of the review process explicitly notes "these are libraries — public docs matter," so the gap is worth recording. It is fleet-wide (the sibling ZB.MOM.WW.Audit library has the same omission), not a Configuration-specific regression, hence Low.

Recommendation

Add <GenerateDocumentationFile>true</GenerateDocumentationFile> (ideally in Directory.Build.props so the whole family inherits it) and consider <PackageReadmeFile>README.md</PackageReadmeFile> plus packing the README. Treat as a shared-infra change across the six libraries rather than a one-off.

Resolution

Resolved in 544a6dd, 2026-06-01 — GenerateDocumentationFile=true added to Directory.Build.props (test project opts out) and PackageReadmeFile/README pack item added to the csproj, so dotnet pack now ships ZB.MOM.WW.Configuration.xml and README.md in the nupkg.