Joseph Doherty
55e1741075
Each node now re-writes its mirror-status row every SecretMirrorStatusRefreshInterval (10 min) as a heartbeat; SecretMirrorStatusReporter leaves off the health report and deletes any row not refreshed for SecretMirrorStatusStaleAfter (1 h, validated >= 2x the refresh). The delete is conditional on the checked_at it read, so a node that came back keeps its fresh row; a returning node re-writes its row on its first pass.
149 lines
9.7 KiB
C#
149 lines
9.7 KiB
C#
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.");
|
|
|
|
var files = options.ScriptFileAccess ?? new Scripts.ScriptFileAccessOptions();
|
|
builder.RequireThat(files.MaxFileBytes > 0 && files.MaxFileBytes <= Scripts.ScriptFileAccessOptions.MaxFileBytesCeiling,
|
|
$"ScadaBridge:SiteRuntime:ScriptFileAccess:MaxFileBytes must be between 1 and " +
|
|
$"{Scripts.ScriptFileAccessOptions.MaxFileBytesCeiling} (was {files.MaxFileBytes}); it caps one Files.* read.");
|
|
for (var i = 0; i < files.AllowedRoots.Count; i++)
|
|
{
|
|
var root = files.AllowedRoots[i];
|
|
builder.RequireThat(!string.IsNullOrWhiteSpace(root) && System.IO.Path.IsPathFullyQualified(root),
|
|
$"ScadaBridge:SiteRuntime:ScriptFileAccess:AllowedRoots:{i} must be an absolute directory path " +
|
|
$"(was '{root}'); a relative root would resolve against the service's working directory.");
|
|
}
|
|
|
|
builder.RequireThat(options.DeployedSecretsMirrorInterval > TimeSpan.Zero,
|
|
$"ScadaBridge:SiteRuntime:DeployedSecretsMirrorInterval must be a positive duration " +
|
|
$"(was {options.DeployedSecretsMirrorInterval}); it is the DeployedSecretsMirror " +
|
|
"reconcile PeriodicTimer period.");
|
|
builder.RequireThat(options.SecretMirrorStatusRefreshInterval > TimeSpan.Zero,
|
|
$"ScadaBridge:SiteRuntime:SecretMirrorStatusRefreshInterval must be a positive duration " +
|
|
$"(was {options.SecretMirrorStatusRefreshInterval}); it is how often each node re-writes its " +
|
|
"secret_mirror_status row.");
|
|
builder.RequireThat(options.SecretMirrorStatusStaleAfter >= options.SecretMirrorStatusRefreshInterval * 2,
|
|
$"ScadaBridge:SiteRuntime:SecretMirrorStatusStaleAfter (was {options.SecretMirrorStatusStaleAfter}) must be " +
|
|
$"at least twice SecretMirrorStatusRefreshInterval (was {options.SecretMirrorStatusRefreshInterval}); " +
|
|
"otherwise a live node's row could be pruned between two refreshes.");
|
|
}
|
|
}
|