diff options
Diffstat (limited to 'src/client.zig')
| -rw-r--r-- | src/client.zig | 804 |
1 files changed, 804 insertions, 0 deletions
diff --git a/src/client.zig b/src/client.zig new file mode 100644 index 0000000..3a726e5 --- /dev/null +++ b/src/client.zig @@ -0,0 +1,804 @@ +//! The HTTP client, built on `std.http.Client` from the standard library. +//! +//! Retry policy: 429 and the transient 5xx in `retriable_status`, plus network +//! failures, are retried with exponentially backed-off, jittered waits. 400 and +//! 404 are deliberately absent from that set — both are definitive answers +//! about the request, so retrying returns the same thing more slowly while +//! burning someone else's quota. + +const std = @import("std"); +const Allocator = std.mem.Allocator; +const Io = std.Io; + +const csv = @import("csv.zig"); +const errors = @import("errors.zig"); +const model = @import("model.zig"); +const retry = @import("retry.zig"); + +const Address = model.Address; +const Diagnostics = errors.Diagnostics; +const Error = errors.Error; +const Health = model.Health; +const note = errors.note; + +/// The version of this library, as sent in the `User-Agent`. +pub const version = "0.1.0"; + +/// Where the public API lives. +pub const default_url = "https://cep.is"; + +/// How many CEPs the batch endpoint accepts in one request. +pub const max_batch = 500; + +/// The statuses worth trying again: rate limiting and the transient 5xx. +pub const retriable_status = [_]u16{ 429, 500, 502, 503, 504 }; + +/// The `User-Agent` sent unless `Config.user_agent` overrides it. Identifying +/// the library and its version is what lets the server diagnose an old client +/// misbehaving. +pub const default_user_agent = "cepis-zig/" ++ version ++ " (+https://cep.is)"; + +const accept_header = "application/json, text/csv;q=0.9, */*;q=0.1"; + +/// Refuse to buffer more than this from one response. The largest legitimate +/// answer is a 500-row CSV, comfortably under a megabyte. +const max_body_bytes = 16 * 1024 * 1024; + +/// Everything that can go wrong building a `Client`. Distinct from `Error` +/// because a bad configuration is a programming mistake, not a runtime +/// condition to be retried. +pub const InitError = Allocator.Error || error{ + /// `max_attempts` is 0, or `timeout_ms` is 0 — either produces a client + /// that can never complete a call. + InvalidConfiguration, +}; + +/// How a `Client` behaves. Every field has a default; set only what differs. +pub const Config = struct { + /// Where the API lives. + /// + /// Point it at a local instance (the API repo brings one up on + /// `http://localhost:8080` with `just up`) or at a test server. It is the + /// only setting that usually changes between environments. A trailing slash + /// is stripped, so it cannot produce doubled separators that some proxies + /// normalise and others 404. Copied on `init`; the caller keeps ownership. + base_url: []const u8 = default_url, + + /// How long to wait for the TCP and TLS handshake, in milliseconds. + /// + /// This is **not** a cap on the whole call, and Zig 0.16's + /// `std.http.Client` exposes no per-read timeout, so a server that accepts + /// the connection and then stalls is bounded only by `total_timeout_ms`. + /// Set that one in code serving a web request. + timeout_ms: u64 = 10_000, + + /// How many attempts in total, counting the first. + /// + /// 1 disables retrying. The default of 3 covers the common case (one + /// transient failure) without turning a real outage into a long wait. + max_attempts: u32 = 3, + + /// Base of the exponential wait, in milliseconds. + /// + /// The actual wait is drawn from `[0, base * 2^(n-1)]` — *full jitter*. The + /// randomness is not decoration: without it, N clients that fail together + /// come back together and reproduce the spike that took the service down. + backoff_base_ms: u64 = 500, + + /// Cap on each individual wait, in milliseconds. + /// + /// It applies to a server-sent `Retry-After` too, or a `Retry-After: 3600` + /// from a misconfigured proxy would park the caller for an hour. + backoff_max_ms: u64 = 8_000, + + /// Cap on the whole call, attempts and waits included, in milliseconds. + /// + /// Null leaves `max_attempts` as the only bound. + total_timeout_ms: ?u64 = null, + + /// Overrides the `User-Agent`. Copied on `init`; the caller keeps + /// ownership. + user_agent: []const u8 = default_user_agent, + + /// Seed for the backoff jitter. Null draws one from the system, which is + /// what you want; set it only to make a test deterministic. + jitter_seed: ?u64 = null, +}; + +/// Per-call knobs shared by every method. +pub const CallOptions = struct { + /// Where to record the HTTP status, the `Retry-After` and the API's own + /// message when the call fails. Null discards them. + diagnostics: ?*Diagnostics = null, +}; + +/// Return the CEP's 8 digits, accepting the mask. +/// +/// `"01001-000"`, `"01001000"` and `" 01001-000 "` all become `"01001000"`. +/// +/// Fails with `error.InvalidCep` unless exactly 8 digits remain. This runs +/// **before** any request: a 7-digit CEP is the caller's bug, and spending a +/// round trip for the server to say so wastes both sides' time. +/// +/// ## Ownership +/// +/// The result borrows `buffer`; it is valid for as long as `buffer` is. No +/// allocation happens. +pub fn normalizeCep(value: []const u8, buffer: *[8]u8) error{InvalidCep}![]const u8 { + var n: usize = 0; + for (std.mem.trim(u8, value, " \t\r\n")) |c| { + switch (c) { + '-', '.', ' ' => continue, + '0'...'9' => { + if (n == buffer.len) return error.InvalidCep; + buffer[n] = c; + n += 1; + }, + else => return error.InvalidCep, + } + } + if (n != buffer.len) return error.InvalidCep; + return buffer[0..]; +} + +/// Client for the cep.is API. +/// +/// Build one and reuse it: the configuration is immutable after `init`, no +/// method keeps state between calls, and the underlying connection pool is +/// shared — so a second lookup on the same host skips the TLS handshake. +/// Sharing one across threads is safe. +/// +/// ```zig +/// var threaded: std.Io.Threaded = .init(gpa, .{}); +/// defer threaded.deinit(); +/// +/// var client: cepis.Client = try .init(gpa, threaded.io(), .{}); +/// defer client.deinit(); +/// +/// var address = try client.lookup("01001-000", .{}); +/// defer address.deinit(gpa); +/// ``` +pub const Client = struct { + /// The allocator every returned value was built with. Pass it to + /// `Address.deinit`, `Health.deinit` and `freeAddresses`. + gpa: Allocator, + io: Io, + http: std.http.Client, + + /// The API URL in use, without a trailing slash. Owned by the client. + base_url: []u8, + /// The `User-Agent` sent with every request. Owned by the client. + user_agent: []u8, + + timeout_ms: u64, + max_attempts: u32, + backoff_base_ms: u64, + backoff_max_ms: u64, + total_timeout_ms: ?u64, + + prng: std.Random.DefaultPrng, + /// Guards `prng` and the lazy trust-store load, so one `Client` can be + /// shared across threads. + mutex: Io.Mutex, + + /// Build a client. `io` and `gpa` must outlive it. + /// + /// Fails with `error.InvalidConfiguration` when `max_attempts` is 0 or + /// `timeout_ms` is 0 — both describe a client that can never complete a + /// call. Call `deinit` when done. + pub fn init(gpa: Allocator, io: Io, config: Config) InitError!Client { + if (config.max_attempts < 1) return error.InvalidConfiguration; + if (config.timeout_ms == 0) return error.InvalidConfiguration; + + const trimmed = std.mem.trimEnd(u8, config.base_url, "/"); + const base_url = try gpa.dupe(u8, trimmed); + errdefer gpa.free(base_url); + + const user_agent = try gpa.dupe(u8, config.user_agent); + errdefer gpa.free(user_agent); + + const seed = config.jitter_seed orelse seed: { + const now = Io.Timestamp.now(io, .real); + break :seed @as(u64, @truncate(@as(u128, @bitCast(@as(i128, now.nanoseconds))))); + }; + + return .{ + .gpa = gpa, + .io = io, + .http = .{ .allocator = gpa, .io = io }, + .base_url = base_url, + .user_agent = user_agent, + .timeout_ms = config.timeout_ms, + .max_attempts = config.max_attempts, + .backoff_base_ms = config.backoff_base_ms, + .backoff_max_ms = config.backoff_max_ms, + .total_timeout_ms = config.total_timeout_ms, + .prng = .init(seed), + .mutex = .init, + }; + } + + /// Close every pooled connection and release the client's own memory. + /// + /// Values already returned by `lookup`, `lookupMany` and `health` are not + /// touched: they own their memory and outlive the client. + pub fn deinit(c: *Client) void { + c.http.deinit(); + c.gpa.free(c.base_url); + c.gpa.free(c.user_agent); + c.* = undefined; + } + + /// Look up a single CEP. + /// + /// The CEP may be masked or not. This is the only way to obtain a + /// coordinate — see `lookupMany` for why. + /// + /// A 400 from the API becomes `error.InvalidCep` with the API's own message + /// in `Diagnostics`: the format already passed local validation, so the + /// server knows something this client does not. + /// + /// Errors: `error.InvalidCep` (not 8 digits — no request is made), + /// `error.NotFound`, `error.RateLimited`, `error.ServerError`, + /// `error.NetworkError`, `error.InvalidResponse`, `error.OutOfMemory`. + /// + /// ## Ownership + /// + /// The returned `Address` owns its memory. Call `address.deinit(client.gpa)`. + pub fn lookup(c: *Client, cep: []const u8, options: CallOptions) Error!Address { + var digits: [8]u8 = undefined; + const number = normalizeCep(cep, &digits) catch { + note(options.diagnostics, "CEP must be 8 digits, got \"{s}\"", .{cep}); + return error.InvalidCep; + }; + + var path_buffer: [16]u8 = undefined; + const path = std.fmt.bufPrint(&path_buffer, "/{s}", .{number}) catch unreachable; + + const response = try c.request(path, null, &.{200}, options.diagnostics); + defer c.gpa.free(response.body); + + if (response.status == 404) { + note(options.diagnostics, "CEP {s} does not exist in the DNE database", .{number}); + return error.NotFound; + } + if (response.status == 400) { + noteApiMessage(options.diagnostics, response.body, "CEP {s} rejected", .{number}); + return error.InvalidCep; + } + + const parsed = try c.parseJsonObject(response.body, options.diagnostics); + defer parsed.deinit(); + + return Address.fromJson(c.gpa, parsed.value, response.body); + } + + /// Look up many CEPs in one batch. + /// + /// Returns a slice of **the same length and in the same order** as the + /// input. A CEP that does not exist becomes null at its position — it does + /// not vanish from the list, and it is not an error. That is the right + /// difference from `lookup`: in a batch of a thousand, one bad CEP must not + /// cost the other nine hundred and ninety-nine. + /// + /// A malformed CEP also becomes null, for the same reason. If you need to + /// know *which* one was malformed, validate first with `normalizeCep`. + /// + /// Input is chunked into blocks of `max_batch` automatically. Do not loop + /// over `lookup` instead: 500 calls pay 500 round trips, the batch pays one. + /// + /// **Batches carry no coordinate.** The endpoint behind them is CSV, and the + /// CSV has no `geo` column. Every `Address` returned here has `geo == null`, + /// including for CEPs that do have one. Need `geo`? Use `lookup`, one at a + /// time. + /// + /// Errors are transport failures only — `error.RateLimited`, + /// `error.ServerError`, `error.NetworkError`, `error.InvalidResponse`, + /// `error.OutOfMemory`. A bad CEP never fails a batch. + /// + /// ## Ownership + /// + /// The returned slice and every `Address` in it are owned by the caller. + /// Release the lot with `cepis.freeAddresses(client.gpa, result)`. + pub fn lookupMany(c: *Client, ceps: []const []const u8, options: CallOptions) Error![]?Address { + const result = try c.gpa.alloc(?Address, ceps.len); + errdefer freeAddresses(c.gpa, result); + @memset(result, null); + if (ceps.len == 0) return result; + + var start: usize = 0; + while (start < ceps.len) : (start += max_batch) { + const end = @min(start + max_batch, ceps.len); + try c.lookupChunk(ceps[start..end], result[start..end], options); + } + return result; + } + + /// Query `GET /health`: does the API answer, and with which database. + /// + /// An API reporting itself degraded is not an error — that arrives in + /// `Health.status`, and checking health is exactly when you want the + /// diagnosis rather than a failure. Network failures still fail. + /// + /// ## Ownership + /// + /// The returned `Health` owns its memory. Call `health.deinit(client.gpa)`. + pub fn health(c: *Client, options: CallOptions) Error!Health { + const response = try c.request("/health", null, &.{ 200, 503 }, options.diagnostics); + defer c.gpa.free(response.body); + + const parsed = try c.parseJsonObject(response.body, options.diagnostics); + defer parsed.deinit(); + + return Health.fromJson(c.gpa, parsed.value, response.body); + } + + /// One chunk of at most `max_batch` CEPs, in a single request, written into + /// `out` which is already null-filled and exactly as long as `ceps`. + /// + /// A blank CSV row means "not found": the API fills only the `cep` column + /// and leaves the rest empty, precisely so it does not misalign whoever is + /// consuming the batch in a spreadsheet. + /// + /// The API guarantees one row per requested CEP. Should that ever fail to + /// hold — a proxy truncating, a cut response — the extra positions stay null + /// rather than the result being returned short, because a shifted list + /// silently pairs the wrong address with the wrong CEP. + fn lookupChunk( + c: *Client, + ceps: []const []const u8, + out: []?Address, + options: CallOptions, + ) Error!void { + const query = try buildBatchQuery(c.gpa, ceps); + defer c.gpa.free(query); + + const response = try c.request("/csv", query, &.{200}, options.diagnostics); + defer c.gpa.free(response.body); + + const records = try csv.parse(c.gpa, response.body); + defer csv.free(c.gpa, records); + + if (records.len < 2) return; + const header = records[0]; + const localidade = columnIndex(header, "localidade"); + + for (records[1..], 0..) |record, i| { + if (i >= out.len) break; + const found = if (localidade) |column| + column < record.len and std.mem.trim(u8, record[column], " \t").len != 0 + else + false; + if (!found) continue; + out[i] = try Address.fromCsvRecord(c.gpa, header, record); + } + } + + /// One HTTP response, buffered. + const Response = struct { + status: u16, + /// Owned by `Client.gpa`; free it. + body: []u8, + retry_after_ms: ?u64, + }; + + /// Perform the GET, with retries. `query` is appended to `path` as-is and + /// must already be percent-encoded, or be null. + /// + /// *Definitive* error statuses (400, 404) come back normally, for the + /// caller to turn into the right error — only transient failures become + /// errors here, and only once the attempts are exhausted. `accepted` lists + /// the statuses to hand back even though they would otherwise be retried, + /// which is how `/health` gets its 503. + fn request( + c: *Client, + path: []const u8, + query: ?[]const u8, + accepted: []const u16, + diagnostics: ?*Diagnostics, + ) Error!Response { + const url = try std.fmt.allocPrint(c.gpa, "{s}{s}{s}{s}", .{ + c.base_url, + path, + if (query != null) "?" else "", + query orelse "", + }); + defer c.gpa.free(url); + + const started = Io.Timestamp.now(c.io, .awake); + + var last_status: ?u16 = null; + var last_retry_after: ?u64 = null; + var attempts: u32 = 0; + + var attempt: u32 = 1; + while (attempt <= c.max_attempts) : (attempt += 1) { + if (c.remainingMs(started)) |left| { + if (left == 0) break; + } + attempts = attempt; + + if (c.attemptOnce(url, diagnostics)) |response| { + const definitive = !isRetriable(response.status) or contains(accepted, response.status); + if (definitive) { + if (diagnostics) |d| { + d.status = response.status; + d.attempts = attempts; + } + return response; + } + c.gpa.free(response.body); + last_status = response.status; + last_retry_after = response.retry_after_ms; + } else |err| switch (err) { + error.OutOfMemory => return error.OutOfMemory, + error.InvalidResponse => { + if (diagnostics) |d| d.attempts = attempts; + return error.InvalidResponse; + }, + error.NetworkError => { + last_status = null; + last_retry_after = null; + }, + } + + if (attempt == c.max_attempts) break; + + var wait = c.backoffMs(attempt, last_retry_after); + if (c.remainingMs(started)) |left| { + if (left == 0) break; + wait = @min(wait, left); + } + c.sleepMs(wait); + } + + if (diagnostics) |d| { + d.status = last_status; + d.retry_after_ms = last_retry_after; + d.attempts = attempts; + } + + if (last_status) |status| { + if (status == 429) { + note(diagnostics, "rate limit reached at {s} (after {d} attempt(s))", .{ url, attempts }); + return error.RateLimited; + } + note(diagnostics, "the API answered {d} at {s} (after {d} attempt(s))", .{ status, url, attempts }); + return error.ServerError; + } + + if (attempts == 0) { + note(diagnostics, "no attempt was made at {s} within the total timeout", .{url}); + } + return error.NetworkError; + } + + /// A single request/response round trip. `error.NetworkError` means the + /// exchange never completed and is worth retrying; the message explaining + /// which transport error it was is already in `diagnostics`. + fn attemptOnce( + c: *Client, + url: []const u8, + diagnostics: ?*Diagnostics, + ) (error{ NetworkError, InvalidResponse } || Allocator.Error)!Response { + const uri = std.Uri.parse(url) catch { + note(diagnostics, "{s} is not a usable URL", .{url}); + return error.NetworkError; + }; + + const connection = c.connectWithTimeout(uri) catch |err| { + note(diagnostics, "could not reach {s}: {t}", .{ url, err }); + return if (err == error.OutOfMemory) error.OutOfMemory else error.NetworkError; + }; + var req = c.http.request(.GET, uri, .{ + .connection = connection, + .keep_alive = true, + .headers = .{ + .user_agent = .{ .override = c.user_agent }, + .accept_encoding = .{ .override = "identity" }, + }, + .extra_headers = &.{.{ .name = "accept", .value = accept_header }}, + }) catch |err| { + c.http.connection_pool.release(connection, c.io); + note(diagnostics, "could not reach {s}: {t}", .{ url, err }); + return if (err == error.OutOfMemory) error.OutOfMemory else error.NetworkError; + }; + defer req.deinit(); + + req.sendBodiless() catch |err| { + note(diagnostics, "could not send the request to {s}: {t}", .{ url, err }); + return error.NetworkError; + }; + + var redirect_buffer: [8192]u8 = undefined; + var response = req.receiveHead(&redirect_buffer) catch |err| { + note(diagnostics, "no usable response from {s}: {t}", .{ url, err }); + return if (err == error.OutOfMemory) error.OutOfMemory else error.NetworkError; + }; + + const status: u16 = @intFromEnum(response.head.status); + const retry_after_ms = c.readRetryAfter(response.head); + + const decompress_buffer: []u8 = switch (response.head.content_encoding) { + .identity => &.{}, + .zstd => try c.gpa.alloc(u8, std.compress.zstd.default_window_len), + .deflate, .gzip => try c.gpa.alloc(u8, std.compress.flate.max_window_len), + .compress => { + note(diagnostics, "{s} answered with an unsupported content encoding", .{url}); + return error.InvalidResponse; + }, + }; + defer c.gpa.free(decompress_buffer); + + var transfer_buffer: [4096]u8 = undefined; + var decompress: std.http.Decompress = undefined; + const reader = response.readerDecompressing(&transfer_buffer, &decompress, decompress_buffer); + + const body = reader.allocRemaining(c.gpa, .limited(max_body_bytes)) catch |err| { + note(diagnostics, "could not read the response from {s}: {t}", .{ url, err }); + return switch (err) { + error.OutOfMemory => error.OutOfMemory, + error.StreamTooLong => error.InvalidResponse, + else => error.NetworkError, + }; + }; + + return .{ .status = status, .body = body, .retry_after_ms = retry_after_ms }; + } + + /// Open (or reuse) a connection, giving the handshake at most + /// `timeout_ms`. + /// + /// `std.http.Client.request` connects with no timeout at all, so a host + /// that blackholes packets would hang the caller until the kernel gives + /// up. Connecting first and handing the connection over is how `timeout_ms` + /// is made to mean something. Proxy support is skipped along the way — this + /// library never configures one. + fn connectWithTimeout(c: *Client, uri: std.Uri) !*std.http.Client.Connection { + const protocol = std.http.Client.Protocol.fromUri(uri) orelse + return error.UnsupportedUriScheme; + if (protocol == .tls) try c.ensureTrustStore(); + var host_buffer: [std.Io.net.HostName.max_len]u8 = undefined; + const host = try uri.getHost(&host_buffer); + const port = uri.port orelse switch (protocol) { + .plain => @as(u16, 80), + .tls => @as(u16, 443), + }; + return c.http.connectTcpOptions(.{ + .host = host, + .port = port, + .protocol = protocol, + .timeout = .{ .duration = .{ + .raw = .fromNanoseconds(@as(i96, c.timeout_ms) * std.time.ns_per_ms), + .clock = .awake, + } }, + }); + } + + /// Load the system trust store into the underlying `std.http.Client`, once. + /// + /// `std.http.Client.request` does this lazily on the first HTTPS request; + /// `connectTcpOptions`, which is the only entry point that takes a timeout, + /// assumes it has already happened and panics otherwise. Doing it here is + /// what makes `timeout_ms` and `https://` coexist. + fn ensureTrustStore(c: *Client) !void { + if (!std.http.Client.disable_tls) { + c.mutex.lockUncancelable(c.io); + defer c.mutex.unlock(c.io); + if (c.http.now != null) return; + + const now = Io.Clock.real.now(c.io); + var bundle: std.crypto.Certificate.Bundle = .empty; + errdefer bundle.deinit(c.gpa); + bundle.rescan(c.gpa, c.io, now) catch |err| switch (err) { + error.OutOfMemory => return error.OutOfMemory, + else => return error.CertificateBundleLoadFailure, + }; + c.http.ca_bundle = bundle; + c.http.now = now; + } + } + + fn readRetryAfter(c: *Client, head: std.http.Client.Response.Head) ?u64 { + var it = head.iterateHeaders(); + while (it.next()) |header| { + if (!std.ascii.eqlIgnoreCase(header.name, "retry-after")) continue; + const now = Io.Timestamp.now(c.io, .real); + const now_unix: i64 = @intCast(@divFloor(now.nanoseconds, std.time.ns_per_s)); + return retry.parseRetryAfter(header.value, now_unix); + } + return null; + } + + /// How long to wait before the next attempt. + /// + /// The server's `Retry-After` wins over the local calculation when present: + /// it knows when it will be back, we are guessing. It still goes through the + /// `backoff_max_ms` cap. Otherwise the wait is drawn from `[0, ceiling]` + /// rather than being the ceiling. + fn backoffMs(c: *Client, attempt: u32, retry_after_ms: ?u64) u64 { + if (retry_after_ms) |asked| return @min(asked, c.backoff_max_ms); + + const ceiling = retry.ceilingMs(attempt, c.backoff_base_ms, c.backoff_max_ms); + c.mutex.lockUncancelable(c.io); + defer c.mutex.unlock(c.io); + return retry.jitter(c.prng.random(), ceiling); + } + + /// Milliseconds left of `total_timeout_ms`, or null when there is no cap. + fn remainingMs(c: *Client, started: Io.Timestamp) ?u64 { + const cap = c.total_timeout_ms orelse return null; + const now = Io.Timestamp.now(c.io, .awake); + const elapsed_ns = started.durationTo(now).nanoseconds; + if (elapsed_ns <= 0) return cap; + const elapsed_ms: u128 = @intCast(@divFloor(elapsed_ns, std.time.ns_per_ms)); + if (elapsed_ms >= cap) return 0; + return cap - @as(u64, @intCast(elapsed_ms)); + } + + fn sleepMs(c: *Client, ms: u64) void { + if (ms == 0) return; + c.io.sleep(.fromNanoseconds(@as(i96, ms) * std.time.ns_per_ms), .awake) catch {}; + } + + fn parseJsonObject( + c: *Client, + body: []const u8, + diagnostics: ?*Diagnostics, + ) Error!std.json.Parsed(std.json.Value) { + const parsed = std.json.parseFromSlice(std.json.Value, c.gpa, body, .{}) catch |err| { + if (err == error.OutOfMemory) return error.OutOfMemory; + note( + diagnostics, + "response is not valid JSON — something between you and the API is " ++ + "answering instead of it: \"{s}\"", + .{preview(body)}, + ); + return error.InvalidResponse; + }; + errdefer parsed.deinit(); + + switch (parsed.value) { + .object => return parsed, + else => { + note(diagnostics, "expected a JSON object, got \"{s}\"", .{preview(body)}); + return error.InvalidResponse; + }, + } + } +}; + +/// Release a slice returned by `Client.lookupMany`, and every `Address` in it. +pub fn freeAddresses(gpa: Allocator, list: []?Address) void { + for (list) |*slot| { + if (slot.*) |*address| address.deinit(gpa); + } + gpa.free(list); +} + +/// Build `ceps=a,b,c`, percent-encoding anything that is not safe in a query. +/// +/// The caller's CEPs are not validated here — a malformed one is answered with +/// an empty row and becomes null, which is the documented behaviour of +/// `lookupMany`. Encoding is still required so a stray `&` or space cannot +/// rewrite the query string. +/// +/// The result is owned by the caller. +fn buildBatchQuery(gpa: Allocator, ceps: []const []const u8) Allocator.Error![]u8 { + var out: std.ArrayList(u8) = .empty; + errdefer out.deinit(gpa); + + try out.appendSlice(gpa, "ceps="); + for (ceps, 0..) |cep, i| { + if (i != 0) try out.appendSlice(gpa, ","); + for (cep) |char| switch (char) { + 'A'...'Z', 'a'...'z', '0'...'9', '-', '.', '_', '~' => try out.append(gpa, char), + else => try out.print(gpa, "%{X:0>2}", .{char}), + }; + } + return out.toOwnedSlice(gpa); +} + +fn columnIndex(header: []const []const u8, name: []const u8) ?usize { + for (header, 0..) |column, i| { + if (std.mem.eql(u8, std.mem.trim(u8, column, " \t"), name)) return i; + } + return null; +} + +fn contains(haystack: []const u16, needle: u16) bool { + for (haystack) |value| { + if (value == needle) return true; + } + return false; +} + +fn isRetriable(status: u16) bool { + return contains(&retriable_status, status); +} + +/// Pull `mensagem` out of an error body into `diagnostics`, falling back to a +/// formatted default when the body says nothing useful. +fn noteApiMessage( + diagnostics: ?*Diagnostics, + body: []const u8, + comptime fallback: []const u8, + args: anytype, +) void { + const d = diagnostics orelse return; + + var buffer: [4096]u8 = undefined; + var fba: std.heap.FixedBufferAllocator = .init(&buffer); + if (std.json.parseFromSlice(std.json.Value, fba.allocator(), body, .{})) |parsed| { + defer parsed.deinit(); + switch (parsed.value) { + .object => |object| if (object.get("mensagem")) |value| switch (value) { + .string => |text| if (text.len != 0) { + d.setMessage("{s}", .{text}); + return; + }, + else => {}, + }, + else => {}, + } + } else |_| {} + + d.setMessage(fallback, args); +} + +fn preview(body: []const u8) []const u8 { + return body[0..@min(body.len, 120)]; +} + +const testing = std.testing; + +test "normalizeCep accepts the mask" { + var buffer: [8]u8 = undefined; + for ([_][]const u8{ "01001000", "01001-000", " 01001-000 ", "01001.000" }) |value| { + try testing.expectEqualStrings("01001000", try normalizeCep(value, &buffer)); + } +} + +test "normalizeCep rejects anything else" { + var buffer: [8]u8 = undefined; + for ([_][]const u8{ "", "123", "0100100a", "010010000", "abcdefgh", "01001-0000" }) |value| { + try testing.expectError(error.InvalidCep, normalizeCep(value, &buffer)); + } +} + +test "buildBatchQuery joins and encodes" { + const query = try buildBatchQuery(testing.allocator, &.{ "01001000", "a b&c" }); + defer testing.allocator.free(query); + try testing.expectEqualStrings("ceps=01001000,a%20b%26c", query); +} + +test "buildBatchQuery on an empty list is just the key" { + const query = try buildBatchQuery(testing.allocator, &.{}); + defer testing.allocator.free(query); + try testing.expectEqualStrings("ceps=", query); +} + +test "columnIndex finds the column or nothing" { + const header = [_][]const u8{ "cep", "logradouro", "localidade" }; + try testing.expectEqual(@as(?usize, 2), columnIndex(&header, "localidade")); + try testing.expectEqual(@as(?usize, null), columnIndex(&header, "geo")); +} + +test "only transient statuses are retriable" { + for ([_]u16{ 429, 500, 502, 503, 504 }) |status| { + try testing.expect(isRetriable(status)); + } + for ([_]u16{ 200, 400, 404, 501 }) |status| { + try testing.expect(!isRetriable(status)); + } +} + +test "noteApiMessage prefers the API wording" { + var diag: Diagnostics = .{}; + noteApiMessage(&diag, "{\"erro\":\"cep_invalido\",\"mensagem\":\"rejected\"}", "fallback {s}", .{"x"}); + try testing.expectEqualStrings("rejected", diag.message()); + + diag.reset(); + noteApiMessage(&diag, "<html>", "fallback {s}", .{"x"}); + try testing.expectEqualStrings("fallback x", diag.message()); +} |