using Akka.Actor;

namespace ZB.MOM.WW.ScadaBridge.Communication.Grpc;

/// <summary>
/// Abstraction over the site-side stream subscription mechanism.
/// SiteStreamManager in the SiteRuntime project implements this interface;
/// the gRPC server depends on it without referencing SiteRuntime directly.
/// </summary>
public interface ISiteStreamSubscriber
{
    /// <summary>
    /// Subscribes an actor to receive filtered stream events for a specific instance.
    /// </summary>
    /// <param name="instanceName">The unique name of the instance whose events to subscribe to.</param>
    /// <param name="subscriber">The actor reference that will receive stream event messages.</param>
    /// <returns>A subscription ID that can be used for unsubscription.</returns>
    string Subscribe(string instanceName, IActorRef subscriber);

    /// <summary>
    /// Subscribes an actor to receive ALARM events for ALL instances on the site
    /// (no per-instance filter). Only <c>AlarmStateChanged</c> events are
    /// forwarded; attribute-value events are dropped. Backs the site-wide
    /// <c>SubscribeSite</c> gRPC stream used by the aggregated Alarm Summary.
    /// </summary>
    /// <param name="subscriber">The actor reference that will receive alarm stream event messages.</param>
    /// <returns>A subscription ID that can be used for unsubscription.</returns>
    string SubscribeSiteAlarms(IActorRef subscriber);

    /// <summary>
    /// Removes all subscriptions for the given actor.
    /// </summary>
    /// <param name="subscriber">The actor reference whose subscriptions should be removed.</param>
    void RemoveSubscriber(IActorRef subscriber);
}