using ZB.MOM.WW.MxGateway.Contracts.Proto;
using ZB.MOM.WW.MxGateway.Server.Configuration;

namespace ZB.MOM.WW.MxGateway.Server.Alarms;

/// <summary>
///     Resolves the subtag watch-list the gateway sends to the worker when the
///     central alarm monitor operates in subtag-polling fallback mode. Merges
///     Galaxy Repository alarm-attribute discovery with the configured
///     include/exclude overrides and composes the per-attribute subtag item
///     addresses from the configured subtag names.
/// </summary>
public interface IAlarmWatchListResolver
{
    /// <summary>
    ///     Builds the subtag watch-list for the supplied alarm configuration.
    /// </summary>
    /// <param name="options">Alarm configuration carrying discovery and subtag-name settings.</param>
    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
    /// <returns>
    ///     The resolved <see cref="AlarmSubtagTarget"/> watch-list, possibly empty, together
    ///     with the discovery provenance the caller needs to grade it.
    ///     Discovery being unavailable never throws — it yields an empty (or
    ///     config-only) list with <see cref="AlarmWatchListResolution.DiscoveryFailed"/> set,
    ///     and the caller decides what to do with it. Cancellation
    ///     is the one exception: a triggered <paramref name="cancellationToken"/>
    ///     still propagates an <see cref="OperationCanceledException"/>.
    /// </returns>
    Task<AlarmWatchListResolution> ResolveAsync(
        AlarmsOptions options,
        CancellationToken cancellationToken = default);
}