8e8d4cdf13
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
159 lines
8.1 KiB
C#
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><alarm>.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;
|
|
}
|
|
}
|