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,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.");
+    }
+}