feat(options): eager startup validation for site-pipeline options (SiteRuntime, S&F, SiteEventLog) (arch-review 08 §1.5)

Claude-Session: https://claude.ai/code/session_01MtdgwpEeCUn6cUA5f1LMPj

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/SiteRuntimeOptionsValidator.cs

@@ -0,0 +1,60 @@
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.ScadaBridge.SiteRuntime;
+
+/// <summary>
+/// Validates <see cref="SiteRuntimeOptions"/> at startup. These values size the
+/// staggered Instance-Actor startup batches, the dedicated script-execution thread
+/// pool, and the site-wide Akka stream's per-subscriber buffer; a zero or negative
+/// count either creates a degenerate thread scheduler / stream stage or trips an
+/// <see cref="ArgumentOutOfRangeException"/> deep inside actor construction with an
+/// opaque message that never names the offending config key. Registered with
+/// <c>ValidateOnStart()</c> so a bad <c>ScadaBridge:SiteRuntime</c> section fails
+/// fast at boot with a clear, key-naming message.
+/// </summary>
+public sealed class SiteRuntimeOptionsValidator : OptionsValidatorBase<SiteRuntimeOptions>
+{
+    /// <inheritdoc />
+    protected override void Validate(ValidationBuilder builder, SiteRuntimeOptions options)
+    {
+        builder.RequireThat(options.StartupBatchSize > 0,
+            $"ScadaBridge:SiteRuntime:StartupBatchSize must be greater than 0 " +
+            $"(was {options.StartupBatchSize}); it sizes each staggered Instance-Actor startup batch.");
+
+        builder.RequireThat(options.StartupBatchDelayMs >= 0,
+            $"ScadaBridge:SiteRuntime:StartupBatchDelayMs must be >= 0 " +
+            $"(was {options.StartupBatchDelayMs}); it is the inter-batch startup delay.");
+
+        builder.RequireThat(options.MaxScriptCallDepth > 0,
+            $"ScadaBridge:SiteRuntime:MaxScriptCallDepth must be greater than 0 " +
+            $"(was {options.MaxScriptCallDepth}); it bounds recursive CallScript/CallShared depth.");
+
+        builder.RequireThat(options.ScriptExecutionTimeoutSeconds > 0,
+            $"ScadaBridge:SiteRuntime:ScriptExecutionTimeoutSeconds must be greater than 0 " +
+            $"(was {options.ScriptExecutionTimeoutSeconds}).");
+
+        builder.RequireThat(options.StreamBufferSize > 0,
+            $"ScadaBridge:SiteRuntime:StreamBufferSize must be greater than 0 " +
+            $"(was {options.StreamBufferSize}); it is the per-subscriber site-stream buffer size.");
+
+        builder.RequireThat(options.ScriptExecutionThreadCount > 0,
+            $"ScadaBridge:SiteRuntime:ScriptExecutionThreadCount must be greater than 0 " +
+            $"(was {options.ScriptExecutionThreadCount}); it sizes the dedicated script-execution scheduler.");
+
+        builder.RequireThat(options.MirroredAlarmCapPerSource > 0,
+            $"ScadaBridge:SiteRuntime:MirroredAlarmCapPerSource must be greater than 0 " +
+            $"(was {options.MirroredAlarmCapPerSource}).");
+
+        builder.RequireThat(options.NativeAlarmRetryIntervalMs > 0,
+            $"ScadaBridge:SiteRuntime:NativeAlarmRetryIntervalMs must be greater than 0 " +
+            $"(was {options.NativeAlarmRetryIntervalMs}).");
+
+        builder.RequireThat(options.ConfigFetchTimeoutSeconds > 0,
+            $"ScadaBridge:SiteRuntime:ConfigFetchTimeoutSeconds must be greater than 0 " +
+            $"(was {options.ConfigFetchTimeoutSeconds}).");
+
+        builder.RequireThat(options.ConfigFetchRetryCount >= 0,
+            $"ScadaBridge:SiteRuntime:ConfigFetchRetryCount must be >= 0 " +
+            $"(was {options.ConfigFetchRetryCount}).");
+    }
+}

src/ZB.MOM.WW.ScadaBridge.SiteRuntime/ZB.MOM.WW.ScadaBridge.SiteRuntime.csproj

@@ -19,6 +19,7 @@
     <PackageReference Include="Microsoft.Extensions.Http" />
     <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
     <PackageReference Include="Microsoft.Extensions.Options" />
+    <PackageReference Include="ZB.MOM.WW.Configuration" />
   </ItemGroup>
 
   <ItemGroup>