ScadaBridge/src/ZB.MOM.WW.ScadaBridge.DataConnectionLayer/Actors/DataConnectionManagerActor.cs

using ZB.MOM.WW.ScadaBridge.DataConnectionLayer.Logging;
using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Services;
using Akka.Actor;
using Akka.Event;
using Microsoft.Extensions.Logging.Abstractions;
using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Protocol;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.DataConnection;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
using ZB.MOM.WW.ScadaBridge.Commons.Observability;
using ZB.MOM.WW.ScadaBridge.Commons.Serialization;
using ZB.MOM.WW.ScadaBridge.Commons.Types.DataConnections;
using ZB.MOM.WW.ScadaBridge.DataConnectionLayer.Adapters;
using ZB.MOM.WW.ScadaBridge.HealthMonitoring;
using ZB.MOM.WW.ScadaBridge.SiteEventLogging;

namespace ZB.MOM.WW.ScadaBridge.DataConnectionLayer.Actors;

/// <summary>
/// Protocol extensibility — manages DataConnectionActor instances.
/// Routes messages to the correct connection actor based on connection name.
/// Adding a new protocol = implement IDataConnection + register with IDataConnectionFactory.
/// </summary>
public class DataConnectionManagerActor : ReceiveActor
{
    // ScadaBridge#120: execution-aware, so a line logged while serving a correlated message keeps its ExecutionId.
    private readonly ILoggingAdapter _log = ExecutionAwareLogging.GetLogger(Context);
    private readonly IDataConnectionFactory _factory;
    private readonly DataConnectionOptions _options;
    private readonly ISiteHealthCollector _healthCollector;
    private readonly ISiteEventLogger? _siteEventLogger;
    // Deployment-wide OPC UA application identity / cert-store paths — the same
    // global options the DataConnectionFactory feeds to RealOpcUaClient when creating OPC
    // UA connections. Needed by the verify-endpoint probe (VerifyEndpointCommand), which
    // builds an ApplicationConfiguration directly rather than through a connection actor.
    private readonly OpcUaGlobalOptions _opcUaGlobalOptions;
    private readonly Microsoft.Extensions.Logging.ILogger _probeLogger;
    private readonly Dictionary<string, IActorRef> _connectionActors = new();

    // Children this manager has STOPPED (RemoveConnectionCommand) but whose Terminated has not
    // arrived yet, keyed by actor name. Akka keeps a stopping child's name reserved until it has
    // fully terminated, so a create of the same name inside that dispose window must wait for
    // Terminated rather than be refused as a collision (review 2026-10-21 follow-up L2).
    private readonly Dictionary<string, IActorRef> _stoppingChildren = new();

    // Creates queued behind a stopping child of the same actor name; the latest command wins.
    private readonly Dictionary<string, CreateConnectionCommand> _queuedCreates = new();

    /// <summary>
    /// Initializes a new <see cref="DataConnectionManagerActor"/> with the required dependencies.
    /// </summary>
    /// <param name="factory">Factory used to create protocol-specific data connection adapters.</param>
    /// <param name="options">Configuration options for data connections.</param>
    /// <param name="healthCollector">Collector for site health metrics reported by connection actors.</param>
    /// <param name="siteEventLogger">Optional logger for site event entries; null disables site event logging.</param>
    /// <param name="opcUaGlobalOptions">
    /// Deployment-wide OPC UA application identity / cert-store paths used by the
    /// verify-endpoint probe; null falls back to defaults (mirrors
    /// <see cref="DataConnectionFactory"/>'s default-options constructor).
    /// </param>
    /// <param name="probeLogger">
    /// Logger for the verify-endpoint probe; null discards. Gitea #121: a secured probe is
    /// usually what first creates the node's OPC UA application certificate, and that
    /// creation's Warning (with the thumbprint every server must trust) must reach the node log.
    /// </param>
    public DataConnectionManagerActor(
        IDataConnectionFactory factory,
        DataConnectionOptions options,
        ISiteHealthCollector healthCollector,
        ISiteEventLogger? siteEventLogger = null,
        OpcUaGlobalOptions? opcUaGlobalOptions = null,
        Microsoft.Extensions.Logging.ILogger? probeLogger = null)
    {
        _probeLogger = probeLogger ?? NullLogger.Instance;
        _factory = factory;
        _options = options;
        _healthCollector = healthCollector;
        _siteEventLogger = siteEventLogger;
        _opcUaGlobalOptions = opcUaGlobalOptions ?? new OpcUaGlobalOptions();

        Receive<CreateConnectionCommand>(HandleCreateConnection);
        Receive<ReconfigureConnectionCommand>(HandleReconfigureConnection);
        Receive<SubscribeTagsRequest>(HandleRoute);
        Receive<UnsubscribeTagsRequest>(HandleRoute);
        Receive<SubscribeAlarmsRequest>(HandleRouteAlarms);
        Receive<UnsubscribeAlarmsRequest>(HandleRouteAlarms);
        Receive<WriteTagRequest>(HandleRouteWrite);
        Receive<WriteTagBatchRequest>(HandleRouteWriteBatch);
        Receive<RemoveConnectionCommand>(HandleRemoveConnection);
        Receive<GetAllHealthReports>(HandleGetAllHealthReports);
        Receive<BrowseNodeCommand>(HandleBrowse);
        Receive<SearchAddressSpaceCommand>(HandleSearch);
        Receive<ReadTagValuesCommand>(HandleReadTagValues);
        Receive<VerifyEndpointCommand>(HandleVerifyEndpoint);
        Receive<Terminated>(HandleChildTerminated);
    }

    private void HandleCreateConnection(CreateConnectionCommand command)
    {
        if (_connectionActors.ContainsKey(command.ConnectionName))
        {
            _log.Warning("Connection {0} already exists", command.ConnectionName);
            return;
        }

        var actorName = ConnectionActorNames.Sanitize(command.ConnectionName);
        if (_stoppingChildren.ContainsKey(actorName))
        {
            // The previous actor of this name is still terminating (a Remove→Create redeploy):
            // its name is reserved until Terminated, so queue the create rather than refuse it —
            // a refusal is permanent, because the deployment manager has already recorded the
            // config hash and will not resend (review 2026-10-21 follow-up L2).
            if (_queuedCreates.TryGetValue(actorName, out var queued)
                && !string.Equals(queued.ConnectionName, command.ConnectionName, StringComparison.Ordinal))
            {
                RefuseCollision(command, actorName,
                    $"actor name [{actorName}] is already claimed by queued connection '{queued.ConnectionName}'");
                return;
            }

            _queuedCreates[actorName] = command;
            _log.Info(
                "Connection {0} queued: the previous actor '{1}' is still stopping; it is created on Terminated",
                command.ConnectionName, actorName);
            return;
        }

        // Factory creates the correct adapter based on protocol type
        var adapter = _factory.Create(command.ProtocolType, command.PrimaryConnectionDetails);

        var props = Props.Create(() => new DataConnectionActor(
            command.ConnectionName, adapter, _options, _healthCollector,
            _factory, command.ProtocolType,
            command.PrimaryConnectionDetails,
            command.BackupConnectionDetails,
            command.FailoverRetryCount,
            _siteEventLogger));

        // Sanitize name for Akka actor path — ASCII only, never a leading '$' (see
        // ConnectionActorNames). Two connection names can still sanitise to the same actor name
        // ("PLC A" / "PLC-A"), and ActorOf throws synchronously on that (or on any name Akka
        // refuses): that must fail THIS connection only, never escape to the supervisor and
        // restart the whole manager with every live connection (review 2026-10-21, lane A M2).
        IActorRef actorRef;
        try
        {
            // Only a LIVE child of this name is a collision; a child this manager stopped was
            // handled above by queueing.
            if (!Context.Child(actorName).IsNobody())
                throw new InvalidActorNameException(
                    $"actor name [{actorName}] is already used by another connection");
            actorRef = Context.ActorOf(props, actorName);
        }
        catch (InvalidActorNameException ex)
        {
            RefuseCollision(command, actorName, ex.Message);
            adapter.DisposeAsync().AsTask().ContinueWith(_ => { });
            return;
        }

        _connectionActors[command.ConnectionName] = actorRef;

        _log.Info("Created DataConnectionActor for {0} (protocol={1})",
            command.ConnectionName, command.ProtocolType);
    }

    /// <summary>
    /// Applies a new configuration to a LIVE connection actor (deferred register row 97) by
    /// forwarding the command to it — the actor swaps its adapter in place and re-issues every
    /// subscription it holds, rather than being stopped and rebuilt (which would silently strand
    /// every subscriber; see <see cref="ReconfigureConnectionCommand"/>).
    ///
    /// <para>
    /// A name this manager does not hold falls back to <see cref="HandleCreateConnection"/>, so
    /// the command is safe regardless of manager state: a sender whose view of which connections
    /// exist is stale (a fresh singleton incarnation, a node that has just taken over) still
    /// converges on the intended configuration in one message.
    /// </para>
    /// </summary>
    private void HandleReconfigureConnection(ReconfigureConnectionCommand command)
    {
        if (_connectionActors.TryGetValue(command.ConnectionName, out var actor))
        {
            _log.Info("Reconfiguring DataConnectionActor for {0} in place (protocol={1})",
                command.ConnectionName, command.ProtocolType);
            actor.Forward(command);
            return;
        }

        _log.Info(
            "Reconfigure for {0} arrived with no live connection actor — creating it instead",
            command.ConnectionName);
        HandleCreateConnection(new CreateConnectionCommand(
            command.ConnectionName,
            command.ProtocolType,
            command.PrimaryConnectionDetails,
            command.BackupConnectionDetails,
            command.FailoverRetryCount));
    }

    private void HandleRoute(SubscribeTagsRequest request)
    {
        if (_connectionActors.TryGetValue(request.ConnectionName, out var actor))
            actor.Forward(request);
        else
        {
            _log.Warning("No connection actor for {0}", request.ConnectionName);
            Sender.Tell(new SubscribeTagsResponse(
                request.CorrelationId, request.InstanceUniqueName, false,
                $"Unknown connection: {request.ConnectionName}", DateTimeOffset.UtcNow));
        }
    }

    private void HandleRoute(UnsubscribeTagsRequest request)
    {
        if (_connectionActors.TryGetValue(request.ConnectionName, out var actor))
            actor.Forward(request);
        else
            _log.Warning("No connection actor for {0} during unsubscribe", request.ConnectionName);
    }

    /// <summary>
    /// Routes a native alarm subscribe to the <see cref="DataConnectionActor"/> that owns
    /// the named connection (the NativeAlarmActor sends here, not to the child directly).
    /// </summary>
    private void HandleRouteAlarms(SubscribeAlarmsRequest request)
    {
        if (_connectionActors.TryGetValue(request.ConnectionName, out var actor))
            actor.Forward(request);
        else
        {
            _log.Warning("No connection actor for {0} during alarm subscribe", request.ConnectionName);
            Sender.Tell(new SubscribeAlarmsResponse(
                request.CorrelationId, request.InstanceUniqueName, false,
                $"Unknown connection: {request.ConnectionName}", DateTimeOffset.UtcNow));
        }
    }

    private void HandleRouteAlarms(UnsubscribeAlarmsRequest request)
    {
        if (_connectionActors.TryGetValue(request.ConnectionName, out var actor))
            actor.Forward(request);
        else
            _log.Warning("No connection actor for {0} during alarm unsubscribe", request.ConnectionName);
    }

    /// <summary>
    /// ScadaBridge#56: while handling a message sent on behalf of an execution
    /// (<see cref="IExecutionCorrelated"/>), every line this actor logs - and every line logged by
    /// a continuation it starts - carries that execution's <c>ExecutionId</c>. A message that names
    /// no execution costs one type test.
    /// </summary>
    /// <remarks>
    /// Enrichment reaches lines written through a Serilog-backed <c>ILogger</c> - here, the protocol
    /// adapter's own logging on the write path, whose <c>WriteAsync</c> starts inside this scope. This
    /// actor's own Akka <c>_log</c> lines are tagged too (Gitea #120): the execution-aware adapter
    /// records the id when the line is logged, and the host's Serilog logger actor re-pushes it.
    /// </remarks>
    /// <param name="receive">The behaviour that handles the message.</param>
    /// <param name="message">The message.</param>
    /// <returns>Whether the message was handled.</returns>
    protected override bool AroundReceive(Receive receive, object message)
    {
        using (ExecutionLogContext.PushFor(message))
            return base.AroundReceive(receive, message);
    }

    private void HandleRouteWrite(WriteTagRequest request)
    {
        if (_connectionActors.TryGetValue(request.ConnectionName, out var actor))
            actor.Forward(request);
        else
        {
            _log.Warning("No connection actor for {0}", request.ConnectionName);
            Sender.Tell(new WriteTagResponse(
                request.CorrelationId, false,
                $"Unknown connection: {request.ConnectionName}", DateTimeOffset.UtcNow));
        }
    }

    /// <summary>
    /// Routes a <see cref="WriteTagBatchRequest"/> to the child
    /// <see cref="DataConnectionActor"/> that owns the named connection — the batch
    /// counterpart of <see cref="HandleRouteWrite"/>. The manager owns only the
    /// unknown-connection failure (the same split as every other routed message);
    /// the child resolves connected/not-connected and the per-write outcomes.
    /// </summary>
    private void HandleRouteWriteBatch(WriteTagBatchRequest request)
    {
        if (_connectionActors.TryGetValue(request.ConnectionName, out var actor))
            actor.Forward(request);
        else
        {
            _log.Warning("No connection actor for {0}", request.ConnectionName);
            Sender.Tell(new WriteTagBatchResponse(
                request.CorrelationId, false,
                $"Unknown connection: {request.ConnectionName}", DateTimeOffset.UtcNow));
        }
    }

    /// <summary>
    /// Routes a <see cref="BrowseNodeCommand"/> from the central UI's OPC UA
    /// Tag Browser to the child <see cref="DataConnectionActor"/> that owns the
    /// named connection. The manager is the only actor that knows whether a
    /// connection exists at this site — so it owns the
    /// <see cref="BrowseFailureKind.ConnectionNotFound"/> failure. Everything
    /// else (capability check, session state, server errors) lives inside the
    /// child where the adapter is held.
    /// </summary>
    private void HandleBrowse(BrowseNodeCommand command)
    {
        if (_connectionActors.TryGetValue(command.ConnectionName, out var actor))
        {
            actor.Forward(command);
        }
        else
        {
            _log.Warning("No connection actor for {0} during browse", command.ConnectionName);
            Sender.Tell(new BrowseNodeResult(
                Array.Empty<BrowseNode>(),
                Truncated: false,
                new BrowseFailure(
                    BrowseFailureKind.ConnectionNotFound,
                    $"No data connection named '{command.ConnectionName}' at this site.")));
        }
    }

    /// <summary>
    /// Routes a <see cref="SearchAddressSpaceCommand"/> from the central UI's OPC
    /// UA tag picker to the child <see cref="DataConnectionActor"/> that owns the
    /// named connection — the address-space analogue of <see cref="HandleBrowse"/>.
    /// Same split: the manager owns <see cref="BrowseFailureKind.ConnectionNotFound"/>
    /// (only it knows the per-site connection set); the capability check and every
    /// other failure live inside the child where the adapter is held.
    /// </summary>
    private void HandleSearch(SearchAddressSpaceCommand command)
    {
        if (_connectionActors.TryGetValue(command.ConnectionName, out var actor))
        {
            actor.Forward(command);
        }
        else
        {
            _log.Warning("No connection actor for {0} during search", command.ConnectionName);
            Sender.Tell(new SearchAddressSpaceResult(
                Array.Empty<AddressSpaceMatch>(),
                CapReached: false,
                new BrowseFailure(
                    BrowseFailureKind.ConnectionNotFound,
                    $"No data connection named '{command.ConnectionName}' at this site.")));
        }
    }

    /// <summary>
    /// Routes a <see cref="ReadTagValuesCommand"/> from the CentralUI's Test
    /// Bindings dialog to the child <see cref="DataConnectionActor"/> that
    /// owns the named connection. Same split as <see cref="HandleBrowse"/> —
    /// the manager owns
    /// <see cref="ReadTagValuesFailureKind.ConnectionNotFound"/> because it is
    /// the only actor with site-level visibility; every other failure
    /// (not connected, server error, timeout) is resolved by the child where
    /// the adapter is held.
    /// </summary>
    private void HandleReadTagValues(ReadTagValuesCommand command)
    {
        if (_connectionActors.TryGetValue(command.ConnectionName, out var actor))
        {
            actor.Forward(command);
        }
        else
        {
            _log.Warning("No connection actor for {0} during test-bindings read", command.ConnectionName);
            Sender.Tell(new ReadTagValuesResult(
                Array.Empty<TagReadOutcome>(),
                new ReadTagValuesFailure(
                    ReadTagValuesFailureKind.ConnectionNotFound,
                    $"No data connection named '{command.ConnectionName}' at this site.")));
        }
    }

    /// <summary>
    /// Handles a <see cref="VerifyEndpointCommand"/> from the Central UI's "Verify"
    /// action — probes the endpoint config WITHOUT persisting it (connect → capture an
    /// untrusted cert → disconnect) and pipes a structured <see cref="VerifyEndpointResult"/>
    /// back to the sender. Verify does NOT require an existing connection (the config may be
    /// brand-new and unsaved), so — unlike the routed browse/read handlers — it does not look
    /// up a connection actor; it runs the probe directly. Only OPC UA is supported today.
    /// </summary>
    private void HandleVerifyEndpoint(VerifyEndpointCommand cmd)
    {
        if (!string.Equals(cmd.Protocol, "OpcUa", StringComparison.OrdinalIgnoreCase))
        {
            Sender.Tell(new VerifyEndpointResult(
                false, VerifyFailureKind.ServerError,
                "Verify is only supported for OPC UA connections.", null));
            return;
        }

        OpcUaEndpointConfig config;
        try
        {
            (config, _) = OpcUaEndpointConfigSerializer.Deserialize(cmd.ConfigJson);
        }
        catch (Exception ex)
        {
            // Defensive: Deserialize is designed not to throw (it classifies Malformed), but
            // a verify must never crash the manager — surface the parse failure as ServerError.
            _log.Warning(ex, "Verify config for {0} could not be parsed", cmd.ConnectionName);
            Sender.Tell(new VerifyEndpointResult(
                false, VerifyFailureKind.ServerError,
                "The endpoint configuration could not be parsed.", null));
            return;
        }

        RealOpcUaClient
            .VerifyEndpointAsync(config, _opcUaGlobalOptions, _probeLogger, TimeSpan.FromSeconds(6), CancellationToken.None)
            .PipeTo(Sender);
    }

    private void RefuseCollision(CreateConnectionCommand command, string actorName, string reason)
    {
        _log.Error(
            "Connection {0} not created: its actor name '{1}' is invalid or already used by another " +
            "connection ({2}). Rename the connection so its name differs in more than spaces/symbols.",
            command.ConnectionName, actorName, reason);
        if (_siteEventLogger != null)
        {
            _ = _siteEventLogger.LogEventAsync(
                "connection", "Error", null, command.ConnectionName,
                $"Connection not created — runtime actor name '{actorName}' is invalid or already in use",
                reason);
        }
    }

    /// <summary>
    /// A child this manager stopped has fully terminated, releasing its actor name: run any
    /// create that was queued behind it (review 2026-10-21 follow-up L2).
    /// </summary>
    private void HandleChildTerminated(Terminated terminated)
    {
        string? actorName = null;
        foreach (var (name, child) in _stoppingChildren)
        {
            if (child.Equals(terminated.ActorRef))
            {
                actorName = name;
                break;
            }
        }

        if (actorName is null)
            return;

        _stoppingChildren.Remove(actorName);
        if (_queuedCreates.Remove(actorName, out var queued))
        {
            _log.Info("Previous actor '{0}' terminated — creating queued connection {1}",
                actorName, queued.ConnectionName);
            HandleCreateConnection(queued);
        }
    }

    private void HandleRemoveConnection(RemoveConnectionCommand command)
    {
        // A Remove for a connection whose create is still queued behind a stopping child
        // cancels that create — the connection is meant to be gone.
        var removedActorName = ConnectionActorNames.Sanitize(command.ConnectionName);
        if (_queuedCreates.TryGetValue(removedActorName, out var queued)
            && string.Equals(queued.ConnectionName, command.ConnectionName, StringComparison.Ordinal))
        {
            _queuedCreates.Remove(removedActorName);
            _log.Info("Queued create for connection {0} cancelled by remove", command.ConnectionName);
        }

        if (_connectionActors.TryGetValue(command.ConnectionName, out var actor))
        {
            // Watch before stopping so the Terminated that frees the actor name reaches us.
            Context.Watch(actor);
            _stoppingChildren[actor.Path.Name] = actor;
            Context.Stop(actor);
            _connectionActors.Remove(command.ConnectionName);
            _healthCollector.RemoveConnection(command.ConnectionName);
            // Register row 54 — drop it from the gauges too, so an undeployed connection
            // stops counting toward the total instead of lingering as a permanently
            // not-connected row that would hold the connected < total alert on forever.
            ScadaBridgeTelemetry.RemoveDataConnection(command.ConnectionName);
            _log.Info("Removed DataConnectionActor for {0}", command.ConnectionName);
        }
    }

    private void HandleGetAllHealthReports(GetAllHealthReports _)
    {
        // Forward health report requests to all connection actors
        foreach (var actor in _connectionActors.Values)
        {
            actor.Forward(new DataConnectionActor.GetHealthReport());
        }
    }

    /// <inheritdoc />
    protected override SupervisorStrategy SupervisorStrategy()
    {
        return new OneForOneStrategy(
            maxNrOfRetries: 10,
            withinTimeRange: TimeSpan.FromMinutes(1),
            decider: Decider.From(ex =>
            {
                _log.Warning(ex, "DataConnectionActor threw exception, resuming (subscription state preserved)");
                return Directive.Resume;
            }));
    }
}

/// <summary>
/// Command to remove a data connection actor.
/// </summary>
public record RemoveConnectionCommand(string ConnectionName);

/// <summary>
/// Request for health reports from all active connections.
/// </summary>
public record GetAllHealthReports;