diff --git a/src/ZB.MOM.WW.ScadaBridge.Host/SiteServiceRegistration.cs b/src/ZB.MOM.WW.ScadaBridge.Host/SiteServiceRegistration.cs index 43366413..104b38fe 100644 --- a/src/ZB.MOM.WW.ScadaBridge.Host/SiteServiceRegistration.cs +++ b/src/ZB.MOM.WW.ScadaBridge.Host/SiteServiceRegistration.cs @@ -1,3 +1,5 @@ +using Microsoft.Extensions.DependencyInjection.Extensions; +using Microsoft.Extensions.Options; using ZB.MOM.WW.ScadaBridge.AuditLog; using ZB.MOM.WW.ScadaBridge.ClusterInfrastructure; using ZB.MOM.WW.ScadaBridge.Communication; @@ -121,10 +123,33 @@ public static class SiteServiceRegistration // Options binding BindSharedOptions(services, config); - services.Configure(config.GetSection("ScadaBridge:SiteRuntime")); + + // Bind + eagerly validate the site-pipeline options. The validators live with their + // owner component projects (SiteRuntime / StoreAndForward / SiteEventLogging) per the + // "options classes owned by component projects" convention, but these three sections + // are bound HERE in the Host (not in a component SCE), so both the ValidateOnStart() + // chain and the TryAddEnumerable validator registration happen here. A bad section + // fails fast at host build with a clear, key-naming message instead of crashing an + // actor / hosted service later with an opaque ArgumentOutOfRangeException. + services.AddOptions() + .Bind(config.GetSection("ScadaBridge:SiteRuntime")) + .ValidateOnStart(); + services.TryAddEnumerable( + ServiceDescriptor.Singleton, SiteRuntimeOptionsValidator>()); + services.Configure(config.GetSection("ScadaBridge:DataConnection")); - services.Configure(config.GetSection("ScadaBridge:StoreAndForward")); - services.Configure(config.GetSection("ScadaBridge:SiteEventLog")); + + services.AddOptions() + .Bind(config.GetSection("ScadaBridge:StoreAndForward")) + .ValidateOnStart(); + services.TryAddEnumerable( + ServiceDescriptor.Singleton, StoreAndForwardOptionsValidator>()); + + services.AddOptions() + .Bind(config.GetSection("ScadaBridge:SiteEventLog")) + .ValidateOnStart(); + services.TryAddEnumerable( + ServiceDescriptor.Singleton, SiteEventLogOptionsValidator>()); } /// Binds shared options sections (Node, Cluster, Database, Communication, etc.) used by both site and central roles. diff --git a/src/ZB.MOM.WW.ScadaBridge.SiteEventLogging/SiteEventLogOptionsValidator.cs b/src/ZB.MOM.WW.ScadaBridge.SiteEventLogging/SiteEventLogOptionsValidator.cs new file mode 100644 index 00000000..702ecd59 --- /dev/null +++ b/src/ZB.MOM.WW.ScadaBridge.SiteEventLogging/SiteEventLogOptionsValidator.cs @@ -0,0 +1,56 @@ +using ZB.MOM.WW.Configuration; + +namespace ZB.MOM.WW.ScadaBridge.SiteEventLogging; + +/// +/// Validates at startup. Retention/purge values +/// drive the daily purge PeriodicTimer (a zero/negative period trips +/// ), the paging bounds gate query result +/// sizes, and the write-queue capacity sizes a bounded channel; a +/// MaxQueryPageSize below QueryPageSize would silently clamp the +/// default page below itself. Registered with ValidateOnStart() so a bad +/// ScadaBridge:SiteEventLog section fails fast at boot with a clear, +/// key-naming message. +/// +public sealed class SiteEventLogOptionsValidator : OptionsValidatorBase +{ + /// + protected override void Validate(ValidationBuilder builder, SiteEventLogOptions options) + { + builder.RequireThat(options.RetentionDays > 0, + $"ScadaBridge:SiteEventLog:RetentionDays must be greater than 0 " + + $"(was {options.RetentionDays})."); + + builder.RequireThat(options.MaxStorageMb > 0, + $"ScadaBridge:SiteEventLog:MaxStorageMb must be greater than 0 " + + $"(was {options.MaxStorageMb})."); + + builder.RequireThat(!string.IsNullOrWhiteSpace(options.DatabasePath), + "ScadaBridge:SiteEventLog:DatabasePath must be a non-empty path; " + + "it is the SQLite file backing the site event log."); + + builder.RequireThat(options.QueryPageSize > 0, + $"ScadaBridge:SiteEventLog:QueryPageSize must be greater than 0 " + + $"(was {options.QueryPageSize})."); + + builder.RequireThat(options.WriteQueueCapacity > 0, + $"ScadaBridge:SiteEventLog:WriteQueueCapacity must be greater than 0 " + + $"(was {options.WriteQueueCapacity}); it bounds the background write channel."); + + builder.RequireThat(options.PurgeInterval > TimeSpan.Zero, + $"ScadaBridge:SiteEventLog:PurgeInterval must be a positive duration " + + $"(was {options.PurgeInterval}); it is the purge PeriodicTimer period."); + + // The hard page-size ceiling clamps a caller-supplied PageSize; a ceiling + // below the default QueryPageSize would silently clamp the default below + // itself. Only meaningful when both are positive (owned above), so stay + // silent when either is non-positive rather than double-firing. + builder.RequireThat( + !(options.QueryPageSize > 0 + && options.MaxQueryPageSize > 0 + && options.MaxQueryPageSize < options.QueryPageSize), + $"ScadaBridge:SiteEventLog:MaxQueryPageSize ({options.MaxQueryPageSize}) " + + $"must be >= QueryPageSize ({options.QueryPageSize}): the ceiling clamps a caller's " + + "requested page size, so it cannot be smaller than the default page size."); + } +} diff --git a/src/ZB.MOM.WW.ScadaBridge.SiteEventLogging/ZB.MOM.WW.ScadaBridge.SiteEventLogging.csproj b/src/ZB.MOM.WW.ScadaBridge.SiteEventLogging/ZB.MOM.WW.ScadaBridge.SiteEventLogging.csproj index f6df1c1d..089117e3 100644 --- a/src/ZB.MOM.WW.ScadaBridge.SiteEventLogging/ZB.MOM.WW.ScadaBridge.SiteEventLogging.csproj +++ b/src/ZB.MOM.WW.ScadaBridge.SiteEventLogging/ZB.MOM.WW.ScadaBridge.SiteEventLogging.csproj @@ -14,6 +14,7 @@ + diff --git a/src/ZB.MOM.WW.ScadaBridge.SiteRuntime/SiteRuntimeOptionsValidator.cs b/src/ZB.MOM.WW.ScadaBridge.SiteRuntime/SiteRuntimeOptionsValidator.cs new file mode 100644 index 00000000..8de19199 --- /dev/null +++ b/src/ZB.MOM.WW.ScadaBridge.SiteRuntime/SiteRuntimeOptionsValidator.cs @@ -0,0 +1,60 @@ +using ZB.MOM.WW.Configuration; + +namespace ZB.MOM.WW.ScadaBridge.SiteRuntime; + +/// +/// Validates 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 +/// deep inside actor construction with an +/// opaque message that never names the offending config key. Registered with +/// ValidateOnStart() so a bad ScadaBridge:SiteRuntime section fails +/// fast at boot with a clear, key-naming message. +/// +public sealed class SiteRuntimeOptionsValidator : OptionsValidatorBase +{ + /// + 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})."); + } +} diff --git a/src/ZB.MOM.WW.ScadaBridge.SiteRuntime/ZB.MOM.WW.ScadaBridge.SiteRuntime.csproj b/src/ZB.MOM.WW.ScadaBridge.SiteRuntime/ZB.MOM.WW.ScadaBridge.SiteRuntime.csproj index 17df3d89..ec65583d 100644 --- a/src/ZB.MOM.WW.ScadaBridge.SiteRuntime/ZB.MOM.WW.ScadaBridge.SiteRuntime.csproj +++ b/src/ZB.MOM.WW.ScadaBridge.SiteRuntime/ZB.MOM.WW.ScadaBridge.SiteRuntime.csproj @@ -19,6 +19,7 @@ + diff --git a/src/ZB.MOM.WW.ScadaBridge.StoreAndForward/StoreAndForwardOptionsValidator.cs b/src/ZB.MOM.WW.ScadaBridge.StoreAndForward/StoreAndForwardOptionsValidator.cs new file mode 100644 index 00000000..a9ce0f2f --- /dev/null +++ b/src/ZB.MOM.WW.ScadaBridge.StoreAndForward/StoreAndForwardOptionsValidator.cs @@ -0,0 +1,35 @@ +using ZB.MOM.WW.Configuration; + +namespace ZB.MOM.WW.ScadaBridge.StoreAndForward; + +/// +/// Validates at startup. The retry intervals +/// feed the background sweep timer (a zero/negative period trips +/// in the timer constructor) and the +/// SQLite path is opened for the S&F buffer; an empty path yields an opaque +/// connection failure at first enqueue. Registered with ValidateOnStart() +/// so a bad ScadaBridge:StoreAndForward section fails fast at boot with a +/// clear, key-naming message. +/// +public sealed class StoreAndForwardOptionsValidator : OptionsValidatorBase +{ + /// + protected override void Validate(ValidationBuilder builder, StoreAndForwardOptions options) + { + builder.RequireThat(!string.IsNullOrWhiteSpace(options.SqliteDbPath), + "ScadaBridge:StoreAndForward:SqliteDbPath must be a non-empty path; " + + "it is the SQLite file backing the store-and-forward buffer."); + + builder.RequireThat(options.DefaultRetryInterval > TimeSpan.Zero, + $"ScadaBridge:StoreAndForward:DefaultRetryInterval must be a positive duration " + + $"(was {options.DefaultRetryInterval}); it is the default per-message retry interval."); + + builder.RequireThat(options.RetryTimerInterval > TimeSpan.Zero, + $"ScadaBridge:StoreAndForward:RetryTimerInterval must be a positive duration " + + $"(was {options.RetryTimerInterval}); it is the background retry-sweep timer period."); + + builder.RequireThat(options.DefaultMaxRetries >= 0, + $"ScadaBridge:StoreAndForward:DefaultMaxRetries must be >= 0 " + + $"(was {options.DefaultMaxRetries})."); + } +} diff --git a/src/ZB.MOM.WW.ScadaBridge.StoreAndForward/ZB.MOM.WW.ScadaBridge.StoreAndForward.csproj b/src/ZB.MOM.WW.ScadaBridge.StoreAndForward/ZB.MOM.WW.ScadaBridge.StoreAndForward.csproj index 4f568eb4..df12328e 100644 --- a/src/ZB.MOM.WW.ScadaBridge.StoreAndForward/ZB.MOM.WW.ScadaBridge.StoreAndForward.csproj +++ b/src/ZB.MOM.WW.ScadaBridge.StoreAndForward/ZB.MOM.WW.ScadaBridge.StoreAndForward.csproj @@ -13,6 +13,7 @@ + diff --git a/tests/ZB.MOM.WW.ScadaBridge.SiteEventLogging.Tests/SiteEventLogOptionsValidatorTests.cs b/tests/ZB.MOM.WW.ScadaBridge.SiteEventLogging.Tests/SiteEventLogOptionsValidatorTests.cs new file mode 100644 index 00000000..865eca8d --- /dev/null +++ b/tests/ZB.MOM.WW.ScadaBridge.SiteEventLogging.Tests/SiteEventLogOptionsValidatorTests.cs @@ -0,0 +1,50 @@ +using Microsoft.Extensions.Options; + +namespace ZB.MOM.WW.ScadaBridge.SiteEventLogging.Tests; + +/// +/// retention/purge values drive the daily purge +/// PeriodicTimer (zero/negative trips its constructor) and the paging bounds gate +/// query result sizes. These tests assert the +/// rejects a bad +/// ScadaBridge:SiteEventLog section with a clear, key-naming message. +/// +public class SiteEventLogOptionsValidatorTests +{ + private static ValidateOptionsResult Validate(SiteEventLogOptions options) => + new SiteEventLogOptionsValidator().Validate(Options.DefaultName, options); + + [Fact] + public void DefaultOptions_AreValid() + { + var result = Validate(new SiteEventLogOptions()); + Assert.True(result.Succeeded, result.FailureMessage); + } + + [Fact] + public void ZeroRetentionDays_IsRejected() + { + var result = Validate(new SiteEventLogOptions { RetentionDays = 0 }); + + Assert.True(result.Failed); + Assert.Contains("RetentionDays", result.FailureMessage); + } + + [Fact] + public void ZeroPurgeInterval_IsRejected() + { + var result = Validate(new SiteEventLogOptions { PurgeInterval = TimeSpan.Zero }); + + Assert.True(result.Failed); + Assert.Contains("PurgeInterval", result.FailureMessage); + } + + [Fact] + public void MaxQueryPageSize_BelowQueryPageSize_IsRejected() + { + var result = Validate(new SiteEventLogOptions { QueryPageSize = 500, MaxQueryPageSize = 100 }); + + Assert.True(result.Failed); + Assert.Contains("MaxQueryPageSize", result.FailureMessage); + } +} diff --git a/tests/ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests/SiteRuntimeOptionsValidatorTests.cs b/tests/ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests/SiteRuntimeOptionsValidatorTests.cs new file mode 100644 index 00000000..e8bbf54e --- /dev/null +++ b/tests/ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests/SiteRuntimeOptionsValidatorTests.cs @@ -0,0 +1,60 @@ +using Microsoft.Extensions.Options; + +namespace ZB.MOM.WW.ScadaBridge.SiteRuntime.Tests; + +/// +/// values size the staggered Instance-Actor +/// startup batches, the dedicated script-execution thread scheduler, and the +/// site-wide stream buffer. A zero/negative count crashes actor construction with +/// an opaque ; these tests assert the +/// rejects a bad +/// ScadaBridge:SiteRuntime section with a clear, key-naming message. +/// +public class SiteRuntimeOptionsValidatorTests +{ + private static ValidateOptionsResult Validate(SiteRuntimeOptions options) => + new SiteRuntimeOptionsValidator().Validate(Options.DefaultName, options); + + [Fact] + public void DefaultOptions_AreValid() + { + var result = Validate(new SiteRuntimeOptions()); + Assert.True(result.Succeeded, result.FailureMessage); + } + + [Fact] + public void ZeroStartupBatchSize_IsRejected() + { + var result = Validate(new SiteRuntimeOptions { StartupBatchSize = 0 }); + + Assert.True(result.Failed); + Assert.Contains("StartupBatchSize", result.FailureMessage); + } + + [Fact] + public void ZeroScriptExecutionThreadCount_IsRejected() + { + var result = Validate(new SiteRuntimeOptions { ScriptExecutionThreadCount = 0 }); + + Assert.True(result.Failed); + Assert.Contains("ScriptExecutionThreadCount", result.FailureMessage); + } + + [Fact] + public void ZeroStreamBufferSize_IsRejected() + { + var result = Validate(new SiteRuntimeOptions { StreamBufferSize = 0 }); + + Assert.True(result.Failed); + Assert.Contains("StreamBufferSize", result.FailureMessage); + } + + [Fact] + public void NegativeStartupBatchDelayMs_IsRejected() + { + var result = Validate(new SiteRuntimeOptions { StartupBatchDelayMs = -1 }); + + Assert.True(result.Failed); + Assert.Contains("StartupBatchDelayMs", result.FailureMessage); + } +} diff --git a/tests/ZB.MOM.WW.ScadaBridge.StoreAndForward.Tests/StoreAndForwardOptionsValidatorTests.cs b/tests/ZB.MOM.WW.ScadaBridge.StoreAndForward.Tests/StoreAndForwardOptionsValidatorTests.cs new file mode 100644 index 00000000..5ffb3063 --- /dev/null +++ b/tests/ZB.MOM.WW.ScadaBridge.StoreAndForward.Tests/StoreAndForwardOptionsValidatorTests.cs @@ -0,0 +1,50 @@ +using Microsoft.Extensions.Options; + +namespace ZB.MOM.WW.ScadaBridge.StoreAndForward.Tests; + +/// +/// retry intervals feed the background sweep +/// timer (zero/negative trips the timer constructor) and the SQLite path backs the +/// buffer. These tests assert the +/// rejects a bad ScadaBridge:StoreAndForward section with a clear, +/// key-naming message rather than crashing later with an opaque exception. +/// +public class StoreAndForwardOptionsValidatorTests +{ + private static ValidateOptionsResult Validate(StoreAndForwardOptions options) => + new StoreAndForwardOptionsValidator().Validate(Options.DefaultName, options); + + [Fact] + public void DefaultOptions_AreValid() + { + var result = Validate(new StoreAndForwardOptions()); + Assert.True(result.Succeeded, result.FailureMessage); + } + + [Fact] + public void ZeroDefaultRetryInterval_IsRejected() + { + var result = Validate(new StoreAndForwardOptions { DefaultRetryInterval = TimeSpan.Zero }); + + Assert.True(result.Failed); + Assert.Contains("DefaultRetryInterval", result.FailureMessage); + } + + [Fact] + public void ZeroRetryTimerInterval_IsRejected() + { + var result = Validate(new StoreAndForwardOptions { RetryTimerInterval = TimeSpan.Zero }); + + Assert.True(result.Failed); + Assert.Contains("RetryTimerInterval", result.FailureMessage); + } + + [Fact] + public void EmptySqliteDbPath_IsRejected() + { + var result = Validate(new StoreAndForwardOptions { SqliteDbPath = "" }); + + Assert.True(result.Failed); + Assert.Contains("SqliteDbPath", result.FailureMessage); + } +}