feat(alarms): Primary-gated AlarmTransitionEvent fan-out for native alarms (Phase B WS-5)

2026-06-14 03:48:41 -04:00
parent b50ef9fc2d
commit 8736fcc37c
2 changed files with 177 additions and 5 deletions
@@ -1,11 +1,15 @@
 using System.Text.Json;
 using Akka.Actor;
+using Akka.Cluster.Tools.PublishSubscribe;
+using Akka.TestKit;
 using Microsoft.EntityFrameworkCore;
 using Shouldly;
 using Xunit;
 using ZB.MOM.WW.OtOpcUa.Commons.Engines;
+using ZB.MOM.WW.OtOpcUa.Commons.Messages.Alerts;
 using ZB.MOM.WW.OtOpcUa.Commons.Messages.Deploy;
 using ZB.MOM.WW.OtOpcUa.Commons.Messages.Fleet;
+using ZB.MOM.WW.OtOpcUa.Commons.Messages.Redundancy;
 using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
 using ZB.MOM.WW.OtOpcUa.Commons.Types;
 using ZB.MOM.WW.OtOpcUa.Configuration;
@@ -14,6 +18,7 @@ using ZB.MOM.WW.OtOpcUa.Configuration.Enums;
 using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
 using ZB.MOM.WW.OtOpcUa.Runtime.Drivers;
 using ZB.MOM.WW.OtOpcUa.Runtime.OpcUa;
+using ZB.MOM.WW.OtOpcUa.Runtime.ScriptedAlarms;
 using ZB.MOM.WW.OtOpcUa.Runtime.Tests.Harness;

 namespace ZB.MOM.WW.OtOpcUa.Runtime.Tests.Drivers;
@@ -99,6 +104,116 @@ public sealed class DriverHostActorNativeAlarmTests : RuntimeActorTestBase
        publish.ExpectNoMsg(TimeSpan.FromMilliseconds(500));
    }

+    /// <summary>Primary (default/unset role) fan-out (Phase B WS-5): a native alarm RAISE on a known ref
+    /// publishes exactly one <see cref="AlarmTransitionEvent"/> to the cluster <c>alerts</c> topic with
+    /// <c>AlarmId</c> = the folder-scoped condition NodeId, alongside the (ungated) OPC UA condition
+    /// update. No <see cref="RedundancyStateChanged"/> is sent, so the cached role is unknown ⇒ emit.</summary>
+    [Fact]
+    public void Native_alarm_publishes_AlarmTransitionEvent_to_alerts_when_primary()
+    {
+        var db = NewInMemoryDbFactory();
+        var deploymentId = SeedDeploymentWithAlarmTag(db, RevA,
+            Equip: "eq-1", Driver: "drv-1", FullName: "Temp.HiHi", Folder: null, Name: "temp_hi");
+
+        var alerts = CreateTestProbe();
+        SubscribeToAlerts(alerts);
+
+        var (actor, publish) = SpawnHostAndApply(db, deploymentId);
+
+        actor.Tell(new DriverInstanceActor.AttributeAlarmPublished("drv-1", new AlarmEventArgs(
+            new StubAlarmHandle(),
+            SourceNodeId: "Temp.HiHi",
+            ConditionId: "cond-1",
+            AlarmType: "OffNormalAlarm",
+            Message: "temperature high",
+            Severity: AlarmSeverity.High,
+            SourceTimestampUtc: Ts,
+            Kind: AlarmTransitionKind.Raise)));
+
+        // The OPC UA condition update is UNGATED — it must arrive.
+        var update = publish.ExpectMsg<OpcUaPublishActor.AlarmStateUpdate>(TimeSpan.FromSeconds(5));
+        update.AlarmNodeId.ShouldBe("eq-1/temp_hi");
+
+        // Role unknown ⇒ default-emit: exactly one AlarmTransitionEvent on the alerts topic.
+        var evt = alerts.ExpectMsg<AlarmTransitionEvent>(TimeSpan.FromSeconds(5));
+        evt.AlarmId.ShouldBe("eq-1/temp_hi");          // the folder-scoped condition NodeId
+        evt.EquipmentPath.ShouldBe("eq-1");            // from the alarm-bearing tag's EquipmentId
+        evt.AlarmName.ShouldBe("temp_hi");             // from the tag's Name
+        evt.TransitionKind.ShouldBe("Raise");          // AlarmEventArgs.Kind.ToString()
+        evt.AlarmTypeName.ShouldBe("OffNormalAlarm");  // the tag's alarm AlarmType
+        evt.Severity.ShouldBe(700);                    // AlarmSeverity.High → projector 700
+        evt.Message.ShouldBe("temperature high");
+        evt.User.ShouldBe(string.Empty);              // no operator comment ⇒ device-origin (empty user)
+        evt.HistorizeToAveva.ShouldBe(true);
+        alerts.ExpectNoMsg(TimeSpan.FromMilliseconds(300)); // exactly one
+    }
+
+    /// <summary>Secondary suppression (Phase B WS-5): when the cached local role is Secondary the host
+    /// MUST still write the local OPC UA condition node (ungated — keeps the standby's address space warm
+    /// for failover) but MUST NOT publish the cluster-wide <c>alerts</c> transition (the Primary publishes
+    /// the single fleet-wide copy).</summary>
+    [Fact]
+    public void Secondary_node_suppresses_alerts_publish_but_still_updates_condition()
+    {
+        var db = NewInMemoryDbFactory();
+        var deploymentId = SeedDeploymentWithAlarmTag(db, RevA,
+            Equip: "eq-1", Driver: "drv-1", FullName: "Temp.HiHi", Folder: null, Name: "temp_hi");
+
+        var alerts = CreateTestProbe();
+        SubscribeToAlerts(alerts);
+
+        var (actor, publish) = SpawnHostAndApply(db, deploymentId);
+
+        // Mark this node Secondary so the alerts publish is gated off.
+        TellRedundancyRole(actor, RedundancyRole.Secondary);
+
+        actor.Tell(new DriverInstanceActor.AttributeAlarmPublished("drv-1", new AlarmEventArgs(
+            new StubAlarmHandle(),
+            SourceNodeId: "Temp.HiHi",
+            ConditionId: "cond-1",
+            AlarmType: "OffNormalAlarm",
+            Message: "temperature high",
+            Severity: AlarmSeverity.High,
+            SourceTimestampUtc: Ts,
+            Kind: AlarmTransitionKind.Raise)));
+
+        // The OPC UA condition update is UNGATED — it must still arrive on the secondary.
+        var update = publish.ExpectMsg<OpcUaPublishActor.AlarmStateUpdate>(TimeSpan.FromSeconds(5));
+        update.AlarmNodeId.ShouldBe("eq-1/temp_hi");
+        update.State.Active.ShouldBeTrue();
+
+        // The cluster-wide alerts publish is gated off on the secondary.
+        alerts.ExpectNoMsg(TimeSpan.FromMilliseconds(500));
+    }
+
+    /// <summary>Subscribe <paramref name="probe"/> to the <c>alerts</c> DPS topic and wait for the ack.
+    /// The Subscribe is sent FROM the probe so the SubscribeAck returns to it. Mirrors the
+    /// ScriptedAlarmHostActor test harness.</summary>
+    private void SubscribeToAlerts(TestProbe probe)
+    {
+        DistributedPubSub.Get(Sys).Mediator.Tell(
+            new Subscribe(ScriptedAlarmHostActor.AlertsTopic, probe.Ref), probe.Ref);
+        probe.ExpectMsg<SubscribeAck>(TimeSpan.FromSeconds(5));
+    }
+
+    /// <summary>Tell the host a <see cref="RedundancyStateChanged"/> snapshot marking the host's own
+    /// node (<see cref="TestNode"/>, which equals the host's <c>_localNode</c>) with <paramref name="role"/>
+    /// so the alerts-publish gate observes the local role.</summary>
+    private static void TellRedundancyRole(IActorRef host, RedundancyRole role)
+    {
+        host.Tell(new RedundancyStateChanged(
+            new[]
+            {
+                new NodeRedundancyState(
+                    NodeId: TestNode,
+                    Role: role,
+                    IsClusterLeader: role == RedundancyRole.Primary,
+                    IsRoleLeaderForDriver: role == RedundancyRole.Primary,
+                    AsOfUtc: DateTime.UtcNow),
+            },
+            CorrelationId.NewId()));
+    }
+
    /// <summary>Spawns the host with a publish probe, dispatches the deployment, and waits for the Applied
    /// ACK so the apply (and thus the alarm-map build in PushDesiredSubscriptions) has completed before the
    /// test publishes an alarm. A VirtualTag-host probe is injected so the real host isn't spawned.</summary>