fix(options): validate Host Node/Database/Logging options at startup — empty NodeName fails fast instead of NULLing SourceNode (plan R2-08 T7, arch-review 08r2 NF4)

2026-07-13 10:49:42 -04:00
parent f85f036b09
commit 4a0462e4d0
11 changed files with 224 additions and 3 deletions
@@ -0,0 +1,28 @@
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.ScadaBridge.Host;
+
+/// <summary>
+/// Validates <see cref="DatabaseOptions"/> at host startup (arch-review 08
+/// round 2 NF4). All three connection settings are nullable and role-dependent
+/// (central needs the SQL Server strings, a site needs only the SQLite path),
+/// so a <c>null</c> value is valid. A present-but-whitespace value is not — it
+/// signals a mis-set config key that would fail opaquely at first DB use.
+/// </summary>
+public sealed class DatabaseOptionsValidator : OptionsValidatorBase<DatabaseOptions>
+{
+    /// <inheritdoc />
+    protected override void Validate(ValidationBuilder builder, DatabaseOptions options)
+    {
+        RequireNotWhitespace(builder, options.ConfigurationDb, nameof(DatabaseOptions.ConfigurationDb));
+        RequireNotWhitespace(builder, options.MachineDataDb, nameof(DatabaseOptions.MachineDataDb));
+        RequireNotWhitespace(builder, options.SiteDbPath, nameof(DatabaseOptions.SiteDbPath));
+    }
+
+    // null is valid (role-dependent); reject only a present-but-blank value.
+    private static void RequireNotWhitespace(ValidationBuilder builder, string? value, string field)
+    {
+        builder.RequireThat(value is null || !string.IsNullOrWhiteSpace(value),
+            $"ScadaBridge:Database:{field} is set but blank — either remove it or give it a real value.");
+    }
+}
@@ -0,0 +1,27 @@
+using Serilog.Events;
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.ScadaBridge.Host;
+
+/// <summary>
+/// Validates <see cref="LoggingOptions"/> at host startup (arch-review 08 round
+/// 2 NF4). <see cref="LoggingOptions.MinimumLevel"/> is parsed into a Serilog
+/// <see cref="LogEventLevel"/> by <c>LoggerConfigurationFactory.ParseLevel</c>,
+/// which silently falls back to <c>Information</c> for an unrecognised value.
+/// This validator surfaces that misconfiguration at boot instead: a present,
+/// non-blank value must name a real level (Verbose/Debug/Information/Warning/
+/// Error/Fatal, case-insensitive). A null/blank value is treated as "unset"
+/// (defaults to Information), mirroring the parser.
+/// </summary>
+public sealed class LoggingOptionsValidator : OptionsValidatorBase<LoggingOptions>
+{
+    /// <inheritdoc />
+    protected override void Validate(ValidationBuilder builder, LoggingOptions options)
+    {
+        builder.RequireThat(
+            string.IsNullOrWhiteSpace(options.MinimumLevel)
+                || Enum.TryParse<LogEventLevel>(options.MinimumLevel, ignoreCase: true, out _),
+            $"ScadaBridge:Logging:{nameof(LoggingOptions.MinimumLevel)} ('{options.MinimumLevel}') " +
+            $"is not a recognised Serilog level. Valid: {string.Join(", ", Enum.GetNames<LogEventLevel>())}.");
+    }
+}
@@ -0,0 +1,34 @@
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.ScadaBridge.Host;
+
+/// <summary>
+/// Validates <see cref="NodeOptions"/> at host startup (arch-review 08 round 2
+/// NF4). The headline invariant: <see cref="NodeOptions.NodeName"/> must be
+/// non-empty — an empty value normalises to a NULL <c>SourceNode</c> audit
+/// column, silently degrading the audit trail (the wonder-app-vd03 failure
+/// mode), so the host must fail fast at boot instead. Ports are bounded to the
+/// TCP range; <c>0</c> stays valid because it requests a dynamically-assigned
+/// port (CompositionRootTests rely on this).
+/// </summary>
+public sealed class NodeOptionsValidator : OptionsValidatorBase<NodeOptions>
+{
+    /// <inheritdoc />
+    protected override void Validate(ValidationBuilder builder, NodeOptions options)
+    {
+        builder.RequireThat(!string.IsNullOrWhiteSpace(options.NodeName),
+            $"ScadaBridge:Node:{nameof(NodeOptions.NodeName)} must be a non-empty label " +
+            "— an empty node name stamps the SourceNode audit column NULL.");
+
+        RequirePort(builder, options.RemotingPort, nameof(NodeOptions.RemotingPort));
+        RequirePort(builder, options.GrpcPort, nameof(NodeOptions.GrpcPort));
+        RequirePort(builder, options.MetricsPort, nameof(NodeOptions.MetricsPort));
+    }
+
+    // 0 stays valid (dynamic-port request); reject only out-of-TCP-range values.
+    private static void RequirePort(ValidationBuilder builder, int port, string field)
+    {
+        builder.RequireThat(port is >= 0 and <= 65_535,
+            $"ScadaBridge:Node:{field} ({port}) must be in [0, 65535].");
+    }
+}
@@ -157,19 +157,33 @@ public static class SiteServiceRegistration
    /// <param name="config">Application configuration supplying the option values.</param>
    public static void BindSharedOptions(IServiceCollection services, IConfiguration config)
    {
-        services.Configure<NodeOptions>(config.GetSection("ScadaBridge:Node"));
+        // Bind + eagerly validate: an empty NodeName would stamp the SourceNode audit
+        // column NULL, so fail the host at boot with a key-naming message instead of
+        // silently degrading the audit trail (arch-review 08r2 NF4).
+        services.AddOptions<NodeOptions>().Bind(config.GetSection("ScadaBridge:Node")).ValidateOnStart();
+        services.TryAddEnumerable(
+            ServiceDescriptor.Singleton<IValidateOptions<NodeOptions>, NodeOptionsValidator>());
        // Bind + eagerly validate: ClusterOptionsValidator is registered (TryAddEnumerable)
        // by the ClusterInfrastructure module, so chaining ValidateOnStart() here makes a bad
        // ScadaBridge:Cluster section fail fast at host build instead of lazily on first resolve.
        services.AddOptions<ClusterOptions>().Bind(config.GetSection("ScadaBridge:Cluster")).ValidateOnStart();
-        services.Configure<DatabaseOptions>(config.GetSection("ScadaBridge:Database"));
+        // Bind + eagerly validate: a present-but-blank connection setting fails fast
+        // here rather than opaquely at first DB use (arch-review 08r2 NF4).
+        services.AddOptions<DatabaseOptions>().Bind(config.GetSection("ScadaBridge:Database")).ValidateOnStart();
+        services.TryAddEnumerable(
+            ServiceDescriptor.Singleton<IValidateOptions<DatabaseOptions>, DatabaseOptionsValidator>());
        services.Configure<CommunicationOptions>(config.GetSection("ScadaBridge:Communication"));
        // Bind + eagerly validate: HealthMonitoringOptionsValidator is registered (TryAddEnumerable)
        // by the HealthMonitoring module, so chaining ValidateOnStart() here makes a bad
        // ScadaBridge:HealthMonitoring section fail fast at host build instead of lazily on first resolve.
        services.AddOptions<HealthMonitoringOptions>().Bind(config.GetSection("ScadaBridge:HealthMonitoring")).ValidateOnStart();
        services.Configure<NotificationOptions>(config.GetSection("ScadaBridge:Notification"));
-        services.Configure<LoggingOptions>(config.GetSection("ScadaBridge:Logging"));
+        // Bind + eagerly validate: an unrecognised MinimumLevel would silently fall back
+        // to Information; fail fast at boot so the operator's intended floor is honoured
+        // (arch-review 08r2 NF4).
+        services.AddOptions<LoggingOptions>().Bind(config.GetSection("ScadaBridge:Logging")).ValidateOnStart();
+        services.TryAddEnumerable(
+            ServiceDescriptor.Singleton<IValidateOptions<LoggingOptions>, LoggingOptionsValidator>());

        // Audit Log — exposes ScadaBridge:Node:NodeName to downstream audit
        // writers so they can stamp the SourceNode column. Registered here in