merge(r2): r2-plan08

# Conflicts: # src/ZB.MOM.WW.ScadaBridge.Communication/CommunicationOptionsValidator.cs
2026-07-13 11:10:15 -04:00
parent ca4b0dd849 4f39cfd6c6
commit ccee558ca7
42 changed files with 1094 additions and 79 deletions
@@ -0,0 +1,25 @@
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central;
+
+/// <summary>
+/// Validates <see cref="AuditLogPartitionMaintenanceOptions"/> at host startup
+/// (arch-review 08 round 2 NF4). A zero tick interval spins the maintenance
+/// hosted service; a zero look-ahead leaves <c>pf_AuditLog_Month</c> without a
+/// future monthly boundary, risking inserts into the unbounded tail partition.
+/// </summary>
+public sealed class AuditLogPartitionMaintenanceOptionsValidator
+    : OptionsValidatorBase<AuditLogPartitionMaintenanceOptions>
+{
+    /// <inheritdoc />
+    protected override void Validate(ValidationBuilder builder, AuditLogPartitionMaintenanceOptions options)
+    {
+        builder.RequireThat(options.IntervalSeconds > 0,
+            $"AuditLog:PartitionMaintenance:{nameof(AuditLogPartitionMaintenanceOptions.IntervalSeconds)} " +
+            $"({options.IntervalSeconds}) must be > 0.");
+
+        builder.RequireThat(options.LookaheadMonths > 0,
+            $"AuditLog:PartitionMaintenance:{nameof(AuditLogPartitionMaintenanceOptions.LookaheadMonths)} " +
+            $"({options.LookaheadMonths}) must be > 0.");
+    }
+}
@@ -0,0 +1,31 @@
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central;
+
+/// <summary>
+/// Validates <see cref="AuditLogPurgeOptions"/> at host startup (arch-review 08
+/// round 2 NF4). The class self-clamps at resolve time, but a plainly-wrong
+/// config (zero cadence, zero batch, zero maintenance-command timeout) should
+/// still fail the boot so the operator learns immediately.
+/// <see cref="AuditLogPurgeOptions.IntervalOverride"/> is test-only (per the
+/// class remarks) and is deliberately not validated.
+/// </summary>
+public sealed class AuditLogPurgeOptionsValidator : OptionsValidatorBase<AuditLogPurgeOptions>
+{
+    /// <inheritdoc />
+    protected override void Validate(ValidationBuilder builder, AuditLogPurgeOptions options)
+    {
+        builder.RequireThat(options.IntervalHours > 0,
+            $"AuditLog:Purge:{nameof(AuditLogPurgeOptions.IntervalHours)} " +
+            $"({options.IntervalHours}) must be > 0.");
+
+        // Backing field for the documented "ChannelPurgeBatchSize" config key.
+        builder.RequireThat(options.ChannelPurgeBatchSizeConfigured > 0,
+            $"AuditLog:Purge:{nameof(AuditLogPurgeOptions.ChannelPurgeBatchSizeConfigured)} " +
+            $"(config key ChannelPurgeBatchSize = {options.ChannelPurgeBatchSizeConfigured}) must be > 0.");
+
+        builder.RequireThat(options.MaintenanceCommandTimeoutMinutes > 0,
+            $"AuditLog:Purge:{nameof(AuditLogPurgeOptions.MaintenanceCommandTimeoutMinutes)} " +
+            $"({options.MaintenanceCommandTimeoutMinutes}) must be > 0.");
+    }
+}
@@ -0,0 +1,31 @@
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central;
+
+/// <summary>
+/// Validates <see cref="SiteAuditReconciliationOptions"/> at host startup
+/// (arch-review 08 round 2 NF4). A zero tick interval spins the reconciliation
+/// singleton, a zero batch pulls nothing per RPC, and a zero stalled-cycle
+/// threshold would fire the stalled signal on the first non-draining cycle.
+/// <see cref="SiteAuditReconciliationOptions.ReconciliationIntervalOverride"/>
+/// is test-only (per the class remarks) and is deliberately not validated.
+/// </summary>
+public sealed class SiteAuditReconciliationOptionsValidator
+    : OptionsValidatorBase<SiteAuditReconciliationOptions>
+{
+    /// <inheritdoc />
+    protected override void Validate(ValidationBuilder builder, SiteAuditReconciliationOptions options)
+    {
+        builder.RequireThat(options.ReconciliationIntervalSeconds > 0,
+            $"AuditLog:Reconciliation:{nameof(SiteAuditReconciliationOptions.ReconciliationIntervalSeconds)} " +
+            $"({options.ReconciliationIntervalSeconds}) must be > 0.");
+
+        builder.RequireThat(options.BatchSize > 0,
+            $"AuditLog:Reconciliation:{nameof(SiteAuditReconciliationOptions.BatchSize)} " +
+            $"({options.BatchSize}) must be > 0.");
+
+        builder.RequireThat(options.StalledAfterNonDrainingCycles > 0,
+            $"AuditLog:Reconciliation:{nameof(SiteAuditReconciliationOptions.StalledAfterNonDrainingCycles)} " +
+            $"({options.StalledAfterNonDrainingCycles}) must be > 0.");
+    }
+}
@@ -92,20 +92,23 @@ public static class ServiceCollectionExtensions
        // failures as AuditRedactionFailure on the site health report.
        services.TryAddSingleton<IAuditRedactionFailureCounter, NoOpAuditRedactionFailureCounter>();

-        // Site writer + telemetry options bindings.
-        // BindConfiguration is not used because the configuration root supplied
-        // by the caller may not be the application root — we go through the
-        // section explicitly so a partial IConfiguration (e.g. a test stub
-        // anchored on the AuditLog section's parent) still works.
-        services.AddOptions<SqliteAuditWriterOptions>()
-            .Bind(config.GetSection(SiteWriterSectionName));
-        services.AddOptions<SiteAuditTelemetryOptions>()
-            .Bind(config.GetSection(SiteTelemetrySectionName));
+        // Site writer + telemetry options bindings — now bind-and-validate via
+        // the shared helper so a bad site config fails fast at boot (NF4). The
+        // helper's GetSection(sectionPath) still resolves the section explicitly
+        // (NOT BindConfiguration), preserving the partial-config-root rationale:
+        // the caller's IConfiguration may be a test stub anchored on the AuditLog
+        // section's parent rather than the application root.
+        services.AddValidatedOptions<SqliteAuditWriterOptions, SqliteAuditWriterOptionsValidator>(
+            config, SiteWriterSectionName);
+        services.AddValidatedOptions<SiteAuditTelemetryOptions, SiteAuditTelemetryOptionsValidator>(
+            config, SiteTelemetrySectionName);
        // Retention purge options (the SiteAuditRetentionService hosted job is
-        // registered site-only in AddAuditLogHealthMetricsBridge). Binding here is
-        // inert on central — no hosted service consumes it there.
-        services.AddOptions<SiteAuditRetentionOptions>()
-            .Bind(config.GetSection(SiteAuditRetentionOptions.SectionName));
+        // registered site-only in AddAuditLogHealthMetricsBridge). The binding
+        // here is inert on central — no hosted service consumes it there — but
+        // the defaults validate clean, so eager validation on the central root is
+        // harmless.
+        services.AddValidatedOptions<SiteAuditRetentionOptions, SiteAuditRetentionOptionsValidator>(
+            config, SiteAuditRetentionOptions.SectionName);

        // SqliteAuditWriter is a singleton with a single owned SqliteConnection
        // and a background writer Task; multiple instances would race on the
@@ -365,8 +368,8 @@ public static class ServiceCollectionExtensions
        ArgumentNullException.ThrowIfNull(services);
        ArgumentNullException.ThrowIfNull(config);

-        services.AddOptions<AuditLogPartitionMaintenanceOptions>()
-            .Bind(config.GetSection(PartitionMaintenanceSectionName));
+        services.AddValidatedOptions<AuditLogPartitionMaintenanceOptions,
+            AuditLogPartitionMaintenanceOptionsValidator>(config, PartitionMaintenanceSectionName);
        services.AddHostedService<AuditLogPartitionMaintenanceService>();

        // I1 (review): bind the two central-singleton options HERE rather than in
@@ -382,10 +385,10 @@ public static class ServiceCollectionExtensions
        // 5 min reconciliation tick); production exposes IntervalHours /
        // ReconciliationIntervalSeconds only — the test-only *Override knobs are
        // not intended to be set from config (see the options classes' remarks).
-        services.AddOptions<AuditLogPurgeOptions>()
-            .Bind(config.GetSection(PurgeSectionName));
-        services.AddOptions<SiteAuditReconciliationOptions>()
-            .Bind(config.GetSection(ReconciliationSectionName));
+        services.AddValidatedOptions<AuditLogPurgeOptions, AuditLogPurgeOptionsValidator>(
+            config, PurgeSectionName);
+        services.AddValidatedOptions<SiteAuditReconciliationOptions, SiteAuditReconciliationOptionsValidator>(
+            config, ReconciliationSectionName);

        // Central health snapshot — a single object
        // that owns the CentralAuditWriteFailures + AuditRedactionFailure
@@ -0,0 +1,31 @@
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.ScadaBridge.AuditLog.Site;
+
+/// <summary>
+/// Validates <see cref="SiteAuditRetentionOptions"/> at host startup
+/// (arch-review 08 round 2 NF4). The option class self-clamps at resolve time,
+/// but a plainly-wrong config (zero retention window, zero/negative purge
+/// period, negative initial delay) should still fail the boot so the operator
+/// learns immediately rather than trusting a silent clamp.
+/// <see cref="SiteAuditRetentionOptions.PurgeIntervalOverride"/> is test-only
+/// (per the class remarks) and is deliberately not validated.
+/// </summary>
+public sealed class SiteAuditRetentionOptionsValidator : OptionsValidatorBase<SiteAuditRetentionOptions>
+{
+    /// <inheritdoc />
+    protected override void Validate(ValidationBuilder builder, SiteAuditRetentionOptions options)
+    {
+        builder.RequireThat(options.RetentionDays > 0,
+            $"AuditLog:SiteRetention:{nameof(SiteAuditRetentionOptions.RetentionDays)} " +
+            $"({options.RetentionDays}) must be > 0.");
+
+        builder.RequireThat(options.PurgeInterval > TimeSpan.Zero,
+            $"AuditLog:SiteRetention:{nameof(SiteAuditRetentionOptions.PurgeInterval)} " +
+            $"({options.PurgeInterval}) must be > 0.");
+
+        builder.RequireThat(options.InitialDelay >= TimeSpan.Zero,
+            $"AuditLog:SiteRetention:{nameof(SiteAuditRetentionOptions.InitialDelay)} " +
+            $"({options.InitialDelay}) must be >= 0.");
+    }
+}
@@ -0,0 +1,38 @@
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.ScadaBridge.AuditLog.Site;
+
+/// <summary>
+/// Validates <see cref="SqliteAuditWriterOptions"/> at host startup
+/// (arch-review 08 round 2 NF4). The channel/batch/flush knobs feed the
+/// background writer task; a zero anywhere stalls it (nothing drains, nothing
+/// flushes), and an empty <c>DatabasePath</c> leaves the SQLite writer with no
+/// backing store. <see cref="SqliteAuditWriterOptions.BacklogPollIntervalSeconds"/>
+/// is intentionally NOT validated — a non-positive value has a documented
+/// fall-back-to-30s contract in <c>SiteAuditBacklogReporter</c>.
+/// </summary>
+public sealed class SqliteAuditWriterOptionsValidator : OptionsValidatorBase<SqliteAuditWriterOptions>
+{
+    /// <inheritdoc />
+    protected override void Validate(ValidationBuilder builder, SqliteAuditWriterOptions options)
+    {
+        builder.RequireThat(!string.IsNullOrWhiteSpace(options.DatabasePath),
+            $"AuditLog:SiteWriter:{nameof(SqliteAuditWriterOptions.DatabasePath)} must be a non-empty path.");
+
+        builder.RequireThat(options.ChannelCapacity > 0,
+            $"AuditLog:SiteWriter:{nameof(SqliteAuditWriterOptions.ChannelCapacity)} " +
+            $"({options.ChannelCapacity}) must be > 0.");
+
+        builder.RequireThat(options.BatchSize > 0,
+            $"AuditLog:SiteWriter:{nameof(SqliteAuditWriterOptions.BatchSize)} " +
+            $"({options.BatchSize}) must be > 0.");
+
+        builder.RequireThat(options.FlushIntervalMs > 0,
+            $"AuditLog:SiteWriter:{nameof(SqliteAuditWriterOptions.FlushIntervalMs)} " +
+            $"({options.FlushIntervalMs}) must be > 0.");
+
+        // BacklogPollIntervalSeconds is deliberately unchecked: a non-positive
+        // value falls back to the reporter's 30s default (see the option's
+        // remarks + register row 21 resolution).
+    }
+}
@@ -0,0 +1,36 @@
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.ScadaBridge.AuditLog.Site.Telemetry;
+
+/// <summary>
+/// Validates <see cref="SiteAuditTelemetryOptions"/> at host startup
+/// (arch-review 08 round 2 NF4). <c>SiteAuditTelemetryActor</c> uses the two
+/// interval knobs as raw scheduling delays (busy after a productive/faulted
+/// drain, idle after an empty one), so a zero interval spins the drain loop and
+/// a zero batch drains nothing. Idle must be &gt;= busy: a shorter idle interval
+/// inverts the actor's back-off-when-empty intent.
+/// </summary>
+public sealed class SiteAuditTelemetryOptionsValidator : OptionsValidatorBase<SiteAuditTelemetryOptions>
+{
+    /// <inheritdoc />
+    protected override void Validate(ValidationBuilder builder, SiteAuditTelemetryOptions options)
+    {
+        builder.RequireThat(options.BatchSize > 0,
+            $"AuditLog:SiteTelemetry:{nameof(SiteAuditTelemetryOptions.BatchSize)} " +
+            $"({options.BatchSize}) must be > 0.");
+
+        builder.RequireThat(options.BusyIntervalSeconds > 0,
+            $"AuditLog:SiteTelemetry:{nameof(SiteAuditTelemetryOptions.BusyIntervalSeconds)} " +
+            $"({options.BusyIntervalSeconds}) must be > 0.");
+
+        builder.RequireThat(options.IdleIntervalSeconds > 0,
+            $"AuditLog:SiteTelemetry:{nameof(SiteAuditTelemetryOptions.IdleIntervalSeconds)} " +
+            $"({options.IdleIntervalSeconds}) must be > 0.");
+
+        builder.RequireThat(options.IdleIntervalSeconds >= options.BusyIntervalSeconds,
+            $"AuditLog:SiteTelemetry:{nameof(SiteAuditTelemetryOptions.IdleIntervalSeconds)} " +
+            $"({options.IdleIntervalSeconds}) must be >= " +
+            $"{nameof(SiteAuditTelemetryOptions.BusyIntervalSeconds)} ({options.BusyIntervalSeconds}) " +
+            "— the idle drain must back off at least as far as the busy drain.");
+    }
+}