fix(alarms): surface a refused native alarm ack synchronously, revert one that fails later (lmxopcua#760)

The native-ack path is fire-and-forget after the Part 9 Acknowledge returns, so
a Galaxy ack refused for lack of a credential (#749), or rejected by MXAccess,
left the client with Good and the condition showing Acknowledged while Galaxy
was never acked. Both options from the issue, layered:

1. Synchronous refusal for what the driver can decide without I/O. New optional
   IAlarmAcknowledgePreflight (Core.Abstractions); GalaxyDriver refuses an
   anonymous session when the driver has no AlarmAck fallback account.
   DriverHostActor publishes a condition NodeId -> owning-driver snapshot into
   NativeAlarmAckPreflightView (lock-free, volatile); the node manager's new
   NativeAlarmAckPreflight seam, consulted after the authz and Primary gates,
   returns BadUserAccessDenied with the reason - nothing routed, applied or
   reported. A keyed session is not pre-checked (its identity lives in the
   Secrets store, which must not be read under the SDK lock).

2. Revert for everything else. RouteAlarmAck carries the condition NodeId;
   DriverInstanceActor replies AlarmAckFailed on a refusal, a backend failure,
   a driver without an alarm source, or an ack dropped while connecting /
   reconnecting. DriverHostActor re-projects the condition unacknowledged via
   NativeAlarmProjector.TryRevertAcknowledge, but only while the local ack is
   still pending - any driver transition projected since then wins. A disabled
   or unspawned driver is not reverted (unchanged).

GatewayGalaxyAlarmAcknowledger now throws DriverOperationRefusedException on a
non-zero native hresult (wrong password, no ack permission) instead of only
warning, so that case reverts too; as a refusal it neither retries nor trips
the breaker.

Tests (each fails with its fix mutated out): projector revert/supersede,
DriverHostActor refused + failed ack -> unacked AlarmStateUpdate (successful
ack control), preflight view snapshot, node-manager preflight unit test,
over-the-wire ConditionMethodEventTests (BadUserAccessDenied, no route, no
event; positive control), Galaxy preflight + hresult refusal.
Docs: Galaxy.md, AlarmTracking.md, ScriptedAlarms.md, .claude/rules/alarms.md.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 13:12:17 -05:00
parent 0217d36cf4
commit 8e8d4cdf13
21 changed files with 737 additions and 61 deletions
@@ -255,6 +255,15 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
/// </summary>
public Func<bool>? NativeAlarmAckPrimaryGate { get; set; }
/// <summary>
/// Synchronous pre-check for an OPC UA Acknowledge of a NATIVE condition (lmxopcua#760): returns why the
/// owning driver would refuse it, or null to proceed. Consulted after the authorization and Primary gates;
/// a non-null answer refuses the method with <c>BadUserAccessDenied</c> carrying the reason, and nothing is
/// routed, applied or reported. Runs under the manager's <c>Lock</c>, so it must be a lock-free read of
/// state the host already holds. Null (the default) skips the check.
/// </summary>
public Func<NativeAlarmAck, string?>? NativeAlarmAckPreflight { get; set; }
/// <summary>
/// Whether this node may serve an OPC UA HistoryUpdate right now: the redundancy data-plane
/// verdict (<c>PrimaryGatePolicy.ShouldServiceAsPrimary</c>, as published to <c>IDriverPrimaryRoleSource</c>) —
@@ -2123,7 +2132,8 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
/// <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; the method path reports the event);
/// <c>BadUserAccessDenied</c> when the gate vetoes, <c>BadInvalidState</c> when this node is not the redundancy
/// Primary (<see cref="NativeAlarmAckPrimaryGate"/>) — in both cases no route, no state mutation.</returns>
/// Primary (<see cref="NativeAlarmAckPrimaryGate"/>), <c>BadUserAccessDenied</c> with the driver's reason when
/// <see cref="NativeAlarmAckPreflight"/> refuses it — in every case 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
@@ -2145,12 +2155,22 @@ public sealed class OtOpcUaNodeManager : CustomNodeManager2
// 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(
var ack = new NativeAlarmAck(
ConditionNodeId: condition.NodeId.Identifier?.ToString() ?? string.Empty,
Comment: comment?.Text,
OperatorUser: AlarmOperatorName(identity!),
ApiKeyId: identity!.ApiKeyId));
ApiKeyId: identity!.ApiKeyId);
// lmxopcua#760 — a driver that already knows it would refuse this acknowledge (e.g. an anonymous session
// on a Galaxy driver with no fallback ack account) refuses it HERE, synchronously, rather than the client
// getting Good for an ack the upstream alarm system never sees. Lock-free read; nothing routed or applied.
if (NativeAlarmAckPreflight?.Invoke(ack) is { } refusal)
{
return new ServiceResult(StatusCodes.BadUserAccessDenied, new LocalizedText(refusal));
}
// Non-blocking by contract (host wires a fire-and-forget dispatch); safe to call under Lock.
NativeAlarmAckRouter?.Invoke(ack);
// Good ⇒ the SDK applies the node-state change; WireMethodTransitionReporting then reports the one
// condition event (the SDK reports none of its own).
@@ -83,6 +83,20 @@ public sealed class OtOpcUaSdkServer : StandardServer
return true;
}
/// <summary>
/// Wire the synchronous native-ack pre-check (<see cref="OtOpcUaNodeManager.NativeAlarmAckPreflight"/>,
/// lmxopcua#760). Passing <c>null</c> clears it. No-op (returns <c>false</c>) when the node manager has not
/// been created yet (mirrors <see cref="SetNativeAlarmAckRouter"/>).
/// </summary>
/// <param name="preflight">A lock-free read returning the refusal reason, or null to proceed.</param>
/// <returns><c>true</c> when set on a live node manager; <c>false</c> when no node manager exists yet.</returns>
public bool SetNativeAlarmAckPreflight(Func<NativeAlarmAck, string?>? preflight)
{
if (_otOpcUaNodeManager is null) return false;
_otOpcUaNodeManager.NativeAlarmAckPreflight = preflight;
return true;
}
/// <summary>
/// Wire the redundancy verdict that decides whether this node serves an OPC UA HistoryUpdate
/// (<see cref="OtOpcUaNodeManager.HistoryUpdatePrimaryGate"/>); on any other node every authorized node of a