worker: alarm event mapper + sink scaffold (PR A.2 — partial)

Eighteenth PR of the alarms-over-gateway epic (docs/plans/alarms-over-gateway.md). Lands the proto-build path that the worker uses to create OnAlarmTransition events. The COM-side subscription that registers an alarm event sink against the MXAccess Toolkit is pinned during dev-rig validation — the exact API differs across AVEVA versions and needs hardware to verify. Lands today (unit-testable, no hardware needed): - MxAccessEventMapper.CreateOnAlarmTransition — mechanical proto builder. Takes decoded alarm fields (full reference, source object, alarm type, transition kind, severity, timestamps, operator user/comment, category, description) and produces an MxEvent with the OnAlarmTransition body populated. Mirrors the pattern of CreateOnDataChange / CreateOnWriteComplete / etc. - MxAccessAlarmEventSink — scaffolded class with documented Attach / Detach + an internal EnqueueTransition entry point. When dev-rig validation pins the MXAccess Toolkit alarm subscription API, the only edit needed is to wire the COM delegate inside Attach to call EnqueueTransition. The mapper bridge is already done. Pending dev-rig validation: - Pin the MXAccess Toolkit alarm event source COM API (likely one of IAlarmEventSink, IAlarmEventSubscription, or a method on LMXProxyServerClass — verify against the worker host's installed version). - Add cancellation/cleanup tests once the COM hook is wired. - Integration test against the parity rig that fires a real Galaxy alarm and asserts the gateway emits OnAlarmTransition. Tests: - 2 new mapper tests pin the full-payload Acknowledge case and the bare-bones Raise case. - Full Worker.Tests suite green: 123 passed (was 121; 2 new). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-30 21:16:29 -04:00
parent 3256733d24
commit 335c952f00
3 changed files with 262 additions and 0 deletions
@@ -102,6 +102,72 @@ public sealed class MxAccessEventMapper
        return mxEvent;
    }

+    /// <summary>
+    ///     Creates an OnAlarmTransition event from MXAccess COM alarm-event arguments.
+    ///     PR A.2 — proto-build path is mechanical and unit-testable; the COM-side
+    ///     subscription that calls into this method (registering an
+    ///     <c>IAlarmEventSink</c> against the MXAccess Toolkit's alarm provider) is
+    ///     pinned during dev-rig validation since the exact MXAccess Toolkit version
+    ///     installed on the worker host determines the API shape.
+    /// </summary>
+    /// <param name="sessionId">Identifier of the session.</param>
+    /// <param name="alarmFullReference">Fully-qualified MxAccess alarm reference (e.g. "Tank01.Level.HiHi").</param>
+    /// <param name="sourceObjectReference">Galaxy-side source object reference; empty when not bound to a Galaxy object.</param>
+    /// <param name="alarmTypeName">MxAccess alarm-type qualifier (e.g. "AnalogLimitAlarm.HiHi").</param>
+    /// <param name="transitionKind">Discriminator: Raise / Acknowledge / Clear / Retrigger.</param>
+    /// <param name="severity">Raw MxAccess severity (kept on the native scale; lmxopcua maps to OPC UA 0-1000).</param>
+    /// <param name="originalRaiseTimestampUtc">When the alarm originally entered active; null on retrigger.</param>
+    /// <param name="transitionTimestampUtc">When this specific transition occurred.</param>
+    /// <param name="operatorUser">Operator principal recorded by MxAccess on Acknowledge transitions; empty on raise/clear.</param>
+    /// <param name="operatorComment">Operator-supplied comment recorded by MxAccess on Acknowledge transitions; empty on raise/clear.</param>
+    /// <param name="category">Alarm taxonomy bucket from the Galaxy template.</param>
+    /// <param name="description">Human-readable alarm description.</param>
+    /// <param name="statuses">Array of MxStatusProxy values from MXAccess.</param>
+    public MxEvent CreateOnAlarmTransition(
+        string sessionId,
+        string alarmFullReference,
+        string sourceObjectReference,
+        string alarmTypeName,
+        AlarmTransitionKind transitionKind,
+        int severity,
+        DateTime? originalRaiseTimestampUtc,
+        DateTime transitionTimestampUtc,
+        string operatorUser,
+        string operatorComment,
+        string category,
+        string description,
+        Array? statuses)
+    {
+        MxEvent mxEvent = CreateBaseEvent(
+            MxEventFamily.OnAlarmTransition,
+            sessionId,
+            serverHandle: 0,
+            itemHandle: 0,
+            statuses);
+
+        OnAlarmTransitionEvent body = new()
+        {
+            AlarmFullReference = alarmFullReference ?? string.Empty,
+            SourceObjectReference = sourceObjectReference ?? string.Empty,
+            AlarmTypeName = alarmTypeName ?? string.Empty,
+            TransitionKind = transitionKind,
+            Severity = severity,
+            TransitionTimestamp = Google.Protobuf.WellKnownTypes.Timestamp.FromDateTime(
+                DateTime.SpecifyKind(transitionTimestampUtc, DateTimeKind.Utc)),
+            OperatorUser = operatorUser ?? string.Empty,
+            OperatorComment = operatorComment ?? string.Empty,
+            Category = category ?? string.Empty,
+            Description = description ?? string.Empty,
+        };
+        if (originalRaiseTimestampUtc is { } orts)
+        {
+            body.OriginalRaiseTimestamp = Google.Protobuf.WellKnownTypes.Timestamp.FromDateTime(
+                DateTime.SpecifyKind(orts, DateTimeKind.Utc));
+        }
+        mxEvent.OnAlarmTransition = body;
+        return mxEvent;
+    }
+
    /// <summary>Creates an OnBufferedDataChange event from MXAccess COM event arguments.</summary>
    /// <param name="sessionId">Identifier of the session.</param>
    /// <param name="serverHandle">Handle returned by the worker.</param>