Files
lmxopcua/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Galaxy/Runtime/IGalaxyAlarmAcknowledger.cs
T
Joseph Doherty 4e492e6550 fix(galaxy): confirm unconfirmed native alarm acks against Galaxy's acknowledged transition (#869)
mxaccessgw answers AcknowledgeAlarm OK both when the AckMsg write was
applied and when it was only sent (no OnWriteComplete; the reply then
carries a diagnostic). EvaluateReply treated both as success, so the H6
live gate saw a condition go Acknowledged while Galaxy never applied it.

- EvaluateReply returns Applied (no diagnostic) or Unconfirmed (diagnostic)
  and logs the gateway diagnostic on every branch that carries one.
- GalaxyAckConfirmationTracker watches the alarm feed from before the RPC
  and, for an unconfirmed reply, waits up to AlarmAck.ConfirmTimeoutMs
  (default 10 s, 0 = old behaviour) for an Acknowledge/ActiveAcknowledged
  transition; on timeout it refuses (BadTimeout + diagnostic).
- New optional IAlarmAcknowledgeConfirmation: DriverInstanceActor awaits it
  after AcknowledgeAsync, off its mailbox and outside the resilience
  pipeline; a failure is the existing #760 AlarmAckFailed revert.
- AdminUI Galaxy form carries the new knob; docs updated.

Claude-Session: https://claude.ai/code/session_01GT67AD99zQQqpLCVm3p7xk
2026-11-11 13:03:04 -05:00

54 lines
2.8 KiB
C#

namespace ZB.MOM.WW.OtOpcUa.Driver.Galaxy.Runtime;
/// <summary>
/// Test seam for the gateway-side Acknowledge call. Production wraps the
/// <c>MxGatewayClient.AcknowledgeAlarmAsync</c> RPC; tests substitute a fake
/// so <see cref="GalaxyDriver.AcknowledgeAsync"/> can be exercised without a
/// running gateway.
/// </summary>
internal interface IGalaxyAlarmAcknowledger
{
/// <summary>
/// Forward a single alarm acknowledgement to the gateway. The gateway (488649c+)
/// authenticates <paramref name="credential"/> and writes <paramref name="comment"/>
/// to <c>&lt;alarm&gt;.AckMsg</c> as that user, so the Historian records it as the operator.
/// </summary>
/// <param name="alarmFullReference">
/// Fully-qualified alarm reference (e.g. <c>"Tank01.Level.HiHi"</c>).
/// </param>
/// <param name="comment">Ack comment written to <c>AckMsg</c>.</param>
/// <param name="credential">
/// The Galaxy account to acknowledge as, resolved by <see cref="IGalaxyAckCredentialResolver"/>.
/// Carries a password — implementations must keep it out of logs and exception text.
/// </param>
/// <param name="cancellationToken">Cancels the gateway RPC.</param>
/// <returns>
/// Whether the gateway reported the ack APPLIED or only SENT without confirmation (lmxopcua#869). A refusal
/// or failure throws instead.
/// </returns>
Task<GalaxyAckOutcome> AcknowledgeAsync(
string alarmFullReference,
string comment,
GalaxyAckCredential credential,
CancellationToken cancellationToken);
}
/// <summary>
/// What the gateway said about an acknowledge it accepted (lmxopcua#869). mxaccessgw answers OK both when the
/// <c>AckMsg</c> write's <c>OnWriteComplete</c> reported success (<see cref="Applied"/>) and when the write was
/// sent but no completion arrived inside the worker's window (<see cref="Unconfirmed"/>) — its contract tells
/// clients to watch the alarm stream for the real acknowledged transition in that case.
/// </summary>
/// <param name="IsApplied">True when the gateway confirmed the ack write was applied.</param>
/// <param name="Diagnostic">The gateway's diagnostic message (password-scrubbed); empty when it sent none.</param>
internal sealed record GalaxyAckOutcome(bool IsApplied, string Diagnostic)
{
/// <summary>The gateway confirmed the ack write.</summary>
public static GalaxyAckOutcome Applied { get; } = new(true, string.Empty);
/// <summary>The gateway sent the ack write but could not confirm it.</summary>
/// <param name="diagnostic">The gateway's diagnostic message.</param>
/// <returns>The outcome.</returns>
public static GalaxyAckOutcome Unconfirmed(string diagnostic) => new(false, diagnostic ?? string.Empty);
}