ScadaBridge/src/ZB.MOM.WW.ScadaBridge.Communication/CommunicationOptionsValidator.cs

using ZB.MOM.WW.Configuration;

namespace ZB.MOM.WW.ScadaBridge.Communication;

/// <summary>
/// Validates <see cref="CommunicationOptions"/> at startup (ValidateOnStart) so a
/// malformed "ScadaBridge:Communication" appsettings section fails fast at boot with a
/// key-naming message instead of surfacing later at first Ask/gRPC use. Every
/// timeout feeds a per-pattern Ask deadline or a gRPC keepalive/stream-lifetime
/// setting, and a zero/negative value there produces an opaque runtime failure
/// far from the offending config key.
/// </summary>
public sealed class CommunicationOptionsValidator : OptionsValidatorBase<CommunicationOptions>
{
    /// <summary>
    /// Exclusive upper bound on <see cref="CommunicationOptions.GrpcStreamBatchWindow"/> —
    /// the end-to-end site→central event latency budget the target-scale load test asserts
    /// a P99 against. The coalescing window is the only latency batching introduces, so it
    /// must stay strictly inside that budget rather than consuming it whole.
    /// </summary>
    internal static readonly TimeSpan StreamBatchWindowCeiling = TimeSpan.FromMilliseconds(250);

    /// <inheritdoc />
    protected override void Validate(ValidationBuilder builder, CommunicationOptions options)
    {
        builder.RequireThat(options.DeploymentTimeout > TimeSpan.Zero,
            $"ScadaBridge:Communication:DeploymentTimeout must be a positive duration (was {options.DeploymentTimeout}).");

        builder.RequireThat(options.LifecycleTimeout > TimeSpan.Zero,
            $"ScadaBridge:Communication:LifecycleTimeout must be a positive duration (was {options.LifecycleTimeout}).");

        builder.RequireThat(options.ArtifactDeploymentTimeout > TimeSpan.Zero,
            $"ScadaBridge:Communication:ArtifactDeploymentTimeout must be a positive duration (was {options.ArtifactDeploymentTimeout}).");

        builder.RequireThat(options.QueryTimeout > TimeSpan.Zero,
            $"ScadaBridge:Communication:QueryTimeout must be a positive duration (was {options.QueryTimeout}).");

        builder.RequireThat(options.IntegrationTimeout > TimeSpan.Zero,
            $"ScadaBridge:Communication:IntegrationTimeout must be a positive duration (was {options.IntegrationTimeout}).");

        builder.RequireThat(options.DebugViewTimeout > TimeSpan.Zero,
            $"ScadaBridge:Communication:DebugViewTimeout must be a positive duration (was {options.DebugViewTimeout}).");

        builder.RequireThat(options.HealthReportTimeout > TimeSpan.Zero,
            $"ScadaBridge:Communication:HealthReportTimeout must be a positive duration (was {options.HealthReportTimeout}).");

        builder.RequireThat(options.NotificationForwardTimeout > TimeSpan.Zero,
            $"ScadaBridge:Communication:NotificationForwardTimeout must be a positive duration (was {options.NotificationForwardTimeout}).");

        // Outermost rung of the audit-ingest timeout ladder. It must be strictly greater than the
        // gRPC deadline / central Ask beneath it, or a slow-but-succeeding central write gets acked
        // to a caller that already gave up and re-sent the batch. See CommunicationOptions.
        builder.RequireThat(
            options.AuditForwardTimeout > Grpc.SiteStreamGrpcServer.AuditIngestAskTimeout,
            $"ScadaBridge:Communication:AuditForwardTimeout must be strictly greater than the "
            + $"central audit-ingest Ask timeout ({Grpc.SiteStreamGrpcServer.AuditIngestAskTimeout}) "
            + $"so the ingest timeout ladder stays monotonic (was {options.AuditForwardTimeout}).");

        builder.RequireThat(options.GrpcKeepAlivePingDelay > TimeSpan.Zero,
            $"ScadaBridge:Communication:GrpcKeepAlivePingDelay must be a positive duration (was {options.GrpcKeepAlivePingDelay}).");

        builder.RequireThat(options.GrpcKeepAlivePingTimeout > TimeSpan.Zero,
            $"ScadaBridge:Communication:GrpcKeepAlivePingTimeout must be a positive duration (was {options.GrpcKeepAlivePingTimeout}).");

        builder.RequireThat(options.GrpcMaxStreamLifetime > TimeSpan.Zero,
            $"ScadaBridge:Communication:GrpcMaxStreamLifetime must be a positive duration (was {options.GrpcMaxStreamLifetime}).");

        builder.RequireThat(options.TransportHeartbeatInterval > TimeSpan.Zero,
            $"ScadaBridge:Communication:TransportHeartbeatInterval must be a positive duration (was {options.TransportHeartbeatInterval}).");

        builder.RequireThat(options.ApplicationHeartbeatInterval > TimeSpan.Zero,
            $"ScadaBridge:Communication:ApplicationHeartbeatInterval must be a positive duration (was {options.ApplicationHeartbeatInterval}).");

        builder.RequireThat(options.TransportFailureThreshold > TimeSpan.Zero,
            $"ScadaBridge:Communication:TransportFailureThreshold must be a positive duration (was {options.TransportFailureThreshold}).");

        builder.RequireThat(options.PendingDeploymentTtl > TimeSpan.Zero,
            $"ScadaBridge:Communication:PendingDeploymentTtl must be a positive duration (was {options.PendingDeploymentTtl}).");

        builder.RequireThat(options.PendingDeploymentPurgeInterval > TimeSpan.Zero,
            $"ScadaBridge:Communication:PendingDeploymentPurgeInterval must be a positive duration (was {options.PendingDeploymentPurgeInterval}).");

        builder.RequireThat(options.GrpcMaxConcurrentStreams > 0,
            $"ScadaBridge:Communication:GrpcMaxConcurrentStreams must be positive (was {options.GrpcMaxConcurrentStreams}).");

        // ── Site→central stream event batching (R2) ─────────────────────────────
        // 1 is legal and means "disabled" (one event per frame, the un-negotiated shape).
        builder.RequireThat(options.GrpcStreamBatchMaxEvents > 0,
            $"ScadaBridge:Communication:GrpcStreamBatchMaxEvents must be positive — 1 disables "
            + $"batching (was {options.GrpcStreamBatchMaxEvents}).");

        // The coalescing window is the ONLY latency batching can add, and the target-scale
        // load test holds end-to-end event latency to a 250 ms P99. Validate it strictly
        // below that so a misconfigured window cannot silently spend the entire budget.
        builder.RequireThat(
            options.GrpcStreamBatchWindow >= TimeSpan.Zero
            && options.GrpcStreamBatchWindow < StreamBatchWindowCeiling,
            $"ScadaBridge:Communication:GrpcStreamBatchWindow must be non-negative and strictly "
            + $"below {StreamBatchWindowCeiling.TotalMilliseconds:0} ms (the end-to-end stream "
            + $"latency budget the coalescing window spends from); zero means \"pack only what is "
            + $"already queued\" (was {options.GrpcStreamBatchWindow}).");

        // The gRPC site→central transport needs at least one central endpoint to dial. gRPC is now
        // the only site→central transport (ClusterClient was removed in the migration's Phase 4), so
        // every site node must declare its central endpoints — there is no Akka fallback to ignore
        // the list. Central nodes leave it empty (they host CentralControlService, they don't dial it).
        builder.RequireThat(
            options.CentralGrpcEndpoints.All(e => !string.IsNullOrWhiteSpace(e)),
            "ScadaBridge:Communication:CentralGrpcEndpoints must not contain empty or whitespace "
            + "entries (a site node must list at least one central gRPC endpoint; central nodes "
            + "leave it empty).");

        // ── Aggregated live alarm cache (plan #10, Task 6) ───────────────────────
        // Linger drives a Timer dueTime; TimeSpan.Zero is valid (stop the aggregator
        // immediately when the last viewer leaves), only a negative value is invalid.
        builder.RequireThat(options.LiveAlarmCacheLinger >= TimeSpan.Zero,
            $"ScadaBridge:Communication:LiveAlarmCacheLinger must be zero or a positive duration (was {options.LiveAlarmCacheLinger}).");

        // Reconcile interval is a periodic timer cadence AND the start-retry cadence; a
        // zero/negative value would spin or never fire.
        builder.RequireThat(options.LiveAlarmCacheReconcileInterval > TimeSpan.Zero,
            $"ScadaBridge:Communication:LiveAlarmCacheReconcileInterval must be a positive duration (was {options.LiveAlarmCacheReconcileInterval}).");

        // Seed fan-out concurrency gates a SemaphoreSlim; at least 1, capped so a
        // fat-fingered config can't open an unbounded burst of cross-cluster Asks.
        builder.RequireThat(options.LiveAlarmCacheSeedConcurrency is >= 1 and <= 64,
            $"ScadaBridge:Communication:LiveAlarmCacheSeedConcurrency must be between 1 and 64 (was {options.LiveAlarmCacheSeedConcurrency}).");

        // Per-site viewer cap must admit at least one viewer, else the page could never go live.
        builder.RequireThat(options.LiveAlarmCacheMaxSubscribersPerSite >= 1,
            $"ScadaBridge:Communication:LiveAlarmCacheMaxSubscribersPerSite must be at least 1 (was {options.LiveAlarmCacheMaxSubscribersPerSite}).");

        // Publish-coalescing window drives a single-shot timer; TimeSpan.Zero is valid
        // (publish per delta — legacy), only a negative value is invalid.
        builder.RequireThat(options.LiveAlarmCachePublishCoalesce >= TimeSpan.Zero,
            $"ScadaBridge:Communication:LiveAlarmCachePublishCoalesce must be zero or a positive duration (was {options.LiveAlarmCachePublishCoalesce}).");
    }
}