using ScadaLink.Commons.Messages.Integration;

namespace ScadaLink.AuditLog.Central;

/// <summary>
/// Mockable abstraction over the central-side <c>PullAuditEvents</c> gRPC
/// client surface that <see cref="SiteAuditReconciliationActor"/> uses to
/// fetch the next reconciliation batch from a specific site. Extracted so the
/// actor can be unit-tested against an in-memory stub without standing up a
/// real <c>GrpcChannel</c> per site.
/// </summary>
/// <remarks>
/// <para>
/// The production implementation (host wiring task) wraps the auto-generated
/// <c>SiteStreamService.SiteStreamServiceClient</c>, multiplexing one
/// <c>GrpcChannel</c> per site keyed on
/// <see cref="SiteEntry.GrpcEndpoint"/>. Until that wiring lands the DI
/// composition root binds a NoOp default that returns an empty response — the
/// reconciliation tick is still scheduled and the cursor logic still runs, so
/// regressions in the actor itself are caught even before the real client
/// arrives.
/// </para>
/// <para>
/// Implementations MUST NOT throw on transport faults that the actor can
/// tolerate (connection refused, deadline exceeded). The actor's contract is
/// "one site's failure doesn't sink the rest of the tick"; an exception still
/// won't crash the actor (the per-site try/catch catches it), but returning
/// an empty response on a known-recoverable error keeps the logs cleaner.
/// </para>
/// </remarks>
public interface IPullAuditEventsClient
{
    /// <summary>
    /// Issues a <c>PullAuditEvents</c> RPC against the site whose endpoint
    /// is registered against <paramref name="siteId"/>. Returns the next
    /// batch of <see cref="ScadaLink.Commons.Entities.Audit.AuditEvent"/>
    /// rows ordered oldest-first AND a <c>MoreAvailable</c> flag the actor
    /// uses to decide whether to fire another pull immediately.
    /// </summary>
    Task<PullAuditEventsResponse> PullAsync(
        string siteId,
        DateTime sinceUtc,
        int batchSize,
        CancellationToken ct);
}