Skip to main content

ipscanner/
client.rs

1use std::sync::Arc;
2use std::time::Duration;
3
4use reqwest::header::{HeaderValue, ACCEPT, AUTHORIZATION, CONTENT_TYPE, USER_AGENT};
5use reqwest::{Method, Response};
6use serde::de::DeserializeOwned;
7use serde::Serialize;
8
9use crate::error::{self, Error};
10use crate::resources::{Account, Agentscan, AsnDirectory, Bulk, Crawlers, Ip, Provenance};
11
12/// The default API base URL.
13pub const DEFAULT_BASE_URL: &str = "https://ipscanner.io";
14
15const DEFAULT_TIMEOUT: Duration = Duration::from_secs(30);
16const DEFAULT_MAX_RETRIES: u32 = 2;
17const USER_AGENT_VALUE: &str = concat!("ipscanner-rust/", env!("CARGO_PKG_VERSION"));
18
19/// An IPScanner API client. Cheap to clone; clones share one connection pool.
20#[derive(Clone)]
21pub struct Client {
22    inner: Arc<Inner>,
23}
24
25struct Inner {
26    http: reqwest::Client,
27    base_url: String,
28    api_key: Option<String>,
29    timeout: Duration,
30    max_retries: u32,
31}
32
33impl std::fmt::Debug for Client {
34    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
35        f.debug_struct("Client")
36            .field("base_url", &self.inner.base_url)
37            .field(
38                "api_key",
39                &self.inner.api_key.as_ref().map(|_| "[redacted]"),
40            )
41            .field("timeout", &self.inner.timeout)
42            .field("max_retries", &self.inner.max_retries)
43            .finish()
44    }
45}
46
47impl Client {
48    /// Creates a client with the given API key. Panics if the TLS backend fails, like `reqwest::Client::new`.
49    pub fn new(api_key: impl Into<String>) -> Self {
50        Self::builder()
51            .api_key(api_key)
52            .build()
53            .expect("failed to build HTTP client")
54    }
55
56    /// Creates a client from `IPSCANNER_API_KEY` and `IPSCANNER_API_URL`; without a key only keyless routes work.
57    pub fn from_env() -> Self {
58        let mut b = Self::builder();
59        if let Ok(key) = std::env::var("IPSCANNER_API_KEY") {
60            b = b.api_key(key);
61        }
62        if let Ok(url) = std::env::var("IPSCANNER_API_URL") {
63            if !url.trim().is_empty() {
64                b = b.base_url(url);
65            }
66        }
67        b.build().expect("failed to build HTTP client")
68    }
69
70    /// Returns a builder for a client with custom settings.
71    pub fn builder() -> ClientBuilder {
72        ClientBuilder::default()
73    }
74
75    /// IP lookups, single-signal checks and lookup history.
76    pub fn ip(&self) -> Ip<'_> {
77        Ip::new(self)
78    }
79
80    /// Bulk checks, as one JSON response or as an NDJSON stream.
81    pub fn bulk(&self) -> Bulk<'_> {
82        Bulk::new(self)
83    }
84
85    /// Agentscan: classify requests as human, bot, AI agent or automation.
86    pub fn agentscan(&self) -> Agentscan<'_> {
87        Agentscan::new(self)
88    }
89
90    /// Provenance attestations and the evidence chain.
91    pub fn provenance(&self) -> Provenance<'_> {
92        Provenance::new(self)
93    }
94
95    /// Plan limits and usage.
96    pub fn account(&self) -> Account<'_> {
97        Account::new(self)
98    }
99
100    /// The public ASN directory.
101    pub fn asn_directory(&self) -> AsnDirectory<'_> {
102        AsnDirectory::new(self)
103    }
104
105    /// The catalogue of verifiable crawlers.
106    pub fn crawlers(&self) -> Crawlers<'_> {
107        Crawlers::new(self)
108    }
109
110    pub(crate) async fn get<T: DeserializeOwned>(
111        &self,
112        path: &str,
113        query: &[(&str, String)],
114    ) -> Result<T, Error> {
115        let res = self
116            .send(Method::GET, path, query, None, None, "application/json")
117            .await?;
118        decode(res).await
119    }
120
121    pub(crate) async fn post<T: DeserializeOwned, B: Serialize + ?Sized>(
122        &self,
123        path: &str,
124        body: &B,
125    ) -> Result<T, Error> {
126        let res = self.post_raw(path, body, None).await?;
127        decode(res).await
128    }
129
130    pub(crate) async fn post_raw<B: Serialize + ?Sized>(
131        &self,
132        path: &str,
133        body: &B,
134        timeout: Option<Duration>,
135    ) -> Result<Response, Error> {
136        let body = serde_json::to_vec(body)?;
137        self.send(
138            Method::POST,
139            path,
140            &[],
141            Some(body),
142            timeout,
143            "application/json",
144        )
145        .await
146    }
147
148    pub(crate) async fn get_text(
149        &self,
150        path: &str,
151        query: &[(&str, String)],
152        accept: &str,
153    ) -> Result<String, Error> {
154        let res = self
155            .send(Method::GET, path, query, None, None, accept)
156            .await?;
157        Ok(res.text().await?)
158    }
159
160    async fn send(
161        &self,
162        method: Method,
163        path: &str,
164        query: &[(&str, String)],
165        body: Option<Vec<u8>>,
166        timeout: Option<Duration>,
167        accept: &str,
168    ) -> Result<Response, Error> {
169        let inner = &self.inner;
170        let url = format!("{}/v1{}", inner.base_url, path);
171        let retries = if method == Method::GET {
172            inner.max_retries
173        } else {
174            0
175        };
176        let mut attempt = 0;
177        loop {
178            let mut req = inner
179                .http
180                .request(method.clone(), &url)
181                .timeout(timeout.unwrap_or(inner.timeout))
182                .header(USER_AGENT, USER_AGENT_VALUE)
183                .header(ACCEPT, accept);
184            if !query.is_empty() {
185                req = req.query(query);
186            }
187            if let Some(key) = &inner.api_key {
188                req = req.header(AUTHORIZATION, format!("Bearer {key}"));
189            }
190            if let Some(b) = &body {
191                req = req
192                    .header(CONTENT_TYPE, HeaderValue::from_static("application/json"))
193                    .body(b.clone());
194            }
195
196            match req.send().await {
197                Ok(res) => {
198                    let status = res.status();
199                    if status.is_success() {
200                        return Ok(res);
201                    }
202                    if attempt < retries && matches!(status.as_u16(), 502..=504) {
203                        backoff(attempt).await;
204                        attempt += 1;
205                        continue;
206                    }
207                    let headers = res.headers().clone();
208                    let text = res.text().await.unwrap_or_default();
209                    return Err(error::from_response(status, &headers, text));
210                }
211                Err(e) => {
212                    if attempt < retries && !e.is_builder() {
213                        backoff(attempt).await;
214                        attempt += 1;
215                        continue;
216                    }
217                    return Err(e.into());
218                }
219            }
220        }
221    }
222}
223
224async fn backoff(attempt: u32) {
225    tokio::time::sleep(Duration::from_millis(500 << attempt)).await;
226}
227
228async fn decode<T: DeserializeOwned>(res: Response) -> Result<T, Error> {
229    let bytes = res.bytes().await?;
230    Ok(serde_json::from_slice(&bytes)?)
231}
232
233/// Percent-encodes a single path segment.
234pub(crate) fn segment(s: &str) -> String {
235    let mut out = String::with_capacity(s.len());
236    for b in s.bytes() {
237        if b.is_ascii_alphanumeric() || matches!(b, b'-' | b'.' | b'_' | b'~') {
238            out.push(b as char);
239        } else {
240            out.push_str(&format!("%{b:02X}"));
241        }
242    }
243    out
244}
245
246/// Builds a [`Client`] with custom settings.
247#[derive(Default)]
248pub struct ClientBuilder {
249    api_key: Option<String>,
250    base_url: Option<String>,
251    timeout: Option<Duration>,
252    max_retries: Option<u32>,
253    http_client: Option<reqwest::Client>,
254}
255
256impl ClientBuilder {
257    /// Sets the API key sent as a bearer token.
258    pub fn api_key(mut self, key: impl Into<String>) -> Self {
259        self.api_key = Some(key.into());
260        self
261    }
262
263    /// Overrides the base URL. Defaults to `https://ipscanner.io`.
264    pub fn base_url(mut self, url: impl Into<String>) -> Self {
265        self.base_url = Some(url.into());
266        self
267    }
268
269    /// Sets the per-request timeout. Defaults to 30 seconds. Bulk streams use 5 minutes.
270    pub fn timeout(mut self, timeout: Duration) -> Self {
271        self.timeout = Some(timeout);
272        self
273    }
274
275    /// Sets how many times a failed GET is retried. Defaults to 2.
276    pub fn max_retries(mut self, n: u32) -> Self {
277        self.max_retries = Some(n);
278        self
279    }
280
281    /// Uses an existing `reqwest::Client`.
282    pub fn http_client(mut self, client: reqwest::Client) -> Self {
283        self.http_client = Some(client);
284        self
285    }
286
287    /// Builds the client.
288    pub fn build(self) -> Result<Client, Error> {
289        let http = match self.http_client {
290            Some(c) => c,
291            None => reqwest::Client::builder().build()?,
292        };
293        let base_url = self
294            .base_url
295            .unwrap_or_else(|| DEFAULT_BASE_URL.to_string())
296            .trim_end_matches('/')
297            .to_string();
298        let api_key = self
299            .api_key
300            .map(|k| k.trim().to_string())
301            .filter(|k| !k.is_empty());
302        Ok(Client {
303            inner: Arc::new(Inner {
304                http,
305                base_url,
306                api_key,
307                timeout: self.timeout.unwrap_or(DEFAULT_TIMEOUT),
308                max_retries: self.max_retries.unwrap_or(DEFAULT_MAX_RETRIES),
309            }),
310        })
311    }
312}
313
314#[cfg(test)]
315mod tests {
316    use super::segment;
317
318    #[test]
319    fn escapes_ipv6() {
320        assert_eq!(segment("2001:db8::1"), "2001%3Adb8%3A%3A1");
321        assert_eq!(segment("1.1.1.1"), "1.1.1.1");
322        assert_eq!(segment("a/b"), "a%2Fb");
323    }
324}