internetdata 2.9.0

The official Rust client library for the InternetData API: look up IP addresses, AS numbers and domains, and download the IP intelligence databases.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
use std::collections::HashMap;
use std::net::IpAddr;
use std::sync::Arc;
use std::time::Duration;

use futures_util::StreamExt;
use indexmap::IndexMap;
use moka::future::Cache;
use serde::Deserialize;

use crate::bogon::{bogon_lookup, is_bogon, unmapped};
use crate::database::DatabaseApi;
use crate::entitlement::Entitlement;
use crate::error::{Error, ErrorKind};
use crate::flight::{Flights, restate};
use crate::lookup::Lookup;
use crate::models::{AsnLookupResponse, BatchLookupError, BatchLookupRequest};
use crate::models::{DomainLookupResponse, LookupResponse};
use crate::oauth::{OauthApi, OauthError, authorization_server};
use crate::transport::{Transport, encode_path_segment};

/// The production API. Override it with [`ClientBuilder::base_url`].
pub const DEFAULT_BASE_URL: &str = "https://api.internetdata.io";

const DEFAULT_CACHE_CAPACITY: u64 = 10_000;
const DEFAULT_CACHE_TTL: Duration = Duration::from_secs(60 * 60);
const DEFAULT_CONCURRENCY: usize = 8;
const DEFAULT_RETRIES: u32 = 2;
const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
// The CLIENT bounds how long we wait to connect and for the next byte, never the
// whole transfer: a total `.timeout()` on it would also cover a database's body,
// and a download that legitimately takes longer would abort however healthy the
// link is. The whole-request bound is set per API request instead.
const DEFAULT_CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
const DEFAULT_READ_TIMEOUT: Duration = Duration::from_secs(30);
const RETRY_BASE_DELAY: Duration = Duration::from_millis(250);
/// The longest `Retry-After` waited out as given, 2^31 - 1 ms. One past it reads
/// like a header that will not parse, a throttle all the same, so the call waits
/// its own backoff instead: a `Retry-After` of 2147484 held a call for 24.8 days,
/// and 9223372036854775807 or a year-9999 date for good, from the API and object
/// storage alike (2.2.1, measured 2026-09-26), with tokio clamping rather than
/// refusing the sleep.
const MAX_RETRY_AFTER: Duration = Duration::from_millis(2_147_483_647);
/// The most addresses `POST /batch` takes in one call; a larger batch is sent
/// in chunks of this size.
const BATCH_MAX: usize = 1000;

/// A client for the InternetData API.
///
/// Cloning is cheap and shares everything, including the cache and the
/// connection pool, so a clone per task is the intended way to use it across
/// one.
///
/// The cache is per instance and never global: two clients holding different API
/// keys are on different plans and entitled to different fields, so a shared
/// cache would serve one of them the other's shape.
#[derive(Debug, Clone)]
pub struct Client(Arc<Inner>);

#[derive(Debug)]
struct Inner {
    transport: Transport,
    cache: Option<Cache<String, Lookup>>,
    /// The addresses with a request in flight, shared by a lookup and a batch.
    /// Only a client that caches shares them: without a cache every lookup is
    /// served, as [`ClientBuilder::no_cache`] promises.
    flights: Flights,
    concurrency: usize,
    retries: u32,
    timeout: Duration,
}

impl Client {
    /// A client with no API key, against production. Without a key a lookup is
    /// on Unlimited, the free plan, limited per address per minute. A batch
    /// needs a paid plan, and [`Client::my_entitlement`] and every database
    /// published today need a key.
    pub fn new() -> Result<Self, Error> {
        Self::builder().build()
    }

    pub fn builder() -> ClientBuilder {
        ClientBuilder::default()
    }

    /// What every database says about one address.
    ///
    /// A bogon is answered locally and never reaches the network. Everything
    /// else is served, then cached for this client. Calls that miss the cache
    /// while a request for their address is in flight, a batch's included, await
    /// that request rather than sending their own. An IPv4-mapped address
    /// (`::ffff:8.8.8.8`) is the IPv4 address it carries: judged, sent and cached
    /// as that, so the answer names `8.8.8.8`.
    ///
    /// Anything but an IP address is refused as a bad request before it is sent:
    /// the API answers an AS or a domain at the same path, in a shape this call
    /// cannot read, so ask [`Client::lookup_asn`] or [`Client::lookup_domain`].
    pub async fn lookup(&self, ip: &str) -> Result<Lookup, Error> {
        self.lookup_with(ip, LookupOptions::new()).await
    }

    /// [`Client::lookup`], with this call's own retry budget and timeout. A call
    /// that joins a request already in flight takes that request's answer, sent
    /// under the options of the call that led it.
    pub async fn lookup_with(&self, ip: &str, opts: LookupOptions) -> Result<Lookup, Error> {
        let timeout = self.call_timeout(opts.timeout)?;
        let retries = opts.retries.unwrap_or(self.0.retries);
        if ip.parse::<IpAddr>().is_err() {
            return Err(Error::Config(format!(
                "'{ip}' is not an IP address: look up an AS with lookup_asn, and a domain with \
                 lookup_domain"
            )));
        }
        let carried = unmapped(ip);
        let ip: &str = &carried;
        if is_bogon(ip) {
            return Ok(bogon_lookup(ip));
        }
        let Some(cache) = &self.0.cache else {
            return self.serve(ip, retries, timeout).await;
        };

        loop {
            if let Some(hit) = cache.get(ip).await {
                return Ok(hit);
            }
            let (mut pilot, joined) = self.0.flights.board([ip]);
            if let Some((_, flight)) = joined.into_iter().next() {
                match flight.await {
                    Ok(landed) => return restate(&landed),
                    // Its leader was dropped before the answer landed.
                    Err(_) => continue,
                }
            }
            // A request that landed between the miss above and boarding cached
            // its answer before leaving the board, so it is found here.
            let answer = match cache.get(ip).await {
                Some(hit) => Ok(hit),
                None => {
                    let answer = self.serve(ip, retries, timeout).await;
                    if let Ok(lookup) = &answer {
                        cache.insert(ip.to_owned(), lookup.clone()).await;
                    }
                    answer
                }
            };
            pilot.land(ip, &answer);
            return answer;
        }
    }

    async fn serve(&self, ip: &str, retries: u32, timeout: Duration) -> Result<Lookup, Error> {
        let path = format!("/{}", encode_path_segment(ip));
        let answer: LookupResponse =
            with_retry(retries, || self.0.transport.get_json(&path, &[], timeout)).await?;
        Ok(Lookup::served(answer))
    }

    /// What every database says about the address this client is calling from.
    ///
    /// The same answer [`Client::lookup`] would give for that address, at the
    /// same cost against your allowance. The address is the one our edge
    /// observed, so a call made through a proxy or a VPN reports the exit it
    /// left through - usually the point of asking.
    ///
    /// Deliberately NOT cached. The cache is keyed by address, and which
    /// address this is IS the question: a machine that moves between networks
    /// would otherwise be told where it used to be.
    pub async fn my_ip(&self) -> Result<Lookup, Error> {
        self.my_ip_with(LookupOptions::new()).await
    }

    /// [`Client::my_ip`], with this call's own retry budget and timeout.
    pub async fn my_ip_with(&self, opts: LookupOptions) -> Result<Lookup, Error> {
        let timeout = self.call_timeout(opts.timeout)?;
        let answer: LookupResponse = with_retry(opts.retries.unwrap_or(self.0.retries), || {
            self.0.transport.get_json("/myip", &[], timeout)
        })
        .await?;
        Ok(Lookup::served(answer))
    }

    /// What this client's key is entitled to, and how much of it has been used.
    ///
    /// Named for what it answers rather than `me`, which sits one letter from
    /// [`Client::my_ip`] and means something quite different: one is which
    /// address you are calling FROM, the other is what the key you are calling
    /// WITH may spend.
    ///
    /// Unlike a lookup there is no useful unauthenticated answer, so a client
    /// built without an API key gets an unauthorized error rather than a
    /// partial one.
    ///
    /// Usage counts against the ALLOWANCE WINDOW - on a paid plan the
    /// anniversary of the subscription, not the calendar month and not the
    /// billing period, and on the free plan the UTC day - and it is the same
    /// number a lookup is gated on. It can lag by a few seconds, because
    /// requests are counted in memory and flushed in aggregate.
    ///
    /// Deliberately NOT cached: the whole point is what has been spent, and a
    /// cached answer is a wrong one within seconds of the next request.
    pub async fn my_entitlement(&self) -> Result<Entitlement, Error> {
        self.my_entitlement_with(LookupOptions::new()).await
    }

    /// [`Client::my_entitlement`], with this call's own retry budget and timeout.
    pub async fn my_entitlement_with(&self, opts: LookupOptions) -> Result<Entitlement, Error> {
        let timeout = self.call_timeout(opts.timeout)?;
        with_retry(opts.retries.unwrap_or(self.0.retries), || {
            self.0.transport.get_json("/api/v1/entitlement", &[], timeout)
        })
        .await
    }

    /// Looks many addresses up in as few requests as possible.
    ///
    /// Bogons are answered locally and cached answers are reused, and an address
    /// with a request already in flight, a single lookup's or another batch's,
    /// awaits that request; everything else goes to `POST /batch` in chunks of up
    /// to 1000 addresses, with at most `concurrency` chunks in flight. The answers are keyed by address
    /// rather than positional, so duplicates in the input collapse to a single
    /// entry and the caller never has to line two lists up. Keys are in the
    /// order the addresses were first seen. An address that fails carries its
    /// error as its value, so one bad entry cannot lose the rest of the answers:
    /// the API reports a per-entry failure with the status the single lookup
    /// would have answered, and a chunk that fails as a whole marks every
    /// address in it. `POST /batch` needs a paid plan: without a key every
    /// address in a request of two or more carries an unauthorized error, and
    /// a free-plan key's request of two or more a bad request (HTTP 402). A
    /// request of one address is answered as its lookup would be.
    pub async fn lookup_batch<I, S>(
        &self,
        ips: I,
        opts: BatchOptions,
    ) -> IndexMap<String, Result<Lookup, Error>>
    where
        I: IntoIterator<Item = S>,
        S: AsRef<str>,
    {
        // An IPv4-mapped address is looked up as the IPv4 address it carries,
        // once, and its answer keyed as the caller passed it.
        let asked = dedupe(ips);
        let wire: Vec<String> = asked.iter().map(|ip| unmapped(ip).into_owned()).collect();
        let unique = dedupe(&wire);
        let retries = opts.retries.unwrap_or(self.0.retries);
        let concurrency = opts.concurrency.unwrap_or(self.0.concurrency);
        let refused = match self.call_timeout(opts.timeout) {
            Err(err) => Some(err.message()),
            Ok(_) if concurrency == 0 => Some("concurrency must be at least 1".to_owned()),
            Ok(_) => None,
        };
        if let Some(message) = refused {
            return asked.into_iter().map(|ip| (ip, Err(Error::Config(message.clone())))).collect();
        }
        let timeout = opts.timeout.unwrap_or(self.0.timeout);

        let mut answers: HashMap<String, Result<Lookup, Error>> =
            HashMap::with_capacity(unique.len());
        let mut pending: Vec<String> = Vec::new();
        for ip in &unique {
            if is_bogon(ip) {
                answers.insert(ip.clone(), Ok(bogon_lookup(ip)));
                continue;
            }
            if let Some(cache) = &self.0.cache {
                if let Some(hit) = cache.get(ip).await {
                    answers.insert(ip.clone(), Ok(hit));
                    continue;
                }
            }
            pending.push(ip.clone());
        }

        // Each address with a request in flight awaits it, and the rest are
        // boarded before any chunk is built, so a lookup arriving meanwhile
        // awaits this batch's answer in turn. A request that landed since the
        // cache was read above cached its answer first, so a led address is
        // looked up there once more before it is sent.
        let (mut pilot, joined) = match &self.0.cache {
            Some(_) => self.0.flights.board(pending.iter().map(String::as_str)),
            None => self.0.flights.board([]),
        };
        let mut send: Vec<String> = Vec::with_capacity(pending.len());
        for ip in pending {
            if joined.iter().any(|(joined_ip, _)| *joined_ip == ip) {
                continue;
            }
            if let Some(cache) = self.0.cache.as_ref().filter(|_| pilot.leads(&ip)) {
                if let Some(hit) = cache.get(&ip).await {
                    let hit = Ok(hit);
                    pilot.land(&ip, &hit);
                    answers.insert(ip, hit);
                    continue;
                }
            }
            send.push(ip);
        }

        // buffer_unordered completes out of order, so each chunk's answers are
        // gathered as they land and the map is assembled in input order at the
        // end, which is what keeps it insertion-ordered whatever order the
        // network answers in.
        let chunks: Vec<Vec<String>> = send.chunks(BATCH_MAX).map(<[String]>::to_vec).collect();
        {
            let mut stream = futures_util::stream::iter(chunks)
                .map(|chunk| async move { self.lookup_chunk(chunk, retries, timeout).await })
                .buffer_unordered(concurrency);
            while let Some(chunk_answers) = stream.next().await {
                for (ip, answer) in chunk_answers {
                    pilot.land(&ip, &answer);
                    answers.insert(ip, answer);
                }
            }
        }
        drop(pilot);
        for (ip, flight) in joined {
            let answer = match flight.await {
                Ok(landed) => restate(&landed),
                // Its leader was dropped before the answer landed, so this one
                // goes alone, sharing whatever is in flight by then.
                Err(_) => {
                    let opts = LookupOptions { retries: Some(retries), timeout: Some(timeout) };
                    self.lookup_with(&ip, opts).await
                }
            };
            answers.insert(ip, answer);
        }

        // Two spellings of one address share its answer: restated for all but
        // the last, which takes it.
        let mut uses: HashMap<&str, usize> = HashMap::with_capacity(wire.len());
        for ip in &wire {
            *uses.entry(ip.as_str()).or_default() += 1;
        }
        asked
            .into_iter()
            .zip(&wire)
            .map(|(ip, wire)| {
                let left = uses.get_mut(wire.as_str()).expect("every address is counted");
                *left -= 1;
                let answer = if *left == 0 {
                    answers.remove(wire).expect("every address is answered exactly once")
                } else {
                    restate(answers.get(wire).expect("every address is answered"))
                };
                (ip, answer)
            })
            .collect()
    }

    /// One `POST /batch`, mapped back onto the addresses it was asked about. A
    /// chunk-level failure - the call refused, the transport failing, the
    /// retries exhausted - becomes every address's error, exactly as it would
    /// have been had each been looked up alone.
    async fn lookup_chunk(
        &self,
        chunk: Vec<String>,
        retries: u32,
        timeout: Duration,
    ) -> Vec<(String, Result<Lookup, Error>)> {
        let request =
            BatchLookupRequest { ips: Some(chunk.clone()), ..BatchLookupRequest::default() };
        let answered: Result<BatchAnswer, Error> =
            with_retry(retries, || self.0.transport.post_json("/batch", &request, timeout)).await;
        let mut body = match answered {
            Ok(body) => body,
            Err(err) => return chunk.into_iter().map(|ip| (ip, Err(err.restated()))).collect(),
        };
        let mut out = Vec::with_capacity(chunk.len());
        for ip in chunk {
            let answer = if let Some(served) = body.results.remove(&ip) {
                match serde_json::from_value::<LookupResponse>(served) {
                    Ok(served) => {
                        let lookup = Lookup::served(served);
                        if let Some(cache) = &self.0.cache {
                            cache.insert(ip.clone(), lookup.clone()).await;
                        }
                        Ok(lookup)
                    }
                    Err(err) => Err(unreadable_entry(&ip, &err)),
                }
            } else if let Some(failed) = body.errors.remove(&ip) {
                match serde_json::from_value::<BatchLookupError>(failed) {
                    Ok(failed) => Err(Error::from_entry(
                        u16::try_from(failed.status).unwrap_or(500),
                        &failed.error,
                    )),
                    Err(err) => Err(unreadable_entry(&ip, &err)),
                }
            } else {
                Err(Error::Api {
                    kind: ErrorKind::ServerError,
                    message: format!("the batch answer did not include {ip}"),
                    status: 200,
                    retry_after: None,
                })
            };
            out.push((ip, answer));
        }
        out
    }

    /// What every database says about one AS.
    ///
    /// Sent as given and never cached: the cache is keyed by address, and an AS
    /// answer has none. Nor is it batched, so many AS numbers are many calls.
    pub async fn lookup_asn(&self, asn: u32) -> Result<AsnLookupResponse, Error> {
        self.lookup_asn_with(asn, LookupOptions::new()).await
    }

    /// [`Client::lookup_asn`], with this call's own retry budget and timeout.
    pub async fn lookup_asn_with(
        &self,
        asn: u32,
        opts: LookupOptions,
    ) -> Result<AsnLookupResponse, Error> {
        let timeout = self.call_timeout(opts.timeout)?;
        let path = format!("/asn/{asn}");
        with_retry(opts.retries.unwrap_or(self.0.retries), || {
            self.0.transport.get_json(&path, &[], timeout)
        })
        .await
    }

    /// What every database says about one domain.
    ///
    /// Sent as given, escaped into the path: the API reads it lowercase and in
    /// punycode, and refuses what it cannot read as a bad request. Never cached,
    /// and not batched, as [`Client::lookup_asn`] is not.
    pub async fn lookup_domain(&self, domain: &str) -> Result<DomainLookupResponse, Error> {
        self.lookup_domain_with(domain, LookupOptions::new()).await
    }

    /// [`Client::lookup_domain`], with this call's own retry budget and timeout.
    pub async fn lookup_domain_with(
        &self,
        domain: &str,
        opts: LookupOptions,
    ) -> Result<DomainLookupResponse, Error> {
        let timeout = self.call_timeout(opts.timeout)?;
        let path = format!("/domain/{}", encode_path_segment(domain));
        with_retry(opts.retries.unwrap_or(self.0.retries), || {
            self.0.transport.get_json(&path, &[], timeout)
        })
        .await
    }

    /// Whether an address is answered locally rather than served. Exposed here
    /// so the check is reachable from the client you already hold; the free
    /// [`crate::is_bogon`] is the same function.
    pub fn is_bogon(&self, ip: &str) -> bool {
        is_bogon(ip)
    }

    /// The database catalog and its downloads.
    ///
    /// They hang off here rather than off the client itself, which is where the
    /// sibling VPNDetection crate keeps the same calls, so one program holding
    /// both spells the two the same way.
    pub fn database(&self) -> DatabaseApi<'_> {
        DatabaseApi::new(self)
    }

    /// Signing a person in with OAuth: the device flow, so a program on their
    /// own machine can be handed one of their API keys, or the authorization
    /// code flow, for an app that can take a browser redirect. These requests
    /// never carry this client's API key, so a client built without one works,
    /// and they go to the apex, which [`OauthApi`] says how it is found.
    pub fn oauth(&self) -> OauthApi<'_> {
        OauthApi::new(self)
    }

    pub(crate) fn transport(&self) -> &Transport {
        &self.0.transport
    }

    pub(crate) fn retries(&self) -> u32 {
        self.0.retries
    }

    pub(crate) fn timeout(&self) -> Duration {
        self.0.timeout
    }

    /// One call's timeout: its own, else the client's. Zero is refused here, before
    /// a bogon or a cache hit could answer without a request to fail, since no
    /// attempt can meet it: accepted, it failed every OAuth call as a network
    /// error, retried after ~750 ms of backoff where the call retries, and the
    /// poll only after its first wait (2.2.1, measured 2026-09-26). `build`
    /// refuses the client's own zero. `Duration::MAX` needs no refusal, since
    /// tokio clamps a deadline past its reach rather than failing.
    pub(crate) fn call_timeout(&self, per_call: Option<Duration>) -> Result<Duration, Error> {
        match per_call {
            Some(timeout) if timeout.is_zero() => {
                Err(Error::Config("timeout must be positive".to_owned()))
            }
            Some(timeout) => Ok(timeout),
            None => Ok(self.0.timeout),
        }
    }
}

/// Builds a [`Client`]. With nothing set it queries production with no API key,
/// which a lookup answers as Unlimited and every database published today
/// answers `401`.
#[derive(Debug, Default)]
pub struct ClientBuilder {
    api_key: Option<String>,
    base_url: Option<String>,
    cache_capacity: Option<u64>,
    cache_ttl: Option<Duration>,
    cache_off: bool,
    concurrency: Option<usize>,
    retries: Option<u32>,
    timeout: Option<Duration>,
    http_client: Option<reqwest::Client>,
}

impl ClientBuilder {
    pub fn new() -> Self {
        Self::default()
    }

    /// Authenticates as the key's organization. Which fields a lookup answers
    /// with, and how many requests are allowed, follow the key's plan; which
    /// databases you can see and download follow its licenses, and those calls
    /// need the key to carry the `db.download` scope. Keys are default-deny, so
    /// an existing key does not gain database access until that scope is added.
    ///
    /// Optional. Leave it unset, or pass an empty or blank string, and no
    /// `Authorization` header is sent - which is what an unset `${{ secrets.X }}`
    /// interpolates to, and a better answer than `Bearer ` with nothing behind
    /// it. Whitespace around a key, such as the newline a key read from a file
    /// ends in, is not part of it; a key still holding a control character is
    /// refused by [`ClientBuilder::build`].
    pub fn api_key(mut self, key: impl Into<String>) -> Self {
        self.api_key = Some(key.into());
        self
    }

    /// Points the client at a different deployment of the API. The OAuth
    /// requests go to its apex, as [`OauthApi`] says.
    pub fn base_url(mut self, url: impl Into<String>) -> Self {
        self.base_url = Some(url.into());
        self
    }

    /// Sizes the per-client answer cache. Defaults are 10000 addresses and a one
    /// hour TTL.
    pub fn cache(mut self, capacity: u64, ttl: Duration) -> Self {
        self.cache_capacity = Some(capacity);
        self.cache_ttl = Some(ttl);
        self.cache_off = false;
        self
    }

    /// Turns caching off, so every lookup of a non-bogon address is served.
    pub fn no_cache(mut self) -> Self {
        self.cache_off = true;
        self
    }

    /// How many requests a batch keeps in flight. Default 8.
    pub fn concurrency(mut self, n: usize) -> Self {
        self.concurrency = Some(n);
        self
    }

    /// How many further attempts a transient failure gets. Default 2.
    pub fn retries(mut self, n: u32) -> Self {
        self.retries = Some(n);
        self
    }

    /// How long one attempt at an API request may take, from connecting to the
    /// last byte of the answer. Default 30 seconds.
    ///
    /// Per ATTEMPT, so a call that is retried can take longer in total. A
    /// database transfer is exempt: a download runs for as long as the file
    /// takes, and only a connection that stops moving fails it. A request that
    /// runs out of time is an [`Error::Network`], which is retryable.
    pub fn timeout(mut self, timeout: Duration) -> Self {
        self.timeout = Some(timeout);
        self
    }

    /// The HTTP client to send with, for a custom transport or proxy.
    ///
    /// **Build it with [`reqwest::redirect::Policy::none`].** reqwest follows
    /// redirects by default and its policy is a client-level setting with no
    /// per-request override, so a following client would chase the download
    /// endpoint's 302 into object storage instead of handing back the link.
    /// [`DatabaseApi::download_url`] refuses rather than downloading, but only after
    /// the request has been spent.
    ///
    /// **And do not put a total [`reqwest::ClientBuilder::timeout`] on it.**
    /// API requests carry [`ClientBuilder::timeout`] whichever client sends
    /// them, but a database transfer carries none, so a total timeout here caps
    /// how large a database this client can fetch: at 30 seconds a 5 GiB
    /// transfer cannot finish however healthy the connection is. The default
    /// client sets a connect timeout and a read (inactivity) timeout instead,
    /// which fail a stalled transfer without failing a slow one.
    pub fn http_client(mut self, client: reqwest::Client) -> Self {
        self.http_client = Some(client);
        self
    }

    pub fn build(self) -> Result<Client, Error> {
        let base_url = self.base_url.unwrap_or_else(|| DEFAULT_BASE_URL.to_owned());
        let parsed = reqwest::Url::parse(&base_url)
            .map_err(|e| Error::Config(format!("base url {base_url:?}: {e}")))?;
        if !parsed.has_host() {
            return Err(Error::Config(format!("base url {base_url:?} needs a scheme and a host")));
        }
        let concurrency = self.concurrency.unwrap_or(DEFAULT_CONCURRENCY);
        if concurrency == 0 {
            return Err(Error::Config("concurrency must be at least 1".to_owned()));
        }
        let capacity = self.cache_capacity.unwrap_or(DEFAULT_CACHE_CAPACITY);
        let ttl = self.cache_ttl.unwrap_or(DEFAULT_CACHE_TTL);
        if capacity == 0 {
            return Err(Error::Config("cache capacity must be at least 1".to_owned()));
        }
        if ttl.is_zero() {
            return Err(Error::Config("cache ttl must be positive".to_owned()));
        }
        let timeout = self.timeout.unwrap_or(DEFAULT_TIMEOUT);
        if timeout.is_zero() {
            return Err(Error::Config("timeout must be positive".to_owned()));
        }

        let api_key = self.api_key.map(|key| key.trim().to_owned()).filter(|key| !key.is_empty());
        // Refused here rather than at the first request, where reqwest failed
        // every call as a retried network error with nothing sent. The message
        // names the key's fault and never the key.
        if api_key.as_deref().is_some_and(|key| key.chars().any(char::is_control)) {
            return Err(Error::Config("the API key holds a control character".to_owned()));
        }

        let http = match self.http_client {
            Some(client) => client,
            None => reqwest::Client::builder()
                .connect_timeout(DEFAULT_CONNECT_TIMEOUT)
                .read_timeout(DEFAULT_READ_TIMEOUT)
                .user_agent(concat!("internetdata-rust/", env!("CARGO_PKG_VERSION")))
                // The download endpoint answers 302 to object storage and the
                // database behind it reaches gigabytes, so the link is the
                // answer and following it is never what a caller wants.
                .redirect(reqwest::redirect::Policy::none())
                .build()?,
        };

        let base_url = base_url.trim_end_matches('/').to_owned();
        let oauth_base_url = authorization_server(&base_url);
        Ok(Client(Arc::new(Inner {
            transport: Transport::new(http, base_url, oauth_base_url, api_key),
            cache: (!self.cache_off)
                .then(|| Cache::builder().max_capacity(capacity).time_to_live(ttl).build()),
            flights: Flights::default(),
            concurrency,
            retries: self.retries.unwrap_or(DEFAULT_RETRIES),
            timeout,
        })))
    }
}

/// A batch answer whose entries are read one at a time, so an entry this
/// version cannot read fails only its own address. Both maps must be objects,
/// or the chunk is an answer the call cannot read and is retried whole.
#[derive(Deserialize)]
struct BatchAnswer {
    results: HashMap<String, serde_json::Value>,
    errors: HashMap<String, serde_json::Value>,
}

/// An entry of a readable batch answer that is no answer for its address: the
/// server error a 2xx the call cannot read is, carrying 200 as an address the
/// answer left out does.
fn unreadable_entry(ip: &str, err: &serde_json::Error) -> Error {
    Error::Api {
        kind: ErrorKind::ServerError,
        message: format!("could not decode the batch answer for {ip}: {err}"),
        status: 200,
        retry_after: None,
    }
}

/// One call's overrides for [`Client::lookup_with`], [`Client::lookup_asn_with`],
/// [`Client::lookup_domain_with`], [`Client::my_ip_with`] and
/// [`Client::my_entitlement_with`].
#[derive(Debug, Clone, Default)]
pub struct LookupOptions {
    retries: Option<u32>,
    timeout: Option<Duration>,
}

impl LookupOptions {
    pub fn new() -> Self {
        Self::default()
    }

    /// Overrides the client's retry count for this call.
    pub fn retries(mut self, n: u32) -> Self {
        self.retries = Some(n);
        self
    }

    /// Overrides [`ClientBuilder::timeout`] for this call, still per attempt.
    pub fn timeout(mut self, timeout: Duration) -> Self {
        self.timeout = Some(timeout);
        self
    }
}

/// One batch's overrides for [`Client::lookup_batch`].
///
/// `concurrency` lives here and not on [`LookupOptions`], so passing it to a
/// single lookup does not compile rather than being accepted and ignored.
#[derive(Debug, Clone, Default)]
pub struct BatchOptions {
    retries: Option<u32>,
    concurrency: Option<usize>,
    timeout: Option<Duration>,
}

impl BatchOptions {
    pub fn new() -> Self {
        Self::default()
    }

    /// Overrides the client's retry count for every address in this batch.
    pub fn retries(mut self, n: u32) -> Self {
        self.retries = Some(n);
        self
    }

    /// Overrides the client's in-flight request limit for this batch, so one
    /// large batch does not need a second client to widen it. Zero refuses the
    /// whole batch as a bad request before any request is sent.
    pub fn concurrency(mut self, n: usize) -> Self {
        self.concurrency = Some(n);
        self
    }

    /// Overrides [`ClientBuilder::timeout`] for each attempt at each chunk of
    /// this batch.
    pub fn timeout(mut self, timeout: Duration) -> Self {
        self.timeout = Some(timeout);
        self
    }
}

/// Backs off exponentially, except that a server-supplied `Retry-After` wins
/// over the schedule, up to [`MAX_RETRY_AFTER`]. A 429 WITHOUT that header is a
/// spent allowance rather than a throttle and is not retried at all, which
/// [`Error::retryable`] decides.
pub(crate) async fn with_retry<T, E, F, Fut>(retries: u32, mut attempt: F) -> Result<T, E>
where
    E: Retry,
    F: FnMut() -> Fut,
    Fut: Future<Output = Result<T, E>>,
{
    let mut delay = RETRY_BASE_DELAY;
    let mut remaining = retries;
    loop {
        match attempt().await {
            Ok(value) => return Ok(value),
            Err(err) if remaining == 0 || !err.retryable() => return Err(err),
            Err(err) => {
                let wait = err.retry_after().filter(|wait| *wait <= MAX_RETRY_AFTER);
                tokio::time::sleep(wait.unwrap_or(delay)).await;
                delay = delay.saturating_mul(2);
                remaining -= 1;
            }
        }
    }
}

/// What [`with_retry`] asks of a failure, so the OAuth calls retry by the same
/// rules without folding their refusals into [`Error`].
pub(crate) trait Retry {
    fn retryable(&self) -> bool;
    fn retry_after(&self) -> Option<Duration>;
}

impl Retry for Error {
    fn retryable(&self) -> bool {
        Error::retryable(self)
    }

    fn retry_after(&self) -> Option<Duration> {
        Error::retry_after(self)
    }
}

impl Retry for OauthError {
    fn retryable(&self) -> bool {
        OauthError::retryable(self)
    }

    fn retry_after(&self) -> Option<Duration> {
        OauthError::retry_after(self)
    }
}

fn dedupe<I, S>(ips: I) -> Vec<String>
where
    I: IntoIterator<Item = S>,
    S: AsRef<str>,
{
    let mut seen = std::collections::HashSet::new();
    ips.into_iter().map(|ip| ip.as_ref().to_owned()).filter(|ip| seen.insert(ip.clone())).collect()
}