using Akka.Actor;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Audit;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Deployment;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Health;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Notification;

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

/// <summary>
/// The site→central transport seam: one method per the seven messages
/// <see cref="SiteCommunicationActor"/> sends to <c>/user/central-communication</c> today.
/// </summary>
/// <remarks>
/// <para>
/// The actor's receive handlers no longer own the wire plumbing — they capture the current
/// <c>Sender</c> and hand it to the transport as <paramref name="replyTo"/>. The production
/// implementation is <see cref="Grpc.GrpcCentralTransport"/> (a gRPC dial of
/// <c>CentralControlService</c> with sticky central-a→central-b failover) — the only site→central
/// transport since the ClusterClient→gRPC migration removed the Akka path in Phase 4.
/// <see cref="NoOpCentralTransport"/> is the fail-loud placeholder used only when the Host injects
/// nothing (a wiring bug, and in TestKit suites that only exercise command dispatch).
/// </para>
/// <para>
/// <b>Reply/fault contract.</b> Each Ask-returning method (all but the heartbeat) guarantees exactly
/// one reply eventually lands at <paramref name="replyTo"/>: either the real reply type the caller
/// Asks for, or a transient-failure signal. The gRPC path sends <see cref="Status.Failure"/> on any
/// non-OK status (a timeout or an <c>Unavailable</c> that could not be failed over) — what the
/// S&amp;F / audit / health layers above the seam already treat as transient (rows stay buffered,
/// counters restore, the pass re-runs).
/// </para>
/// <para>
/// <b>The heartbeat stays fire-and-forget end-to-end.</b> <see cref="SendHeartbeat"/> takes no
/// <c>replyTo</c> and never surfaces a fault: a transport failure is swallowed and logged, exactly
/// as the old <c>Tell</c> dropped it. A failing heartbeat must never fault the site's heartbeat
/// timer path.
/// </para>
/// </remarks>
public interface ICentralTransport
{
    /// <summary>Forwards a buffered notification; central replies <see cref="NotificationSubmitAck"/> to <paramref name="replyTo"/>.</summary>
    /// <param name="message">The notification submission.</param>
    /// <param name="replyTo">The actor (the S&amp;F forwarder's Ask) the ack routes back to.</param>
    void SubmitNotification(NotificationSubmit message, IActorRef replyTo);

    /// <summary>Forwards a Notify.Status query; central replies <see cref="NotificationStatusResponse"/> to <paramref name="replyTo"/>.</summary>
    /// <param name="message">The status query.</param>
    /// <param name="replyTo">The actor (the Notify helper's Ask) the response routes back to.</param>
    void QueryNotificationStatus(NotificationStatusQuery message, IActorRef replyTo);

    /// <summary>Pushes a batch of audit events; central replies <see cref="IngestAuditEventsReply"/> to <paramref name="replyTo"/>.</summary>
    /// <param name="message">The audit-event ingest command.</param>
    /// <param name="replyTo">The actor (the telemetry drain's Ask) the reply routes back to.</param>
    void IngestAuditEvents(IngestAuditEventsCommand message, IActorRef replyTo);

    /// <summary>Pushes a batch of combined cached-call telemetry; central replies <see cref="IngestCachedTelemetryReply"/> to <paramref name="replyTo"/>.</summary>
    /// <param name="message">The cached-telemetry ingest command.</param>
    /// <param name="replyTo">The actor (the telemetry drain's Ask) the reply routes back to.</param>
    void IngestCachedTelemetry(IngestCachedTelemetryCommand message, IActorRef replyTo);

    /// <summary>Reports a node's startup inventory; central replies <see cref="ReconcileSiteResponse"/> to <paramref name="replyTo"/>.</summary>
    /// <param name="message">The reconcile request.</param>
    /// <param name="replyTo">The actor (the reconciliation Ask) the response routes back to.</param>
    void ReconcileSite(ReconcileSiteRequest message, IActorRef replyTo);

    /// <summary>Reports periodic site health; central replies <see cref="SiteHealthReportAck"/> to <paramref name="replyTo"/>.</summary>
    /// <param name="message">The health report.</param>
    /// <param name="replyTo">The actor (the health transport's Ask) the ack routes back to.</param>
    void ReportSiteHealth(SiteHealthReport message, IActorRef replyTo);

    /// <summary>
    /// Sends an application heartbeat, fire-and-forget. Never replies and never faults; a failure
    /// is swallowed and logged.
    /// </summary>
    /// <param name="message">The heartbeat.</param>
    /// <param name="self">The site communication actor, used as the sender on the Akka path (ignored on gRPC).</param>
    void SendHeartbeat(HeartbeatMessage message, IActorRef self);
}