Initial importv0.1.0

1 files changed, 714 insertions, 0 deletions

diff --git a/src/Cepis/CepisClient.cs b/src/Cepis/CepisClient.cs
new file mode 100644
index 0000000..72637c0
--- /dev/null
+++ b/src/Cepis/CepisClient.cs
@@ -0,0 +1,714 @@
+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.1.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>
+    /// 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"/>.
+    /// </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</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)
+        {
+            throw new CepNotFoundException($"CEP {number} does not exist in the DNE database");
+        }
+
+        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;
+    }
+
+    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);
+}