Files
lmxopcua/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Galaxy/Runtime/GatewayGalaxyAlarmAcknowledger.cs
T
Joseph Doherty 8e8d4cdf13 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
2026-11-09 13:12:17 -05:00

159 lines
8.1 KiB
C#

using Microsoft.Extensions.Logging;
using ZB.MOM.WW.MxGateway.Client;
using ZB.MOM.WW.MxGateway.Contracts.Proto;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Runtime;
/// <summary>
/// Production <see cref="IGalaxyAlarmAcknowledger"/> backed by the session-less
/// <c>MxGatewayClient.AcknowledgeAlarmAsync</c> RPC. The gateway routes acknowledgement
/// through its always-on central alarm monitor, so no worker session is involved.
/// </summary>
/// <remarks>
/// <para>
/// <b>Operator-authenticated ack (mxaccessgw 488649c+, lmxopcua#749).</b> The gateway runs
/// <c>AuthenticateUser</c> with <c>operator_user</c>/<c>operator_domain</c>/<c>operator_password</c>
/// and writes the comment to <c>&lt;alarm&gt;.AckMsg</c> as that user, so the request always
/// carries a real Galaxy account — never an empty <c>operator_user</c>, which the gateway rejects.
/// </para>
/// <para>
/// <b>The password never leaves the request.</b> It is not logged, and every message this type
/// builds from gateway output is scrubbed of it (the gateway contract already keeps it out of
/// <c>ProtocolStatus.Message</c>; the scrub is defence in depth). The 0.3.0 client redacts it from
/// its own <c>MxGatewayException</c>s.
/// </para>
/// <para>
/// A non-OK <see cref="ProtocolStatus"/> means the gateway never reached MXAccess (transport /
/// dispatch / validation failure) and is surfaced as a thrown exception. A non-zero native ack
/// return code (<c>hresult</c> — now the <c>AuthenticateUser</c> HRESULT or the AckMsg write status)
/// means MXAccess rejected the ack (a wrong password, an account without ack permission, a failed
/// AckMsg write). It is logged and thrown as a <see cref="DriverOperationRefusedException"/>
/// (lmxopcua#760): the host then reverts the OPC UA condition to unacknowledged instead of leaving it
/// claiming an ack Galaxy never recorded, and the operator can retry. A refusal, not a fault — the
/// gateway answered — so it neither retries nor counts toward the resilience breaker (a mis-keyed
/// account must not open the breaker for every correctly-configured caller).
/// </para>
/// </remarks>
internal sealed class GatewayGalaxyAlarmAcknowledger : IGalaxyAlarmAcknowledger
{
/// <summary>Placeholder substituted for the password wherever gateway text is echoed.</summary>
internal const string Redacted = "***";
private readonly MxGatewayClient _client;
private readonly ILogger _logger;
/// <summary>Initializes a new instance of the <see cref="GatewayGalaxyAlarmAcknowledger"/> class.</summary>
/// <param name="client">The MX gateway client used to send acknowledgments.</param>
/// <param name="logger">A logger for diagnostic output.</param>
public GatewayGalaxyAlarmAcknowledger(MxGatewayClient client, ILogger logger)
{
_client = client ?? throw new ArgumentNullException(nameof(client));
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
}
/// <inheritdoc />
public async Task AcknowledgeAsync(
string alarmFullReference,
string comment,
GalaxyAckCredential credential,
CancellationToken cancellationToken)
{
var request = BuildRequest(alarmFullReference, comment, credential);
AcknowledgeAlarmReply reply;
try
{
reply = await _client.AcknowledgeAlarmAsync(request, cancellationToken).ConfigureAwait(false);
}
catch (Exception ex) when (ex is not OperationCanceledException
&& credential.Password.Length > 0
&& ContainsSecret(ex, credential.Password))
{
// Defence in depth over the client's own redaction: never let an exception that echoes the
// password escape into the actor's warning log.
throw new InvalidOperationException(
$"Galaxy AcknowledgeAlarm for '{alarmFullReference}' failed at the gateway ({ex.GetType().Name}); "
+ "details withheld because they echoed the operator credential.");
}
EvaluateReply(reply, alarmFullReference, credential, _logger);
}
/// <summary>Maps an acknowledge onto the gateway request. Pure — pinned by unit tests.</summary>
/// <param name="alarmFullReference">The alarm reference.</param>
/// <param name="comment">The ack comment.</param>
/// <param name="credential">The Galaxy account to acknowledge as.</param>
/// <returns>The request.</returns>
internal static AcknowledgeAlarmRequest BuildRequest(
string alarmFullReference, string comment, GalaxyAckCredential credential)
{
ArgumentException.ThrowIfNullOrEmpty(alarmFullReference);
ArgumentNullException.ThrowIfNull(credential);
return new AcknowledgeAlarmRequest
{
ClientCorrelationId = Guid.NewGuid().ToString("N"),
AlarmFullReference = alarmFullReference,
Comment = comment ?? string.Empty,
OperatorUser = credential.User,
OperatorDomain = credential.Domain,
OperatorPassword = credential.Password,
};
}
/// <summary>
/// Applies the reply semantics: non-OK protocol status throws; a non-zero native code warns and throws a
/// <see cref="DriverOperationRefusedException"/> (lmxopcua#760).
/// Every message is scrubbed of the password.
/// </summary>
/// <param name="reply">The gateway reply.</param>
/// <param name="alarmFullReference">The alarm reference.</param>
/// <param name="credential">The credential the request carried.</param>
/// <param name="logger">The logger.</param>
internal static void EvaluateReply(
AcknowledgeAlarmReply reply, string alarmFullReference, GalaxyAckCredential credential, ILogger logger)
{
// Protocol status — the gateway failed before MXAccess saw the ack. This is a
// hard failure: the operator's request was not delivered at all.
if (reply.ProtocolStatus is { } proto && proto.Code != ProtocolStatusCode.Ok)
{
throw new InvalidOperationException(
$"Galaxy AcknowledgeAlarm for '{alarmFullReference}' as '{credential.DisplayName}' failed at the gateway: "
+ $"{proto.Code} {Scrub(proto.Message, credential.Password)}");
}
// hresult is the authoritative native ack return code (0 = success) — the AuthenticateUser HRESULT
// or the AckMsg write status. It is absent only on a worker protocol violation; with an OK protocol
// status a missing value is treated as success.
if (reply.HasHresult && reply.Hresult != 0)
{
logger.LogWarning(
"Galaxy AcknowledgeAlarm for {AlarmRef} as {GalaxyUser} returned native ack failure code {Hresult}.",
alarmFullReference, credential.DisplayName, reply.Hresult);
throw new DriverOperationRefusedException(
$"MXAccess rejected the Galaxy acknowledge of '{alarmFullReference}' as '{credential.DisplayName}' "
+ $"(native code 0x{reply.Hresult:X8}); check the account's password and Galaxy acknowledge permission.");
}
}
/// <summary>Replaces every occurrence of <paramref name="secret"/> in <paramref name="text"/>.</summary>
/// <param name="text">Text that may echo the secret.</param>
/// <param name="secret">The secret; empty means nothing to scrub.</param>
/// <returns>The scrubbed text.</returns>
internal static string Scrub(string? text, string secret) =>
string.IsNullOrEmpty(text) || string.IsNullOrEmpty(secret)
? text ?? string.Empty
: text.Replace(secret, Redacted, StringComparison.Ordinal);
private static bool ContainsSecret(Exception ex, string secret)
{
for (var e = ex; e is not null; e = e.InnerException)
{
if (e.Message.Contains(secret, StringComparison.Ordinal)) return true;
}
return false;
}
}