using ZB.MOM.WW.Audit;

namespace ZB.MOM.WW.MxGateway.Server.Security.Audit;

/// <summary>
/// Durable sink the audit pipeline persists canonical <see cref="AuditEvent"/>s through.
/// It exists so the write path (<see cref="CanonicalAuditWriter"/>) and the batching drain
/// (<see cref="AuditDrainService"/>) depend on the storage contract rather than on the
/// concrete <see cref="SqliteCanonicalAuditStore"/>.
/// </summary>
public interface IAuditEventSink
{
    /// <summary>
    /// Bootstraps the backing storage. Called once at startup so no write path pays a schema
    /// round-trip; implementations must be idempotent and safe to call concurrently.
    /// </summary>
    /// <param name="cancellationToken">Token to observe for cancellation.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task EnsureInitializedAsync(CancellationToken cancellationToken);

    /// <summary>Persists a single canonical audit event.</summary>
    /// <param name="auditEvent">The canonical event to persist.</param>
    /// <param name="cancellationToken">Token to observe for cancellation.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task InsertAsync(AuditEvent auditEvent, CancellationToken cancellationToken);

    /// <summary>Persists a batch of canonical audit events as one unit of work.</summary>
    /// <param name="auditEvents">The canonical events to persist.</param>
    /// <param name="cancellationToken">Token to observe for cancellation.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task InsertBatchAsync(IReadOnlyList<AuditEvent> auditEvents, CancellationToken cancellationToken);

    /// <summary>Deletes every audit row that occurred strictly before <paramref name="cutoffUtc"/>.</summary>
    /// <param name="cutoffUtc">The retention cutoff; rows older than this are removed.</param>
    /// <param name="cancellationToken">Token to observe for cancellation.</param>
    /// <returns>The number of rows deleted.</returns>
    Task<int> DeleteOlderThanAsync(DateTimeOffset cutoffUtc, CancellationToken cancellationToken);
}