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

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 is the FLOOR for the dedicated script-execution scheduler.");

        builder.RequireThat(options.ScriptExecutionMaxThreadCount >= options.ScriptExecutionThreadCount,
            $"ScadaBridge:SiteRuntime:ScriptExecutionMaxThreadCount must be >= ScriptExecutionThreadCount " +
            $"(was {options.ScriptExecutionMaxThreadCount} vs {options.ScriptExecutionThreadCount}); it is the " +
            "CEILING for the instance-scaled script-execution pool and a ceiling below the floor would " +
            "silently shrink the configured pool.");

        builder.RequireThat(options.TriggerEvalMaxConcurrency > 0,
            $"ScadaBridge:SiteRuntime:TriggerEvalMaxConcurrency must be greater than 0 " +
            $"(was {options.TriggerEvalMaxConcurrency}); it gates concurrent trigger-expression evaluations " +
            "and a zero gate would park every Expression trigger on the node forever.");

        builder.RequireThat(options.TriggerEvalTimeoutSeconds > 0,
            $"ScadaBridge:SiteRuntime:TriggerEvalTimeoutSeconds must be greater than 0 " +
            $"(was {options.TriggerEvalTimeoutSeconds}); it bounds a single trigger-expression evaluation " +
            "(measured from enqueue, so it also bounds gate-wait time).");

        builder.RequireThat(options.MaxConcurrentRunsPerScript > 0,
            $"ScadaBridge:SiteRuntime:MaxConcurrentRunsPerScript must be greater than 0 " +
            $"(was {options.MaxConcurrentRunsPerScript}); it caps concurrent runs per script and a zero cap " +
            "would shed every trigger.");

        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.TagSubscribeRetryIntervalMs > 0,
            $"ScadaBridge:SiteRuntime:TagSubscribeRetryIntervalMs must be greater than 0 " +
            $"(was {options.TagSubscribeRetryIntervalMs}); a zero interval hot-loops the tag-subscribe " +
            "retry and a negative one throws inside the Instance Actor's retry scheduling.");

        builder.RequireThat(options.TagSubscribeRetryMaxIntervalMs >= options.TagSubscribeRetryIntervalMs,
            $"ScadaBridge:SiteRuntime:TagSubscribeRetryMaxIntervalMs must be >= TagSubscribeRetryIntervalMs " +
            $"(was {options.TagSubscribeRetryMaxIntervalMs} vs {options.TagSubscribeRetryIntervalMs}); " +
            "it is the ceiling of the tag-subscribe retry backoff.");

        builder.RequireThat(options.TagSubscribeInFlightCeilingMs > 0,
            $"ScadaBridge:SiteRuntime:TagSubscribeInFlightCeilingMs must be greater than 0 " +
            $"(was {options.TagSubscribeInFlightCeilingMs}); it bounds how long an unanswered tag-subscribe " +
            "blocks a duplicate for the same connection.");

        builder.RequireThat(options.StuckScriptGraceMs >= 0,
            $"ScadaBridge:SiteRuntime:StuckScriptGraceMs must be >= 0 " +
            $"(was {options.StuckScriptGraceMs}); a negative grace throws inside the stuck-script watchdog's delay.");

        builder.RequireThat(options.AlarmPublishQueueCapacity > 0,
            $"ScadaBridge:SiteRuntime:AlarmPublishQueueCapacity must be greater than 0 " +
            $"(was {options.AlarmPublishQueueCapacity}); it bounds SiteStreamManager's dedicated alarm publish queue.");

        builder.RequireThat(options.ScriptRunSummaryIntervalSeconds >= 0,
            $"ScadaBridge:SiteRuntime:ScriptRunSummaryIntervalSeconds must be >= 0 " +
            $"(was {options.ScriptRunSummaryIntervalSeconds}); it is the ScriptRunSummaryRecorder " +
            "flush interval and a negative value throws inside its delay. 0 disables the flush.");

        builder.RequireThat(options.InstanceSweepIntervalSeconds >= 0,
            $"ScadaBridge:SiteRuntime:InstanceSweepIntervalSeconds must be >= 0 " +
            $"(was {options.InstanceSweepIntervalSeconds}); it is the Deployment Manager's " +
            "instance reconcile-sweep interval and a negative value throws inside the Akka timer. " +
            "0 disables the sweep, which reopens the replication-seeded-config and stale-revision " +
            "self-heals (deferred register rows 78 and 72).");

        builder.RequireThat(options.TraceArmWindowSeconds > 0,
            $"ScadaBridge:SiteRuntime:TraceArmWindowSeconds must be greater than 0 " +
            $"(was {options.TraceArmWindowSeconds}); it is how long the Instance Actor waits for the " +
            "device echo of a Flow Debugger traced write before the arm expires (design 2026-09-05 §5.3).");

        builder.RequireThat(options.MaxLogLinesPerRun > 0,
            $"ScadaBridge:SiteRuntime:MaxLogLinesPerRun must be greater than 0 " +
            $"(was {options.MaxLogLinesPerRun}); it is the per-run cap on Flow Debugger ScriptLog " +
            "rows a script's Log.* calls may produce (design 2026-09-09 D7), and a run that may " +
            "emit no lines at all cannot report its own truncation.");
    }
}