path: root/src/Cepis/CepisClient.cs

using System.Collections.Frozen;
using System.Globalization;
using System.Net.Sockets;
using System.Text;
using System.Text.Json;

namespace Cepis;

/// <summary>
/// Client for the public CEP API at <see href="https://cep.is">cep.is</see>.
/// </summary>
/// <remarks>
/// <para>
/// Build one and reuse it. The configuration is immutable, no method keeps
/// state between calls, and the single underlying <see cref="HttpClient"/>
/// pools connections — sharing one instance across threads is both safe and
/// faster than creating them. A client per request is the classic way to run a
/// .NET process out of sockets.
/// </para>
/// <example>
/// <code>
/// using var client = new CepisClient(new CepisClientOptions
/// {
///     BaseUrl = "http://localhost:8080",
/// });
///
/// Address address = await client.LookupAsync("01001-000");
/// </code>
/// </example>
/// <para>
/// For a script, <see cref="Default"/> is a shared client with the default
/// configuration, built on first use.
/// </para>
/// <para>
/// Retries cover 429, the transient 5xx and network failures, with exponential
/// backoff and full jitter. 400 and 404 are never retried: both are definitive
/// answers about the request, so retrying returns the same thing more slowly
/// while burning someone else's quota.
/// </para>
/// <para>
/// A note on names: the API surface is English, but the <b>data fields keep the
/// API's own Portuguese names</b> (<see cref="Address.Logradouro"/>,
/// <see cref="Address.Bairro"/>, <see cref="Address.Localidade"/>), with only
/// the casing adapted. What you read in the JSON is what you access on the
/// object.
/// </para>
/// </remarks>
public sealed class CepisClient : IDisposable
{
    /// <summary>Where the public API lives.</summary>
    public const string DefaultUrl = "https://cep.is";

    /// <summary>How many CEPs the batch endpoint accepts in one request.</summary>
    public const int MaxBatch = 500;

    /// <summary>The version of this library.</summary>
    public const string Version = "0.2.0";

    private const string AcceptHeader = "application/json, text/csv;q=0.9, */*;q=0.1";

    private static readonly FrozenSet<int> RetriableStatus =
        new[] { 429, 500, 502, 503, 504 }.ToFrozenSet();

    private static readonly FrozenSet<int> OkOnly = new[] { 200 }.ToFrozenSet();

    private static readonly FrozenSet<int> HealthStatus = new[] { 200, 503 }.ToFrozenSet();

    private static readonly JsonSerializerOptions JsonOptions = CreateJsonOptions();

    private static readonly Lazy<CepisClient> SharedDefault = new(() => new CepisClient());

    private readonly HttpClient _http;
    private readonly bool _ownsHttp;
    private readonly string _baseUrl;
    private readonly CepisClientOptions _options;

    /// <summary>Build a client with the default configuration.</summary>
    public CepisClient()
        : this(new CepisClientOptions())
    {
    }

    /// <summary>Build a client with its own <see cref="HttpClient"/>.</summary>
    /// <param name="options">the configuration</param>
    /// <exception cref="ArgumentNullException"><paramref name="options"/> is null</exception>
    /// <exception cref="ArgumentException">a setting is out of range</exception>
    public CepisClient(CepisClientOptions options)
        : this(NewHttpClient(), options, ownsHttp: true)
    {
    }

    /// <summary>
    /// Build a client over an <see cref="HttpClient"/> the caller owns.
    /// </summary>
    /// <remarks>
    /// For applications that resolve their <see cref="HttpClient"/> from
    /// <c>IHttpClientFactory</c> or a container. The instance is neither
    /// reconfigured nor disposed by this client, so its own
    /// <see cref="HttpClient.Timeout"/> still applies on top of
    /// <see cref="CepisClientOptions.Timeout"/> — whichever is shorter wins.
    /// </remarks>
    /// <param name="httpClient">the transport to use</param>
    /// <param name="options">the configuration, or null for the defaults</param>
    /// <exception cref="ArgumentNullException"><paramref name="httpClient"/> is null</exception>
    /// <exception cref="ArgumentException">a setting is out of range</exception>
    public CepisClient(HttpClient httpClient, CepisClientOptions? options = null)
        : this(httpClient, options ?? new CepisClientOptions(), ownsHttp: false)
    {
    }

    private CepisClient(HttpClient httpClient, CepisClientOptions options, bool ownsHttp)
    {
        ArgumentNullException.ThrowIfNull(httpClient);
        ArgumentNullException.ThrowIfNull(options);
        Validate(options);

        _http = httpClient;
        _ownsHttp = ownsHttp;
        _options = options;
        _baseUrl = options.BaseUrl.Trim().TrimEnd('/');
        UserAgent = options.UserAgent ?? $"cepis-csharp/{Version} (+https://cep.is)";
    }

    /// <summary>
    /// A shared client with the default configuration, built on first use.
    /// </summary>
    /// <remarks>
    /// Convenient for scripts and one-off lookups. It applies process-wide,
    /// including to third-party libraries that also use this package, so do not
    /// dispose it; anyone needing different settings should build their own.
    /// </remarks>
    public static CepisClient Default => SharedDefault.Value;

    /// <summary>Where the API lives, without a trailing slash.</summary>
    public string BaseUrl => _baseUrl;

    /// <summary>The configuration this client was built with.</summary>
    public CepisClientOptions Options => _options;

    /// <summary>The <c>User-Agent</c> this client sends.</summary>
    public string UserAgent { get; }

    /// <summary>
    /// Return the CEP's eight digits, accepting the mask.
    /// </summary>
    /// <remarks>
    /// <c>"01001-000"</c>, <c>"01001000"</c> and <c>" 01001-000 "</c> all become
    /// <c>"01001000"</c>. This runs <b>before</b> any request: a seven-digit CEP
    /// is the caller's bug, and spending a round trip for the server to say so
    /// wastes both sides' time.
    /// </remarks>
    /// <param name="value">the CEP, masked or not</param>
    /// <returns>the eight digits</returns>
    /// <exception cref="InvalidCepException">unless exactly eight digits remain</exception>
    public static string NormalizeCep(string value)
    {
        if (value is null)
        {
            throw new InvalidCepException("the CEP must not be null");
        }

        var cleaned = value.Trim().Replace("-", "", StringComparison.Ordinal)
            .Replace(".", "", StringComparison.Ordinal)
            .Replace(" ", "", StringComparison.Ordinal);

        if (!IsEightDigits(cleaned))
        {
            throw new InvalidCepException($"the CEP must be 8 digits, got \"{value}\"");
        }

        return cleaned;
    }

    /// <summary>
    /// Look up a single CEP.
    /// </summary>
    /// <remarks>
    /// <para>
    /// This is the only call that carries a coordinate. About 57% of CEPs have
    /// one; when they do not, <see cref="Address.Geo"/> is
    /// <see langword="null"/>.
    /// </para>
    /// <para>
    /// A CEP that does not exist throws, as it always has. What is new is that
    /// the exception may name the municipality the number would belong to, in
    /// <see cref="CepNotFoundException.Faixa"/> — context for the failure, not
    /// an address, and never a reason to treat the lookup as having succeeded.
    /// </para>
    /// </remarks>
    /// <param name="cep">the CEP, masked or not</param>
    /// <param name="cancellationToken">cancels the call, waits included</param>
    /// <returns>the address</returns>
    /// <exception cref="InvalidCepException">
    /// the CEP is not eight digits, in which case no request is made, or the API
    /// rejected it with a 400
    /// </exception>
    /// <exception cref="CepNotFoundException">
    /// well-formed, but not in the database; carries the municipality it would
    /// belong to when the API names one
    /// </exception>
    /// <exception cref="RateLimitedException">the API answered 429 on every attempt</exception>
    /// <exception cref="ServerErrorException">the API answered 5xx on every attempt</exception>
    /// <exception cref="NetworkException">the request never completed</exception>
    /// <exception cref="InvalidResponseException">the body cannot be read</exception>
    public async Task<Address> LookupAsync(string cep, CancellationToken cancellationToken = default)
    {
        var number = NormalizeCep(cep);
        var reply = await RequestAsync($"/{number}", OkOnly, cancellationToken).ConfigureAwait(false);

        if (reply.Status == 404)
        {
            var faixa = ReadFaixa(reply.Body);
            throw new CepNotFoundException(NotFoundMessage(number, faixa), faixa);
        }

        if (reply.Status == 400)
        {
            throw new InvalidCepException(
                ErrorMessage(reply.Body, $"CEP {number} was rejected by the API"));
        }

        return Deserialize<Address>(reply.Body);
    }

    /// <summary>
    /// Look up many CEPs in one batch.
    /// </summary>
    /// <remarks>
    /// <para>
    /// The returned list has <b>the same length and the same order</b> as the
    /// input. A CEP that does not exist becomes <see langword="null"/> at its
    /// position — it does not vanish from the list, and it does not throw. That
    /// is the right difference from
    /// <see cref="LookupAsync(string, CancellationToken)"/>: in a batch of a
    /// thousand, one bad CEP must not cost the other nine hundred and
    /// ninety-nine.
    /// </para>
    /// <para>
    /// A malformed CEP also becomes <see langword="null"/>, for the same reason.
    /// If you need to know <i>which</i> one was malformed, validate first with
    /// <see cref="NormalizeCep(string)"/>.
    /// </para>
    /// <para>
    /// Input longer than <see cref="MaxBatch"/> is chunked into that many CEPs
    /// per request automatically.
    /// </para>
    /// <para>
    /// <b>Batches carry no coordinate.</b> The endpoint behind them is CSV, and
    /// the CSV has no <c>geo</c> column. Every address returned here has
    /// <see cref="Address.Geo"/> <see langword="null"/>, including for CEPs that
    /// do have one. Need the coordinate? Use
    /// <see cref="LookupAsync(string, CancellationToken)"/>, one at a time.
    /// </para>
    /// </remarks>
    /// <param name="ceps">the CEPs, masked or not</param>
    /// <param name="cancellationToken">cancels the call, waits included</param>
    /// <returns>
    /// one entry per input CEP, in order, <see langword="null"/> where there is
    /// no address
    /// </returns>
    /// <exception cref="ArgumentNullException"><paramref name="ceps"/> is null</exception>
    /// <exception cref="RateLimitedException">the API answered 429 on every attempt</exception>
    /// <exception cref="ServerErrorException">the API answered 5xx on every attempt</exception>
    /// <exception cref="NetworkException">a request never completed</exception>
    public async Task<IReadOnlyList<Address?>> LookupManyAsync(
        IEnumerable<string> ceps,
        CancellationToken cancellationToken = default)
    {
        ArgumentNullException.ThrowIfNull(ceps);

        var wanted = ceps as IReadOnlyList<string> ?? [.. ceps];
        if (wanted.Count == 0)
        {
            return [];
        }

        var result = new List<Address?>(wanted.Count);
        for (var start = 0; start < wanted.Count; start += MaxBatch)
        {
            var end = Math.Min(start + MaxBatch, wanted.Count);
            var chunk = new List<string>(end - start);
            for (var i = start; i < end; i++)
            {
                chunk.Add(wanted[i]);
            }

            result.AddRange(await LookupChunkAsync(chunk, cancellationToken).ConfigureAwait(false));
        }

        return result;
    }

    /// <summary>
    /// Query <c>GET /health</c>: does the API answer, and with which database.
    /// </summary>
    /// <remarks>
    /// An API reporting itself degraded does not throw — that arrives in
    /// <see cref="Health.Status"/>, and checking health is exactly when you want
    /// the diagnosis rather than an exception. Network failures still throw.
    /// </remarks>
    /// <param name="cancellationToken">cancels the call, waits included</param>
    /// <returns>the API's health</returns>
    /// <exception cref="NetworkException">the request never completed</exception>
    /// <exception cref="InvalidResponseException">the body cannot be read</exception>
    public async Task<Health> HealthAsync(CancellationToken cancellationToken = default)
    {
        var reply = await RequestAsync("/health", HealthStatus, cancellationToken).ConfigureAwait(false);
        return Deserialize<Health>(reply.Body);
    }

    /// <summary>
    /// Release the <see cref="HttpClient"/> this client created for itself.
    /// </summary>
    /// <remarks>
    /// An <see cref="HttpClient"/> handed in by the caller is left alone.
    /// </remarks>
    public void Dispose()
    {
        if (_ownsHttp)
        {
            _http.Dispose();
        }
    }

    /// <summary>
    /// Parse the <c>Retry-After</c> header in both RFC 9110 forms.
    /// </summary>
    /// <remarks>
    /// It may arrive as a number of seconds (<c>"120"</c>) or as an HTTP date
    /// (<c>"Wed, 21 Oct 2026 07:28:00 GMT"</c>). Handling only the first is the
    /// common bug, and it makes a client ignore exactly the wait request that
    /// matters most.
    /// </remarks>
    /// <param name="value">the header value, if any</param>
    /// <returns>the wait, or null when there is nothing usable</returns>
    internal static TimeSpan? ParseRetryAfter(string? value)
    {
        if (string.IsNullOrWhiteSpace(value))
        {
            return null;
        }

        var header = value.Trim();
        if (double.TryParse(header, NumberStyles.Float, CultureInfo.InvariantCulture, out var seconds))
        {
            return TimeSpan.FromSeconds(Math.Max(0, seconds));
        }

        const DateTimeStyles styles = DateTimeStyles.AssumeUniversal | DateTimeStyles.AdjustToUniversal;
        if (!DateTimeOffset.TryParseExact(header, "r", CultureInfo.InvariantCulture, styles, out var target)
            && !DateTimeOffset.TryParse(header, CultureInfo.InvariantCulture, styles, out target))
        {
            return null;
        }

        var wait = target - DateTimeOffset.UtcNow;
        return wait < TimeSpan.Zero ? TimeSpan.Zero : wait;
    }

    private static HttpClient NewHttpClient() =>
        new(new SocketsHttpHandler
        {
            PooledConnectionLifetime = TimeSpan.FromMinutes(5),
            AutomaticDecompression = System.Net.DecompressionMethods.All,
        })
        {
            Timeout = System.Threading.Timeout.InfiniteTimeSpan,
        };

    private static JsonSerializerOptions CreateJsonOptions()
    {
        var options = new JsonSerializerOptions(JsonSerializerDefaults.General)
        {
            NumberHandling = System.Text.Json.Serialization.JsonNumberHandling.AllowReadingFromString,
            ReadCommentHandling = JsonCommentHandling.Disallow,
            AllowTrailingCommas = false,
        };
        options.Converters.Add(new LenientStringConverter());
        return options;
    }

    private static void Validate(CepisClientOptions options)
    {
        if (string.IsNullOrWhiteSpace(options.BaseUrl))
        {
            throw new ArgumentException("BaseUrl must not be empty", nameof(options));
        }

        if (options.MaxAttempts < 1)
        {
            throw new ArgumentException("MaxAttempts must be >= 1", nameof(options));
        }

        if (options.Timeout <= TimeSpan.Zero)
        {
            throw new ArgumentException("Timeout must be > 0", nameof(options));
        }

        if (options.BackoffBase < TimeSpan.Zero)
        {
            throw new ArgumentException("BackoffBase must be >= 0", nameof(options));
        }

        if (options.BackoffMax < TimeSpan.Zero)
        {
            throw new ArgumentException("BackoffMax must be >= 0", nameof(options));
        }

        if (options.TotalTimeout is { } total && total <= TimeSpan.Zero)
        {
            throw new ArgumentException("TotalTimeout must be > 0 when set", nameof(options));
        }
    }

    private static bool IsEightDigits(string value)
    {
        if (value.Length != 8)
        {
            return false;
        }

        foreach (var c in value)
        {
            if (c is < '0' or > '9')
            {
                return false;
            }
        }

        return true;
    }

    private static T Deserialize<T>(byte[] body)
        where T : class
    {
        T? value;
        try
        {
            value = JsonSerializer.Deserialize<T>(body, JsonOptions);
        }
        catch (JsonException unreadable)
        {
            throw new InvalidResponseException(
                "the response is not valid JSON — something between you and the API is "
                + $"answering instead of it: {Preview(body)}",
                unreadable);
        }

        return value ?? throw new InvalidResponseException(
            $"expected a JSON object, got {Preview(body)}");
    }

    private static string ErrorMessage(byte[] body, string fallback)
    {
        try
        {
            using var document = JsonDocument.Parse(new ReadOnlyMemory<byte>(body));
            if (document.RootElement.ValueKind == JsonValueKind.Object
                && document.RootElement.TryGetProperty("mensagem", out var message)
                && message.ValueKind == JsonValueKind.String
                && message.GetString() is { Length: > 0 } text)
            {
                return text;
            }
        }
        catch (JsonException)
        {
            return fallback;
        }

        return fallback;
    }

    /// <summary>
    /// Read the <c>faixa</c> block out of a 404 body, when it has one.
    /// </summary>
    /// <remarks>
    /// The block is optional and always will be: the API omits it — it does not
    /// send a null — for a CEP in a band no municipality owns. Absent,
    /// misshapen or unreadable, the answer here is <see langword="null"/> and
    /// the caller still gets the plain not-found it was going to get anyway.
    /// </remarks>
    /// <param name="body">the 404 body</param>
    /// <returns>the municipality the CEP would belong to, or null</returns>
    private static Faixa? ReadFaixa(byte[] body)
    {
        try
        {
            using var document = JsonDocument.Parse(new ReadOnlyMemory<byte>(body));
            if (document.RootElement.ValueKind == JsonValueKind.Object
                && document.RootElement.TryGetProperty("faixa", out var faixa))
            {
                return FaixaReader.Read(faixa);
            }
        }
        catch (JsonException)
        {
            return null;
        }

        return null;
    }

    /// <summary>
    /// What to tell the caller about a CEP that is not in the database.
    /// </summary>
    /// <remarks>
    /// The municipality goes in the message when the API named one, because the
    /// message is what ends up in a log, and "the range belongs to Areal/RJ" is
    /// the difference between a dead end and a question worth asking the user.
    /// The count is in it for the same reason the API sends it: so nobody reads
    /// the two ends as a list of CEPs to walk.
    /// </remarks>
    /// <param name="cep">the eight digits</param>
    /// <param name="faixa">the municipality it would belong to, if any</param>
    /// <returns>the message</returns>
    private static string NotFoundMessage(string cep, Faixa? faixa)
    {
        var message = $"CEP {cep} does not exist in the DNE database";
        return faixa is null
            ? message
            : message + $" — the range belongs to {faixa.Localidade}/{faixa.UF}, "
                + $"which has {faixa.Ceps} CEP(s) between {faixa.CepIni} and {faixa.CepFim}";
    }

    private static string Preview(byte[] body) =>
        Encoding.UTF8.GetString(body, 0, Math.Min(body.Length, 120));

    /// <summary>
    /// Turn one CSV record into an address, or null when there is none.
    /// </summary>
    /// <remarks>
    /// The CSV column names are the JSON field names, so the record is routed
    /// through the same mapping as a native lookup rather than a second,
    /// drifting copy of it. A record the API filled only the <c>cep</c> column
    /// of means "not found".
    /// </remarks>
    /// <param name="row">the record, by column name</param>
    /// <returns>the address, or null</returns>
    private static Address? AddressFromRow(Dictionary<string, string> row)
    {
        if (!row.TryGetValue("localidade", out var localidade) || string.IsNullOrWhiteSpace(localidade))
        {
            return null;
        }

        return JsonSerializer.SerializeToElement(row).Deserialize<Address>(JsonOptions);
    }

    private static string? FirstHeader(HttpResponseMessage response, string name) =>
        response.Headers.TryGetValues(name, out var values) ? values.FirstOrDefault() : null;

    /// <summary>
    /// One chunk of at most <see cref="MaxBatch"/> CEPs, in a single request.
    /// </summary>
    /// <remarks>
    /// The API guarantees one record per requested CEP. Should that ever fail to
    /// hold — a proxy truncating, a cut response — the result is padded to the
    /// input length rather than returned short, because a shifted list silently
    /// pairs the wrong address with the wrong CEP.
    /// </remarks>
    /// <param name="ceps">the chunk</param>
    /// <param name="cancellationToken">cancels the call</param>
    /// <returns>one entry per CEP in the chunk, in order</returns>
    private async Task<List<Address?>> LookupChunkAsync(
        List<string> ceps,
        CancellationToken cancellationToken)
    {
        var query = "/csv?ceps=" + Uri.EscapeDataString(string.Join(',', ceps));
        var reply = await RequestAsync(query, OkOnly, cancellationToken).ConfigureAwait(false);

        var rows = new List<Address?>(ceps.Count);
        foreach (var row in Csv.Parse(Encoding.UTF8.GetString(reply.Body)))
        {
            rows.Add(AddressFromRow(row));
        }

        while (rows.Count < ceps.Count)
        {
            rows.Add(null);
        }

        return rows.Count > ceps.Count ? rows.GetRange(0, ceps.Count) : rows;
    }

    /// <summary>
    /// Perform the GET, with retries.
    /// </summary>
    /// <remarks>
    /// <para>
    /// <i>Definitive</i> error statuses (400, 404) are returned normally, for
    /// the caller to turn into the right exception — only transient failures
    /// become exceptions here, and only once the attempts are exhausted.
    /// </para>
    /// <para>
    /// <see cref="CepisClientOptions.TotalTimeout"/> arms its own token, which
    /// cuts an attempt that is still in flight and any wait between attempts,
    /// so the whole call really is bounded. That token is also how an abort is
    /// told apart from a transport failure — asking it, rather than comparing a
    /// clock against the budget, is what keeps the two from racing. The abort
    /// does not overwrite the diagnosis: a caller whose budget ran out while
    /// the API was answering 503 is told about the 503, not about a
    /// cancellation it did not ask for.
    /// </para>
    /// </remarks>
    /// <param name="path">the path, query included</param>
    /// <param name="acceptedStatus">statuses to hand back rather than retry</param>
    /// <param name="cancellationToken">cancels the call</param>
    /// <returns>the status and the body</returns>
    private async Task<Reply> RequestAsync(
        string path,
        FrozenSet<int> acceptedStatus,
        CancellationToken cancellationToken)
    {
        var uri = _baseUrl + path;

        using var deadline = _options.TotalTimeout is null
            ? null
            : CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
        deadline?.CancelAfter(_options.TotalTimeout!.Value);
        var callToken = deadline?.Token ?? cancellationToken;

        var attempts = 0;
        var lastStatus = 0;
        TimeSpan? lastRetryAfter = null;
        Exception? lastFailure = null;

        for (var attempt = 1; attempt <= _options.MaxAttempts; attempt++)
        {
            cancellationToken.ThrowIfCancellationRequested();
            if (deadline is { IsCancellationRequested: true })
            {
                break;
            }

            attempts = attempt;

            using var request = new HttpRequestMessage(HttpMethod.Get, uri);
            request.Headers.TryAddWithoutValidation("User-Agent", UserAgent);
            request.Headers.TryAddWithoutValidation("Accept", AcceptHeader);

            using var attemptCancellation = CancellationTokenSource.CreateLinkedTokenSource(callToken);
            attemptCancellation.CancelAfter(_options.Timeout);

            try
            {
                using var response = await _http
                    .SendAsync(request, HttpCompletionOption.ResponseContentRead, attemptCancellation.Token)
                    .ConfigureAwait(false);

                var status = (int)response.StatusCode;
                if (acceptedStatus.Contains(status) || !RetriableStatus.Contains(status))
                {
                    var body = await response.Content
                        .ReadAsByteArrayAsync(attemptCancellation.Token)
                        .ConfigureAwait(false);
                    return new Reply(status, body);
                }

                lastStatus = status;
                lastRetryAfter = ParseRetryAfter(FirstHeader(response, "Retry-After"));
                lastFailure = null;
            }
            catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
            {
                throw;
            }
            catch (Exception unreachable) when (unreachable is HttpRequestException
                or OperationCanceledException
                or SocketException
                or IOException)
            {
                if (deadline is { IsCancellationRequested: true })
                {
                    if (lastStatus == 0)
                    {
                        lastFailure = unreachable;
                    }

                    break;
                }

                lastFailure = unreachable;
                lastStatus = 0;
                lastRetryAfter = null;
            }

            if (attempt == _options.MaxAttempts)
            {
                break;
            }

            if (!await WaitBeforeRetryAsync(attempt, lastRetryAfter, callToken, cancellationToken)
                .ConfigureAwait(false))
            {
                break;
            }
        }

        var suffix = $" (after {attempts} attempt(s))";
        if (lastStatus == 429)
        {
            throw new RateLimitedException($"rate limit reached at {uri}{suffix}", lastRetryAfter);
        }

        if (lastStatus != 0)
        {
            throw new ServerErrorException(
                $"the API answered {lastStatus} at {uri}{suffix}", lastStatus);
        }

        throw new NetworkException(
            $"could not reach {uri}{suffix}: {lastFailure?.Message}", lastFailure);
    }

    /// <summary>
    /// Wait out the backoff, reporting whether there is still budget to retry.
    /// </summary>
    /// <remarks>
    /// The wait is cut short by <paramref name="callToken"/>, so a
    /// <see cref="CepisClientOptions.TotalTimeout"/> that expires mid-wait ends
    /// the call rather than being overrun. A cancellation the caller asked for
    /// propagates instead.
    /// </remarks>
    /// <param name="attempt">which attempt just failed, from one</param>
    /// <param name="retryAfter">what the server asked for, if anything</param>
    /// <param name="callToken">the deadline, or the caller's token</param>
    /// <param name="cancellationToken">the caller's token alone</param>
    /// <returns>false when the budget is spent</returns>
    private async Task<bool> WaitBeforeRetryAsync(
        int attempt,
        TimeSpan? retryAfter,
        CancellationToken callToken,
        CancellationToken cancellationToken)
    {
        var wait = Backoff(attempt, retryAfter);
        if (wait <= TimeSpan.Zero)
        {
            return !callToken.IsCancellationRequested;
        }

        try
        {
            await Task.Delay(wait, callToken).ConfigureAwait(false);
            return true;
        }
        catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
        {
            return false;
        }
    }

    /// <summary>
    /// How long to wait before the next attempt.
    /// </summary>
    /// <remarks>
    /// The server's <c>Retry-After</c> wins over the local calculation when
    /// present: it knows when it will be back, we are guessing. It still goes
    /// through the <see cref="CepisClientOptions.BackoffMax"/> cap. Otherwise
    /// the wait is drawn from <c>[0, ceiling]</c> rather than being the ceiling.
    /// </remarks>
    /// <param name="attempt">which attempt just failed, from one</param>
    /// <param name="retryAfter">what the server asked for, if anything</param>
    /// <returns>the wait</returns>
    internal TimeSpan Backoff(int attempt, TimeSpan? retryAfter)
    {
        var ceiling = _options.BackoffMax.TotalMilliseconds;
        if (retryAfter is { } asked)
        {
            return TimeSpan.FromMilliseconds(Math.Min(asked.TotalMilliseconds, ceiling));
        }

        var exponential = _options.BackoffBase.TotalMilliseconds * Math.Pow(2, Math.Min(attempt - 1, 32));
        return TimeSpan.FromMilliseconds(Random.Shared.NextDouble() * Math.Min(exponential, ceiling));
    }

    private readonly record struct Reply(int Status, byte[] Body);
}