using ScadaLink.Communication.Grpc;

namespace ScadaLink.AuditLog.Site.Telemetry;

/// <summary>
/// Mockable abstraction over the central site-audit push surface that
/// <see cref="SiteAuditTelemetryActor"/> uses to forward <see cref="AuditEventBatch"/>
/// payloads. The production implementation is
/// <see cref="ClusterClientSiteAuditClient"/> — a ClusterClient-based client,
/// wired in the Host for site roles, that forwards batches to central via the
/// site's <c>SiteCommunicationActor</c>. Unit tests substitute via NSubstitute
/// against this interface so the actor never needs a live transport.
/// </summary>
public interface ISiteStreamAuditClient
{
    /// <summary>
    /// Forwards <paramref name="batch"/> to the central audit-ingest path. The
    /// returned <see cref="IngestAck"/> carries the <c>accepted_event_ids</c>
    /// the actor will flip to
    /// <see cref="ScadaLink.Commons.Types.Enums.AuditForwardState.Forwarded"/>
    /// in the site SQLite queue.
    /// </summary>
    Task<IngestAck> IngestAuditEventsAsync(AuditEventBatch batch, CancellationToken ct);

    /// <summary>
    /// Forwards the combined <see cref="CachedTelemetryBatch"/> (Audit Log #23)
    /// to the central cached-telemetry ingest path. Each packet carries both the
    /// audit row and the operational <c>SiteCalls</c> upsert; central writes both
    /// in a single MS SQL transaction. Returns the same <see cref="IngestAck"/>
    /// shape as <see cref="IngestAuditEventsAsync"/> so the site-side forwarder
    /// can flip the underlying audit rows to
    /// <see cref="ScadaLink.Commons.Types.Enums.AuditForwardState.Forwarded"/>
    /// once central has acknowledged them.
    /// </summary>
    /// <remarks>
    /// The production <see cref="ClusterClientSiteAuditClient"/> forwards over
    /// the ClusterClient transport; the <see cref="NoOpSiteStreamAuditClient"/>
    /// DI default (used by central and test composition roots) returns an empty
    /// ack so no rows are flipped.
    /// </remarks>
    Task<IngestAck> IngestCachedTelemetryAsync(CachedTelemetryBatch batch, CancellationToken ct);
}