internetdata 2.5.0

The official Rust client library for the InternetData API: download and verify the published IP intelligence databases.
Documentation
use std::time::Duration;

use chrono::TimeZone;
use reqwest::header::{AUTHORIZATION, HeaderMap, RETRY_AFTER};
use serde::de::DeserializeOwned;

use crate::error::{Error, ErrorKind, kind_for_status};

/// Every request the crate makes: five database GETs with no request bodies,
/// and the OAuth requests, which never carry the key.
///
/// The generated client is not used for this: its `ResponseContent` carries no
/// headers, so a 429's `Retry-After` is unreachable, and its
/// `download_database_v2` is typed `Result<(), _>`, discarding the 302 whose
/// `Location` is that endpoint's entire answer.
#[derive(Debug, Clone)]
pub(crate) struct Transport {
    http: reqwest::Client,
    base_url: String,
    api_key: Option<String>,
}

impl Transport {
    pub(crate) fn new(http: reqwest::Client, base_url: String, api_key: Option<String>) -> Self {
        Self { http, base_url, api_key }
    }

    /// What every path is appended to, with no trailing `/`.
    pub(crate) fn base_url(&self) -> &str {
        &self.base_url
    }

    /// A JSON GET, decoded into `T`.
    ///
    /// `timeout` runs from connecting to the last byte of the body, which is
    /// what reqwest's per-request timeout covers. It also takes precedence over
    /// a total timeout on a caller-supplied client, so the bound is the SDK's
    /// whichever client sends.
    pub(crate) async fn get_json<T: DeserializeOwned>(
        &self,
        path: &str,
        query: &[(&str, &str)],
        timeout: Duration,
    ) -> Result<T, Error> {
        let response = self.send(path, query, timeout).await?;
        let status = response.status().as_u16();
        let retry_after = parse_retry_after(response.headers());
        let body = response.text().await?;
        if !(200..300).contains(&status) {
            return Err(Error::from_response(status, retry_after, &body));
        }
        // A body that will not decode is a transport-level failure rather than
        // the API saying no, so it is retryable like any other malformed read.
        serde_json::from_str(&body).map_err(|e| Error::Api {
            kind: ErrorKind::ServerError,
            message: format!("could not decode the response: {e}"),
            status,
            retry_after: None,
        })
    }

    /// The `Location` of a redirect the client must NOT follow.
    ///
    /// The download endpoint answers 302 to object storage, and the database
    /// behind it reaches gigabytes, so following it would transfer the whole
    /// file to hand back a link. [`crate::ClientBuilder`] builds its client with
    /// `redirect::Policy::none()` for exactly this; a caller-supplied client
    /// that follows redirects is caught here rather than silently downloading.
    ///
    /// Any other 2xx is an answer this call cannot read, such as a proxy's page
    /// served as a 200, and is the retried server error every other call's is.
    /// Read as a followed redirect, it was a `bad_request` sent once that told
    /// the caller to fix a client they never passed (2.4.2, measured 2026-10-08).
    pub(crate) async fn get_redirect(
        &self,
        path: &str,
        query: &[(&str, &str)],
        timeout: Duration,
    ) -> Result<String, Error> {
        let response = self.send(path, query, timeout).await?;
        let status = response.status().as_u16();
        let retry_after = parse_retry_after(response.headers());
        let location = response
            .headers()
            .get(reqwest::header::LOCATION)
            .and_then(|v| v.to_str().ok())
            .map(str::to_owned);

        match (status, location) {
            (300..400, Some(location)) => Ok(location),
            (300..400, None) => Err(Error::Api {
                kind: ErrorKind::ServerError,
                message: "the redirect carried no Location header".to_owned(),
                status,
                retry_after: None,
            }),
            (200..300, _) if !self.answered_from(path, &response) => Err(Error::Config(
                "the download redirect was followed, so its Location is gone: build the \
                 reqwest::Client you passed to ClientBuilder::http_client with \
                 reqwest::redirect::Policy::none()"
                    .to_owned(),
            )),
            (200..300, _) => Err(Error::Api {
                kind: ErrorKind::ServerError,
                message: "expected a redirect to object storage".to_owned(),
                status,
                retry_after: None,
            }),
            _ => {
                let body = response.text().await?;
                Err(Error::from_response(status, retry_after, &body))
            }
        }
    }

    /// Whether `response` came from the URL sent for `path` rather than from
    /// wherever a redirect led, which only a client that follows them reaches.
    fn answered_from(&self, path: &str, response: &reqwest::Response) -> bool {
        let mut url = response.url().clone();
        url.set_query(None);
        reqwest::Url::parse(&format!("{}{}", self.base_url, path)).is_ok_and(|sent| sent == url)
    }

    /// A GET to an absolute URL carrying NO credential, for a presigned link
    /// that authorizes itself.
    ///
    /// The body is handed back unread, so a database of any size is streamed by
    /// the caller rather than buffered here. The API key is not merely omitted
    /// from this request, the redirect is not followed at all: reqwest's
    /// redirect policy is a CLIENT-level setting and some versions carry
    /// request headers across a redirect, so issuing the second request by hand
    /// is the only way the key provably does not travel to object storage.
    ///
    /// No timeout is set: a deadline over the body would cap the size of a
    /// database, so only the client's connect and read timeouts apply.
    pub(crate) async fn get_file(&self, url: &str) -> Result<reqwest::Response, Error> {
        let response = self.http.get(url).send().await?;
        let status = response.status().as_u16();
        if (200..300).contains(&status) {
            return Ok(response);
        }
        // The body is left unread: the status is what separates a lapsed link
        // from a refused one, and nothing bounds the size of an error body.
        let retry_after = parse_retry_after(response.headers());
        Err(Error::Api {
            kind: kind_for_status(status, retry_after),
            message: format!("object storage refused the download link with status {status}"),
            status,
            retry_after,
        })
    }

    /// An OAuth GET. It never carries the API key: those endpoints have no use
    /// for it, and handing a credential to a request that does not need one
    /// only widens where it can leak.
    pub(crate) async fn get_keyless(&self, path: &str, timeout: Duration) -> Result<Answer, Error> {
        let url = format!("{}{}", self.base_url, path);
        Answer::read(self.http.get(url).timeout(timeout).send().await?).await
    }

    /// An OAuth POST of an `application/x-www-form-urlencoded` body, which
    /// never carries the API key either. On the token endpoint an
    /// `Authorization` header would read as client authentication, which these
    /// public clients do not have.
    pub(crate) async fn post_form(
        &self,
        path: &str,
        form: &[(&str, &str)],
        timeout: Duration,
    ) -> Result<Answer, Error> {
        let url = format!("{}{}", self.base_url, path);
        Answer::read(self.http.post(url).form(form).timeout(timeout).send().await?).await
    }

    async fn send(
        &self,
        path: &str,
        query: &[(&str, &str)],
        timeout: Duration,
    ) -> Result<reqwest::Response, Error> {
        let url = format!("{}{}", self.base_url, path);
        let mut request = self.http.get(url).query(query).timeout(timeout);
        // Bearer only. The v1 endpoints take `?apikey=`, and the generated
        // client sends a configured key BOTH ways whenever one is set; a v2 key
        // belongs in one header, not in a query string a proxy will log.
        if let Some(key) = &self.api_key {
            request = request.header(AUTHORIZATION, format!("Bearer {key}"));
        }
        Ok(request.send().await?)
    }
}

/// A response read whole, for a caller that classifies it itself. Reading the
/// body inside the request's timeout is what makes that bound cover it.
pub(crate) struct Answer {
    pub(crate) status: u16,
    pub(crate) retry_after: Option<Duration>,
    pub(crate) body: String,
}

impl Answer {
    async fn read(response: reqwest::Response) -> Result<Self, Error> {
        let status = response.status().as_u16();
        let retry_after = parse_retry_after(response.headers());
        Ok(Self { status, retry_after, body: response.text().await? })
    }
}

/// `Retry-After` is seconds or an HTTP date. Its ABSENCE on a 429 is what makes
/// that 429 a spent allowance rather than a throttle, so a header that will not
/// parse reads as absent rather than as zero.
fn parse_retry_after(headers: &HeaderMap) -> Option<Duration> {
    let value = headers.get(RETRY_AFTER)?.to_str().ok()?.trim().to_owned();
    if let Ok(seconds) = value.parse::<u64>() {
        return Some(Duration::from_secs(seconds));
    }
    let wait = http_date(&value)? - chrono::Utc::now().timestamp();
    Some(Duration::from_secs(wait.max(0) as u64))
}

/// An HTTP date as a Unix timestamp, in any of the three forms RFC 9110 says a
/// recipient must read. The RFC 2822 parser takes the IMF-fixdate a server
/// sends, and not the obsolete RFC 850 and asctime forms, so a 429 dated in
/// either was a spent quota rather than a throttle (2.4.2, measured
/// 2026-10-08). Both are GMT, the only zone either may carry.
fn http_date(value: &str) -> Option<i64> {
    if let Ok(when) = chrono::DateTime::parse_from_rfc2822(value) {
        return Some(when.timestamp());
    }
    ["%A, %d-%b-%y %H:%M:%S GMT", "%a %b %e %H:%M:%S %Y"]
        .into_iter()
        .find_map(|format| chrono::NaiveDateTime::parse_from_str(value, format).ok())
        .map(|when| chrono::Utc.from_utc_datetime(&when).timestamp())
}

#[cfg(test)]
mod tests {
    use super::http_date;

    /// RFC 9110's own example, in each of its three forms.
    #[test]
    fn an_http_date_is_read_in_all_three_forms() {
        for value in [
            "Sun, 06 Nov 1994 08:49:37 GMT",
            "Sunday, 06-Nov-94 08:49:37 GMT",
            "Sun Nov  6 08:49:37 1994",
        ] {
            assert_eq!(http_date(value), Some(784_111_777), "{value}");
        }
    }

    /// What a general date parser would read, and an HTTP date must not.
    #[test]
    fn nothing_else_is_an_http_date() {
        for value in ["-1", "x", "tomorrow", "noon", "+1 day", "1e400", "soon", "1994-11-06"] {
            assert_eq!(http_date(value), None, "{value}");
        }
    }
}