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

/// <summary>
/// Transport-004: thrown by <see cref="BundleImporter.LoadAsync"/> when the caller
/// has exceeded the configured per-IP-per-hour unlock attempt cap
/// (<see cref="TransportOptions.MaxUnlockAttemptsPerIpPerHour"/>). The 429-equivalent
/// signal: the caller must wait for the trailing-hour window to roll forward before
/// another passphrase attempt is accepted.
/// </summary>
public sealed class BundleUnlockRateLimitedException : Exception
{
    /// <summary>
    /// Rate-limit key the limiter rejected the attempt against — the caller IP when
    /// supplied, or the bundle's content hash as the architectural fallback (the
    /// importer has no <c>IHttpContext</c> dependency by design).
    /// </summary>
    public string ClientKey { get; }

    /// <summary>Per-window cap that was reached.</summary>
    public int Limit { get; }

    /// <summary>
    /// Initializes a new <see cref="BundleUnlockRateLimitedException"/>.
    /// </summary>
    /// <param name="clientKey">The rate-limit key that exceeded its budget.</param>
    /// <param name="limit">The configured per-window cap.</param>
    public BundleUnlockRateLimitedException(string clientKey, int limit)
        : base(
            $"Bundle unlock rate limit reached ({limit} attempts per hour). "
            + "Wait for the trailing-hour window to expire before retrying.")
    {
        ClientKey = clientKey ?? throw new ArgumentNullException(nameof(clientKey));
        Limit = limit;
    }
}