lmxopcua/src/ZB.MOM.WW.OtOpcUa.Core/Resilience/AlarmSurfaceInvoker.cs

using ZB.MOM.WW.OtOpcUa.Core.Abstractions;

namespace ZB.MOM.WW.OtOpcUa.Core.Resilience;

/// <summary>
///     Wraps the three mutating surfaces of <see cref="IAlarmSource"/>
///     (<see cref="IAlarmSource.SubscribeAlarmsAsync"/>, <see cref="IAlarmSource.UnsubscribeAlarmsAsync"/>,
///     <see cref="IAlarmSource.AcknowledgeAsync"/>) through <see cref="CapabilityInvoker"/> so the
///     Phase 6.1 resilience pipeline runs — retry semantics match
///     <see cref="DriverCapability.AlarmSubscribe"/> (retries by default) and
///     <see cref="DriverCapability.AlarmAcknowledge"/> (does NOT retry per decision #143).
/// </summary>
/// <remarks>
///     <para>Multi-host dispatch: when the driver implements <see cref="IPerCallHostResolver"/>,
///     each source-node-id is resolved individually + grouped by host so a dead PLC inside a
///     multi-device driver doesn't poison the sibling hosts' breakers. Drivers with a single
///     host fall back to <see cref="IDriver.DriverInstanceId"/> as the single-host key.</para>
///
///     <para>Why this lives here + not on <see cref="CapabilityInvoker"/>: alarm surfaces have a
///     handle-returning shape (SubscribeAlarmsAsync returns <see cref="IAlarmSubscriptionHandle"/>)
///     + a per-call fan-out (AcknowledgeAsync gets a batch of
///     <see cref="AlarmAcknowledgeRequest"/>s that may span multiple hosts). Keeping the fan-out
///     logic here keeps the invoker's execute-overloads narrow.</para>
/// </remarks>
public sealed class AlarmSurfaceInvoker
{
    private readonly CapabilityInvoker _invoker;
    private readonly IAlarmSource _alarmSource;
    private readonly IPerCallHostResolver? _hostResolver;
    private readonly string _defaultHost;

    public AlarmSurfaceInvoker(
        CapabilityInvoker invoker,
        IAlarmSource alarmSource,
        string defaultHost,
        IPerCallHostResolver? hostResolver = null)
    {
        ArgumentNullException.ThrowIfNull(invoker);
        ArgumentNullException.ThrowIfNull(alarmSource);
        ArgumentException.ThrowIfNullOrWhiteSpace(defaultHost);

        _invoker = invoker;
        _alarmSource = alarmSource;
        _defaultHost = defaultHost;
        _hostResolver = hostResolver;
    }

    /// <summary>
    ///     Subscribe to alarm events for a set of source node ids, fanning out by resolved host
    ///     so per-host breakers / bulkheads apply. Returns one handle per host — callers that
    ///     don't care about per-host separation may concatenate them.
    /// </summary>
    public async Task<IReadOnlyList<IAlarmSubscriptionHandle>> SubscribeAsync(
        IReadOnlyList<string> sourceNodeIds,
        CancellationToken cancellationToken)
    {
        ArgumentNullException.ThrowIfNull(sourceNodeIds);
        if (sourceNodeIds.Count == 0) return [];

        var byHost = GroupByHost(sourceNodeIds);
        var handles = new List<IAlarmSubscriptionHandle>(byHost.Count);
        foreach (var (host, ids) in byHost)
        {
            var handle = await _invoker.ExecuteAsync(
                DriverCapability.AlarmSubscribe,
                host,
                async ct => await _alarmSource.SubscribeAlarmsAsync(ids, ct).ConfigureAwait(false),
                cancellationToken).ConfigureAwait(false);
            handles.Add(handle);
        }
        return handles;
    }

    /// <summary>Cancel an alarm subscription. Routes through the AlarmSubscribe pipeline for parity.</summary>
    public ValueTask UnsubscribeAsync(IAlarmSubscriptionHandle handle, CancellationToken cancellationToken)
    {
        ArgumentNullException.ThrowIfNull(handle);
        return _invoker.ExecuteAsync(
            DriverCapability.AlarmSubscribe,
            _defaultHost,
            async ct => await _alarmSource.UnsubscribeAlarmsAsync(handle, ct).ConfigureAwait(false),
            cancellationToken);
    }

    /// <summary>
    ///     Acknowledge alarms. Fans out by resolved host; each host's batch runs through the
    ///     AlarmAcknowledge pipeline (no-retry per decision #143 — an alarm-ack is not idempotent
    ///     at the plant-floor acknowledgement level even if the OPC UA spec permits re-issue).
    /// </summary>
    public async Task AcknowledgeAsync(
        IReadOnlyList<AlarmAcknowledgeRequest> acknowledgements,
        CancellationToken cancellationToken)
    {
        ArgumentNullException.ThrowIfNull(acknowledgements);
        if (acknowledgements.Count == 0) return;

        var byHost = _hostResolver is null
            ? new Dictionary<string, List<AlarmAcknowledgeRequest>> { [_defaultHost] = acknowledgements.ToList() }
            : acknowledgements
                .GroupBy(a => _hostResolver.ResolveHost(a.SourceNodeId))
                .ToDictionary(g => g.Key, g => g.ToList());

        foreach (var (host, batch) in byHost)
        {
            var batchSnapshot = batch; // capture for the lambda
            await _invoker.ExecuteAsync(
                DriverCapability.AlarmAcknowledge,
                host,
                async ct => await _alarmSource.AcknowledgeAsync(batchSnapshot, ct).ConfigureAwait(false),
                cancellationToken).ConfigureAwait(false);
        }
    }

    private Dictionary<string, List<string>> GroupByHost(IReadOnlyList<string> sourceNodeIds)
    {
        if (_hostResolver is null)
            return new Dictionary<string, List<string>> { [_defaultHost] = sourceNodeIds.ToList() };

        var result = new Dictionary<string, List<string>>(StringComparer.Ordinal);
        foreach (var id in sourceNodeIds)
        {
            var host = _hostResolver.ResolveHost(id);
            if (!result.TryGetValue(host, out var list))
                result[host] = list = new List<string>();
            list.Add(id);
        }
        return result;
    }
}