using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using MxGateway.Contracts.Proto;

namespace MxGateway.Server.Sessions;

/// <summary>
///     Gateway-side dispatcher seam for the alarm-RPC surface. Bridges the
///     public <c>AcknowledgeAlarm</c> + <c>QueryActiveAlarms</c> gRPC handlers
///     to the worker process that hosts <c>IMxAccessAlarmConsumer</c>.
/// </summary>
/// <remarks>
///     <para>
///         DI binds the production <see cref="WorkerAlarmRpcDispatcher"/> by
///         default; it routes calls through the existing worker-pipe IPC.
///         <c>NotWiredAlarmRpcDispatcher</c> is only the null fallback used
///         when no dispatcher is registered (DI omission / standalone tests).
///         Other tests inject a fake to exercise the gateway handler shape
///         without spinning up a worker process.
///     </para>
///     <para>
///         The dispatcher is session-scoped: every call resolves the
///         session and forwards to that session's worker. The handler
///         constructs the <see cref="AcknowledgeAlarmReply"/> /
///         <see cref="ActiveAlarmSnapshot"/> stream from the dispatcher's
///         output without further translation.
///     </para>
/// </remarks>
public interface IAlarmRpcDispatcher
{
    /// <summary>Forward an Acknowledge to the worker that owns the session.</summary>
    Task<AcknowledgeAlarmReply> AcknowledgeAsync(
        AcknowledgeAlarmRequest request,
        CancellationToken cancellationToken);

    /// <summary>Walk active alarms on the worker that owns the session.</summary>
    IAsyncEnumerable<ActiveAlarmSnapshot> QueryActiveAlarmsAsync(
        QueryActiveAlarmsRequest request,
        CancellationToken cancellationToken);
}