mxaccessgw/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/AlarmDispatcher.cs

using System;
using System.Collections.Generic;
using ZB.MOM.WW.MxGateway.Contracts.Proto;

namespace ZB.MOM.WW.MxGateway.Worker.MxAccess;

/// <summary>
///     In-process dispatcher that owns the lifetime of an
///     <see cref="IMxAccessAlarmConsumer"/> + <see cref="MxAccessAlarmEventSink"/>
///     pair, and wires the consumer's <c>AlarmTransitionEmitted</c> stream
///     onto the sink's <c>EnqueueTransition</c> path so transitions land on
///     the worker's <see cref="MxAccessEventQueue"/> as proto
///     <see cref="OnAlarmTransitionEvent"/> messages ready for IPC dispatch.
/// </summary>
/// <remarks>
///     <para>
///         The dispatcher carries the consumer→sink→queue pipeline. The
///         worker's IPC layer issues <c>SubscribeAlarmsCommand</c> /
///         <c>AcknowledgeAlarmCommand</c> / <c>QueryActiveAlarmsCommand</c>
///         through <see cref="AlarmCommandHandler"/>, which owns one
///         dispatcher per session. Acknowledgement resolves the alarm to its
///         MXAccess ack item through the consumer and hands the write to the
///         <see cref="IAlarmAckWriter"/>, which authenticates as the operator.
///     </para>
///     <para>
///         Threading: <see cref="WnWrapAlarmConsumer"/> owns no internal
///         timer — the worker's STA drives polling via
///         <c>StaRuntime.InvokeAsync(() =&gt; PollOnce())</c>, so the
///         consumer's <c>AlarmTransitionEmitted</c> event fires on the STA.
///         The dispatcher is purely a pass-through, so it inherits that
///         thread. Fan-out into <c>EnqueueTransition</c> uses the
///         thread-safe <see cref="MxAccessEventQueue.Enqueue"/>.
///     </para>
/// </remarks>
public sealed class AlarmDispatcher : IDisposable
{
    private readonly IMxAccessAlarmConsumer consumer;
    private readonly MxAccessAlarmEventSink sink;
    private readonly string sessionId;
    private readonly EventHandler<MxAlarmTransitionEvent> handler;
    private readonly IAlarmAckWriter ackWriter;
    private bool disposed;

    /// <summary>Initializes a new alarm dispatcher for the given consumer, sink, session ID and ack writer.</summary>
    /// <param name="consumer">The alarm consumer.</param>
    /// <param name="sink">The alarm event sink.</param>
    /// <param name="sessionId">The session identifier.</param>
    /// <param name="ackWriter">
    ///     Writes the resolved ack item as the authenticated operator. Owned by
    ///     the caller (<see cref="AlarmCommandHandler"/>), which disposes it; the
    ///     dispatcher never does, so the writer's registered MXAccess server
    ///     outlives an unsubscribe/resubscribe cycle.
    /// </param>
    public AlarmDispatcher(
        IMxAccessAlarmConsumer consumer,
        MxAccessAlarmEventSink sink,
        string sessionId,
        IAlarmAckWriter ackWriter)
    {
        this.consumer = consumer ?? throw new ArgumentNullException(nameof(consumer));
        this.sink = sink ?? throw new ArgumentNullException(nameof(sink));
        this.sessionId = sessionId ?? string.Empty;
        this.ackWriter = ackWriter ?? throw new ArgumentNullException(nameof(ackWriter));
        // Sink.Attach is the seam that propagates the session id onto the
        // proto SessionId field of every emitted MxEvent. Pass the consumer
        // as the "associated COM object" — sink ignores the object reference
        // for the alarm path, but the existing IMxAccessEventSink contract
        // requires a non-null first arg.
        this.sink.Attach(this.consumer, this.sessionId);
        this.handler = OnTransition;
        consumer.AlarmTransitionEmitted += handler;
    }

    /// <summary>
    ///     Begin polling the configured AVEVA alarm provider for
    ///     transitions. The supplied subscription expression follows the
    ///     canonical <c>\\&lt;machine&gt;\Galaxy!&lt;area&gt;</c> format.
    /// </summary>
    /// <param name="subscription">The subscription expression (e.g., <c>\\HOST\Galaxy!Area</c>).</param>
    public void Subscribe(string subscription)
    {
        if (disposed) throw new ObjectDisposedException(nameof(AlarmDispatcher));
        consumer.Subscribe(subscription);
    }

    /// <summary>Acknowledges the alarm with the given GUID by writing its ack item as the operator.</summary>
    /// <param name="alarmGuid">The alarm GUID.</param>
    /// <param name="ackComment">The acknowledgement comment.</param>
    /// <param name="ackOperator">The operator to authenticate as.</param>
    /// <returns>The outcome.</returns>
    public AlarmAckResult Acknowledge(Guid alarmGuid, string ackComment, AlarmAckOperator ackOperator)
    {
        if (disposed) throw new ObjectDisposedException(nameof(AlarmDispatcher));
        AlarmAckTarget target = consumer.ResolveAckTarget(alarmGuid);
        return target.Found
            ? ackWriter.Acknowledge(target.ItemAddress, ackComment, ackOperator)
            : AlarmAckResult.FromTarget(target);
    }

    /// <summary>Acknowledges the alarm identified by name/provider/group as the operator.</summary>
    /// <param name="alarmName">The tag/alarm name.</param>
    /// <param name="providerName">The provider.</param>
    /// <param name="groupName">The group/area.</param>
    /// <param name="ackComment">The acknowledgement comment.</param>
    /// <param name="ackOperator">The operator to authenticate as.</param>
    /// <returns>The outcome.</returns>
    public AlarmAckResult AcknowledgeByName(
        string alarmName, string providerName, string groupName, string ackComment, AlarmAckOperator ackOperator)
    {
        if (disposed) throw new ObjectDisposedException(nameof(AlarmDispatcher));
        AlarmAckTarget target = consumer.ResolveAckTargetByName(alarmName, providerName, groupName);
        return target.Found
            ? ackWriter.Acknowledge(target.ItemAddress, ackComment, ackOperator)
            : AlarmAckResult.FromTarget(target);
    }

    /// <summary>
    ///     Drives a single synchronous poll of the underlying consumer.
    ///     Must be called on the STA thread that owns the wnwrap COM object.
    ///     No-op if the dispatcher has been disposed.
    /// </summary>
    public void PollOnce()
    {
        if (disposed) return;
        consumer.PollOnce();
    }

    /// <summary>
    ///     Snapshot the currently-active alarm set as
    ///     <see cref="ActiveAlarmSnapshot"/> protos for the
    ///     <c>QueryActiveAlarms</c> RPC's ConditionRefresh stream.
    /// </summary>
    /// <param name="truncated">
    ///     Receives whether the fetch behind the snapshot hit the per-fetch cap,
    ///     so the returned set may omit active alarms. Forwarded from the single
    ///     atomic consumer read, and stamped onto every returned record as
    ///     <c>ActiveAlarmSnapshot.FromTruncatedSnapshot</c>. Also returned
    ///     separately because a snapshot of zero records still has to report it.
    /// </param>
    /// <returns>The currently active alarm snapshots.</returns>
    public IReadOnlyList<ActiveAlarmSnapshot> SnapshotActiveAlarms(out bool truncated)
    {
        if (disposed) throw new ObjectDisposedException(nameof(AlarmDispatcher));
        // One consumer call yields the records and the verdict together, under a
        // single acquisition of the consumer's snapshot lock. Reading them
        // separately would let a poll interleave and pair a stale not-truncated
        // verdict with a capped snapshot — a set that reads complete while
        // missing actives. The atomicity is structural here, not a consequence of
        // the STA happening to serialize the two calls.
        IReadOnlyList<MxAlarmSnapshotRecord> records = consumer.SnapshotActiveAlarms(out truncated);
        if (records.Count == 0) return Array.Empty<ActiveAlarmSnapshot>();
        List<ActiveAlarmSnapshot> snapshots = new List<ActiveAlarmSnapshot>(records.Count);
        foreach (MxAlarmSnapshotRecord record in records)
        {
            snapshots.Add(MapToSnapshot(record, truncated));
        }
        return snapshots;
    }

    private void OnTransition(object? sender, MxAlarmTransitionEvent transition)
    {
        if (disposed) return;
        if (transition is null) return;

        MxAlarmSnapshotRecord record = transition.Record;
        AlarmTransitionKind kind = AlarmRecordTransitionMapper.MapTransition(
            transition.PreviousState, record.State);
        if (kind == AlarmTransitionKind.Unspecified) return;

        string fullReference = AlarmRecordTransitionMapper.ComposeFullReference(
            record.ProviderName, record.Group, record.TagName);
        bool useAck = kind == AlarmTransitionKind.Acknowledge && HasAckAttribution(record);

        sink.EnqueueTransition(
            alarmFullReference: fullReference,
            sourceObjectReference: record.TagName,
            alarmTypeName: record.Type,
            transitionKind: kind,
            severity: record.Priority,
            originalRaiseTimestampUtc: null,
            transitionTimestampUtc: record.TransitionTimestampUtc,
            operatorUser: useAck ? record.AckOperatorName : record.OperatorName,
            operatorComment: useAck ? record.AckComment : record.AlarmComment,
            category: record.Group,
            description: string.Empty,
            degraded: record.Degraded);
    }

    private static bool HasAckAttribution(MxAlarmSnapshotRecord record) =>
        !string.IsNullOrEmpty(record.AckOperatorName) || !string.IsNullOrEmpty(record.AckComment);

    private static bool IsAcked(MxAlarmStateKind state) =>
        state == MxAlarmStateKind.AckAlm || state == MxAlarmStateKind.AckRtn;

    private static ActiveAlarmSnapshot MapToSnapshot(MxAlarmSnapshotRecord record, bool truncated)
    {
        bool useAck = IsAcked(record.State) && HasAckAttribution(record);
        ActiveAlarmSnapshot snapshot = new ActiveAlarmSnapshot
        {
            AlarmFullReference = AlarmRecordTransitionMapper.ComposeFullReference(
                record.ProviderName, record.Group, record.TagName),
            SourceObjectReference = record.TagName,
            AlarmTypeName = record.Type,
            CurrentState = MapConditionState(record.State),
            Severity = record.Priority,
            OperatorUser = useAck ? record.AckOperatorName : record.OperatorName,
            OperatorComment = useAck ? record.AckComment : record.AlarmComment,
            Category = record.Group,
            Description = string.Empty,
            Degraded = record.Degraded,
            SourceProvider = record.Degraded ? AlarmProviderMode.Subtag : AlarmProviderMode.Alarmmgr,
            // Set-level status, stamped identically on every record of the
            // snapshot: QueryActiveAlarms streams bare ActiveAlarmSnapshot
            // messages with no envelope to hang it off. Independent of
            // Degraded above — that is about this record's provider, this is
            // about whether the set it belongs to is complete.
            FromTruncatedSnapshot = truncated,
        };
        if (record.TransitionTimestampUtc != DateTime.MinValue)
        {
            snapshot.LastTransitionTimestamp =
                Google.Protobuf.WellKnownTypes.Timestamp.FromDateTime(
                    DateTime.SpecifyKind(record.TransitionTimestampUtc, DateTimeKind.Utc));
        }
        return snapshot;
    }

    private static AlarmConditionState MapConditionState(MxAlarmStateKind state)
    {
        // The proto's AlarmConditionState only distinguishes Active /
        // ActiveAcked / Inactive — both Rtn states collapse to Inactive
        // (the ack-vs-unack distinction on a cleared alarm is not exposed
        // through OPC UA's Part 9 condition state model anyway).
        return state switch
        {
            MxAlarmStateKind.UnackAlm => AlarmConditionState.Active,
            MxAlarmStateKind.AckAlm => AlarmConditionState.ActiveAcked,
            MxAlarmStateKind.UnackRtn => AlarmConditionState.Inactive,
            MxAlarmStateKind.AckRtn => AlarmConditionState.Inactive,
            _ => AlarmConditionState.Unspecified,
        };
    }

    /// <summary>Gets the session ID.</summary>
    public string SessionId => sessionId;

    /// <inheritdoc />
    public void Dispose()
    {
        if (disposed) return;
        disposed = true;
        try { consumer.AlarmTransitionEmitted -= handler; } catch { /* swallow */ }
        try { sink.Detach(); } catch { /* swallow */ }
        try { consumer.Dispose(); } catch { /* swallow */ }
    }
}