namespace ZB.MOM.WW.ScadaBridge.Transport.Import;

/// <summary>
/// Register row 52: a sliding window of bundle-unlock attempts that is shared across the
/// central pair, so <c>TransportOptions.MaxUnlockAttemptsPerIpPerHour</c> is a FLEET cap
/// rather than a per-node, per-process one.
/// <para>
/// Implementations are expected to THROW on store failure. The fail-open decision belongs
/// to <see cref="BundleUnlockRateLimiter"/>, which owns the policy (log a Warning and
/// permit the attempt), not to the storage layer.
/// </para>
/// </summary>
public interface IBundleUnlockAttemptWindow
{
    /// <summary>
    /// Registers one unlock attempt against the shared window and reports whether it was
    /// within budget. Implementations must NOT record an attempt they are rejecting —
    /// a denial burns no budget, matching the in-memory limiter's contract (register
    /// row 44), so a client that keeps hammering cannot extend its own lockout.
    /// </summary>
    /// <param name="clientKey">Throttle bucket — the caller's remote IP, or the shared unattributed bucket.</param>
    /// <param name="maxAttemptsPerWindow">The trailing-window cap (<c>MaxUnlockAttemptsPerIpPerHour</c>).</param>
    /// <param name="window">Trailing window the attempts are counted over (one hour in production).</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns><c>true</c> when the attempt was recorded (within budget); <c>false</c> when the bucket is exhausted.</returns>
    Task<bool> TryRegisterAttemptAsync(
        string clientKey, int maxAttemptsPerWindow, TimeSpan window, CancellationToken ct = default);

    /// <summary>
    /// Register row 65: drives one retention sweep of aged-out attempt rows independently
    /// of the unlock path. The prune used to ride <see cref="TryRegisterAttemptAsync"/>
    /// only, so a cluster that stopped importing entirely left its last rows in place
    /// indefinitely; <c>BundleSessionEvictionService</c> — Transport's periodic
    /// central-only sweep — now also ticks this, which closes that.
    /// <para>
    /// Unlike <see cref="TryRegisterAttemptAsync"/>, implementations must NOT throw on
    /// store failure: this is pure retention maintenance with no caller to report to, and
    /// the sweep that drives it must never be taken down by a database blip. Implementations
    /// are also expected to keep their own cadence claim, so calling this more often than
    /// the intended prune interval is harmless.
    /// </para>
    /// </summary>
    /// <param name="window">Trailing window the attempts are counted over (one hour in production); rows are retained for a multiple of it.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A task that completes when the prune attempt has finished (or been skipped for cadence).</returns>
    Task PruneAsync(TimeSpan window, CancellationToken ct = default);
}