namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;

/// <summary>
/// Register row 52: read/write access to the central <c>BundleUnlockAttempt</c> table,
/// the fleet-wide sliding window behind the Transport component's per-client bundle-unlock
/// throttle. Both central nodes share this store, so the documented
/// <c>MaxUnlockAttemptsPerIpPerHour</c> cap is a fleet cap rather than a per-process one.
/// </summary>
/// <remarks>
/// The throttle is a best-effort rate cap layered over an already-authenticated,
/// role-gated surface. Callers are expected to treat a store failure as fail-open (the
/// availability of legitimate imports outranks the cap), so no method here is required to
/// be transactional with respect to the caller's own work.
/// </remarks>
public interface IBundleUnlockAttemptRepository
{
    /// <summary>
    /// Counts the attempts recorded for <paramref name="clientKey"/> at or after
    /// <paramref name="sinceUtc"/> — the trailing-window depth the cap is compared against.
    /// </summary>
    /// <param name="clientKey">Throttle bucket (client IP, or the shared unattributed bucket).</param>
    /// <param name="sinceUtc">Inclusive UTC lower bound of the trailing window.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The number of attempts inside the window.</returns>
    Task<int> CountAttemptsSinceAsync(string clientKey, DateTime sinceUtc, CancellationToken ct = default);

    /// <summary>
    /// Appends one attempt row for <paramref name="clientKey"/>.
    /// </summary>
    /// <param name="clientKey">Throttle bucket (client IP, or the shared unattributed bucket).</param>
    /// <param name="attemptedAtUtc">UTC instant of the attempt.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A task that completes when the row is committed.</returns>
    Task RecordAttemptAsync(string clientKey, DateTime attemptedAtUtc, CancellationToken ct = default);

    /// <summary>
    /// Deletes attempt rows older than <paramref name="beforeUtc"/>, up to
    /// <paramref name="maxRows"/> in one bounded pass. Bounded so an opportunistic prune on
    /// a request path can never turn into an unbounded delete.
    /// </summary>
    /// <param name="beforeUtc">Exclusive UTC upper bound — rows strictly older than this are eligible.</param>
    /// <param name="maxRows">Maximum rows to delete in this pass; must be positive.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The number of rows deleted.</returns>
    Task<int> PruneAttemptsOlderThanAsync(DateTime beforeUtc, int maxRows, CancellationToken ct = default);
}