dohertj2/lmxopcua
1
0
Fork 0
Code Issues 2 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat(alarms): native condition Acknowledge routes to NativeAlarmAckRouter with principal [H6c]

Browse Source
This commit is contained in:
Joseph Doherty
2026-06-15 14:33:58 -04:00
parent be6858baa1
commit a6d9de091b
3 changed files with 184 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/NativeAlarmAck.cs
+20
View File
@@ -0,0 +1,20 @@
namespace ZB.MOM.WW.OtOpcUa.OpcUaServer;
/// <summary>
/// H6c — the payload routed when an OPC UA client Acknowledges a NATIVE (driver-fed, e.g. Galaxy)
/// Part 9 condition. The scripted-alarm engine does not own native conditions, so the node manager
/// branches a native condition's inbound Acknowledge to a separate
/// <see cref="OtOpcUaNodeManager.NativeAlarmAckRouter"/> seam (the host later wires it to the backing
/// driver) instead of the scripted <see cref="OtOpcUaNodeManager.AlarmCommandRouter"/>.
/// <para>
/// This record is intentionally OpcUaServer-local (the smallest scope) and Akka-free: it carries
/// exactly what the driver-bound router needs — the condition node id to resolve back to a driver
/// ref, the operator's acknowledge comment, and the authenticated operator's display name.
/// </para>
/// </summary>
/// <param name="ConditionNodeId">The acknowledged condition's folder-scoped NodeId identifier string
/// (the same value the <c>DriverHostActor</c> inverse map keys native conditions by), used to resolve the
/// command back to its backing driver + alarm ref.</param>
/// <param name="Comment">The operator's acknowledge comment text, or <c>null</c> when none was supplied.</param>
/// <param name="OperatorUser">The authenticated operator's display name (empty when none resolves).</param>
public sealed record NativeAlarmAck(string ConditionNodeId, string? Comment, string OperatorUser);
src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/OtOpcUaNodeManager.cs
+66 -1
View File
@@ -97,6 +97,26 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
/// </summary>
public Action<AlarmCommand>? AlarmCommandRouter { get; set; }
/// <summary>
/// H6c — reverse-path sink for an inbound OPC UA Acknowledge on a NATIVE (driver-fed, e.g. Galaxy)
/// Part 9 condition. The scripted-alarm engine does not own native conditions, so when a client
/// Acknowledges one, the condition's <c>OnAcknowledge</c> handler (wired in
/// <see cref="MaterialiseAlarmCondition"/>) branches on <see cref="IsNativeAlarmNode"/> and — after
/// the same <c>AlarmAck</c> role gate as <see cref="AlarmCommandRouter"/> — invokes THIS delegate
/// with a <see cref="NativeAlarmAck"/> instead of routing an <see cref="AlarmCommand"/> to the
/// scripted engine. The host sets it at boot to a non-blocking dispatch toward the backing driver
/// (a later task wires the driver linkage).
/// <para>
/// Like <see cref="AlarmCommandRouter"/>, the handler delegate runs under the manager's
/// <c>Lock</c>, so the invoked action MUST be non-blocking (fire-and-forget). Null (the default)
/// makes the native-ack handler a safe no-op — it still gates + returns, just routes nowhere.
/// Only the Acknowledge of a native condition uses this seam; Confirm/AddComment/Shelve on a
/// native condition stay on the scripted <see cref="AlarmCommandRouter"/> path (H6c scope is the
/// Acknowledge → driver path only).
/// </para>
/// </summary>
public Action<NativeAlarmAck>? NativeAlarmAckRouter { get; set; }
private volatile IOpcUaNodeWriteGateway _nodeWriteGateway = NullOpcUaNodeWriteGateway.Instance;
/// <summary>
@@ -602,8 +622,14 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
// T20: the engine re-projects that same logical transition through WriteAlarmCondition; its
// delta-gate (compares against the node's current state, which the SDK already pre-applied)
// sees no change and suppresses the would-be second event (E3) — so no double-emit.
// H6c — a NATIVE (driver-fed) condition's Acknowledge belongs to the backing driver, NOT the
// scripted engine, so branch on native-ness (via the lock-guarded accessor) and route a native
// ack to NativeAlarmAckRouter instead of the scripted AlarmCommandRouter. Confirm/AddComment/
// Shelve stay on the scripted path even for native conditions (H6c scope is Acknowledge only).
alarm.OnAcknowledge = (context, condition, _, comment) =>
HandleAlarmCommand(context, condition, "Acknowledge", comment, unshelveAt: null);
IsNativeAlarmNode(alarmNodeId)
? HandleNativeAlarmAck(context, condition, comment)
: HandleAlarmCommand(context, condition, "Acknowledge", comment, unshelveAt: null);
alarm.OnConfirm = (context, condition, _, comment) =>
HandleAlarmCommand(context, condition, "Confirm", comment, unshelveAt: null);
alarm.OnAddComment = (context, condition, _, comment) =>
@@ -716,6 +742,45 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
return ServiceResult.Good;
}
/// <summary>
/// H6c — handler body for an inbound OPC UA Acknowledge on a NATIVE (driver-fed) condition. The
/// scripted engine does not own native conditions, so this routes a <see cref="NativeAlarmAck"/> to
/// <see cref="NativeAlarmAckRouter"/> (the driver-bound seam) rather than a scripted
/// <see cref="AlarmCommand"/> to <see cref="AlarmCommandRouter"/>. The calling principal is resolved
/// and the <c>AlarmAck</c> role gate applied EXACTLY as in <see cref="HandleAlarmCommand"/>
/// (<b>fails closed</b>: a missing identity or missing role is denied — no route, no state mutation).
/// </summary>
/// <param name="context">The SDK context the handler delegate was invoked with — a
/// <c>ServerSystemContext</c> (an <see cref="ISessionOperationContext"/>) carrying the session identity
/// (T17 attached the LDAP roles as a <see cref="RoleCarryingUserIdentity"/>).</param>
/// <param name="condition">The condition the Acknowledge targets; its <c>NodeId</c> identifier is the
/// folder-scoped condition node id the driver-bound router resolves back to a driver ref.</param>
/// <param name="comment">The acknowledge comment text, or <c>null</c> when none was supplied.</param>
/// <returns><c>ServiceResult.Good</c> when allowed (the SDK then applies state + auto-fires its event);
/// <c>BadUserAccessDenied</c> when the gate vetoes (no route, no state mutation).</returns>
private ServiceResult HandleNativeAlarmAck(ISystemContext context, ConditionState condition, LocalizedText? comment)
{
// Resolve + gate the SAME way HandleAlarmCommand does so native and scripted acks share one authz
// contract. Anonymous / non-role-carrying identities ⇒ null ⇒ denied (fail closed, never route).
var identity = (context as ISessionOperationContext)?.UserIdentity as RoleCarryingUserIdentity;
if (identity is null || !identity.Roles.Contains(OpcUaDataPlaneRoles.AlarmAck, StringComparer.OrdinalIgnoreCase))
{
return new ServiceResult(StatusCodes.BadUserAccessDenied);
}
// Same condition-node-id extraction HandleAlarmCommand uses (condition.NodeId.Identifier?.ToString()):
// for a native condition this is the folder-scoped NodeId string the DriverHostActor inverse map
// (_alarmNodeIdByDriverRef value set) keys by, so the next task can resolve it back to (driver, ref).
// Non-blocking by contract (host wires a fire-and-forget dispatch); safe to call under Lock.
NativeAlarmAckRouter?.Invoke(new NativeAlarmAck(
ConditionNodeId: condition.NodeId.Identifier?.ToString() ?? string.Empty,
Comment: comment?.Text,
OperatorUser: identity.DisplayName ?? string.Empty));
// Good ⇒ the SDK applies the node-state change + auto-fires its own condition event.
return ServiceResult.Good;
}
/// <summary>
/// The <see cref="NodeValueEventHandler"/> attached to a writable equipment-tag variable by
/// <see cref="EnsureVariable"/> (Task 11). The OPC UA SDK invokes it when a client writes the
tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests/AlarmCommandRouterTests.cs
+98
View File
@@ -411,6 +411,104 @@ public sealed class AlarmCommandRouterTests : IDisposable
await host.DisposeAsync();
}
/// <summary>H6c — a NATIVE (driver-fed) condition's Acknowledge routes to <see
/// cref="OtOpcUaNodeManager.NativeAlarmAckRouter"/> (the driver-bound seam), NOT the scripted
/// <see cref="OtOpcUaNodeManager.AlarmCommandRouter"/>. With the AlarmAck role present, OnAcknowledge
/// returns Good, the captured <see cref="NativeAlarmAck"/> carries the condition NodeId, the operator
/// DisplayName, and the comment text, and the scripted router is NOT invoked.</summary>
[Fact]
public async Task Native_OnAcknowledge_routes_to_NativeAlarmAckRouter_not_scripted()
{
var (host, server) = await BootAsync();
var nm = server.NodeManager!;
var scripted = new List<AlarmCommand>();
var native = new List<NativeAlarmAck>();
nm.AlarmCommandRouter = scripted.Add;
nm.NativeAlarmAckRouter = native.Add;
nm.EnsureFolder("eq-nak1", parentNodeId: null, displayName: "Equipment NAK1");
nm.MaterialiseAlarmCondition("alm-nak1", "eq-nak1", "HighTemp", "OffNormalAlarm", severity: 700, isNative: true);
var condition = nm.TryGetAlarmCondition("alm-nak1");
condition.ShouldNotBeNull();
condition!.OnAcknowledge.ShouldNotBeNull();
var ctx = SessionContext(server, "nora", OpcUaDataPlaneRoles.AlarmAck);
var result = condition.OnAcknowledge!(ctx, condition, EventIdBytes(), new LocalizedText("native ack"));
result.ShouldBe(ServiceResult.Good);
native.Count.ShouldBe(1);
native[0].ConditionNodeId.ShouldBe("alm-nak1"); // folder-scoped condition NodeId identifier
native[0].OperatorUser.ShouldBe("nora");
native[0].Comment.ShouldBe("native ack");
scripted.ShouldBeEmpty(); // scripted engine NOT involved
await host.DisposeAsync();
}
/// <summary>H6c — a SCRIPTED condition's Acknowledge still routes through the scripted
/// <see cref="OtOpcUaNodeManager.AlarmCommandRouter"/> (Operation == "Acknowledge"); the native
/// router is NOT invoked.</summary>
[Fact]
public async Task Scripted_OnAcknowledge_still_uses_AlarmCommandRouter()
{
var (host, server) = await BootAsync();
var nm = server.NodeManager!;
var scripted = new List<AlarmCommand>();
var native = new List<NativeAlarmAck>();
nm.AlarmCommandRouter = scripted.Add;
nm.NativeAlarmAckRouter = native.Add;
nm.EnsureFolder("eq-nak2", parentNodeId: null, displayName: "Equipment NAK2");
nm.MaterialiseAlarmCondition("alm-nak2", "eq-nak2", "HighTemp", "OffNormalAlarm", severity: 700, isNative: false);
var condition = nm.TryGetAlarmCondition("alm-nak2");
condition.ShouldNotBeNull();
condition!.OnAcknowledge.ShouldNotBeNull();
var ctx = SessionContext(server, "owen", OpcUaDataPlaneRoles.AlarmAck);
var result = condition.OnAcknowledge!(ctx, condition, EventIdBytes(), new LocalizedText("scripted ack"));
result.ShouldBe(ServiceResult.Good);
scripted.Count.ShouldBe(1);
scripted[0].AlarmId.ShouldBe("alm-nak2");
scripted[0].Operation.ShouldBe("Acknowledge");
scripted[0].User.ShouldBe("owen");
scripted[0].Comment.ShouldBe("scripted ack");
native.ShouldBeEmpty(); // native seam NOT involved
await host.DisposeAsync();
}
/// <summary>H6c — a NATIVE condition's Acknowledge from an anonymous / role-less identity is vetoed
/// (BadUserAccessDenied) and NEITHER router is invoked — the gate fails closed before any route.</summary>
[Fact]
public async Task Native_OnAcknowledge_anonymous_is_denied()
{
var (host, server) = await BootAsync();
var nm = server.NodeManager!;
var scripted = new List<AlarmCommand>();
var native = new List<NativeAlarmAck>();
nm.AlarmCommandRouter = scripted.Add;
nm.NativeAlarmAckRouter = native.Add;
nm.EnsureFolder("eq-nak3", parentNodeId: null, displayName: "Equipment NAK3");
nm.MaterialiseAlarmCondition("alm-nak3", "eq-nak3", "HighTemp", "OffNormalAlarm", severity: 700, isNative: true);
var condition = nm.TryGetAlarmCondition("alm-nak3");
condition.ShouldNotBeNull();
// ServerSystemContext with no UserIdentity ⇒ anonymous / no role-carrying identity.
var ctx = new ServerSystemContext(server.CurrentInstance);
var result = condition!.OnAcknowledge!(ctx, condition, EventIdBytes(), new LocalizedText("x"));
result.StatusCode.Code.ShouldBe(StatusCodes.BadUserAccessDenied);
native.ShouldBeEmpty();
scripted.ShouldBeEmpty();
await host.DisposeAsync();
}
/// <summary>A null router is a safe no-op: handler still gates + returns Good, just routes nowhere.</summary>
[Fact]
public async Task OnAcknowledge_with_null_router_is_safe_noop_and_returns_good()