internetdata 2.5.4

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

use serde::Deserialize;

/// What every failure from this crate is.
///
/// Match on [`Error::kind`] to branch, or ask [`Error::retryable`] whether
/// retrying this exact request could succeed. The client already retries what
/// is retryable, so an error that reaches you has usually run out of attempts.
#[derive(Debug, thiserror::Error)]
pub enum Error {
    /// The API answered, and said no.
    #[error("internetdata: {kind} (HTTP {status}): {message}")]
    Api {
        kind: ErrorKind,
        /// The API's own `rc`, which names the refusal.
        message: String,
        status: u16,
        /// How long the server asked us to wait. `None` when it did not ask,
        /// which on a 429 means an allowance is spent rather than throttled.
        retry_after: Option<Duration>,
    },

    /// No response arrived: a refused connection, a timeout, a TLS failure, or
    /// a body that could not be decoded. All are worth another attempt.
    #[error("internetdata: network: {0}")]
    Network(#[from] reqwest::Error),

    /// A database transfer failed on this side of the socket: the stream ended
    /// before the promised length (`UnexpectedEof`), the disk filled, or the
    /// destination could not be written. The inner [`std::io::ErrorKind`] is
    /// what tells those apart.
    #[error("internetdata: io: {0}")]
    Io(#[from] std::io::Error),

    /// The client was asked for something it cannot do, before any request was
    /// sent: an unusable base URL, for instance.
    #[error("internetdata: {0}")]
    Config(String),
}

/// Why a request failed.
///
/// [`ErrorKind::RateLimited`] and [`ErrorKind::QuotaExceeded`] both arrive as
/// HTTP 429 and are NOT the same thing. A rate limit is the API protecting
/// itself, carries `Retry-After`, and retrying works. A spent quota carries no
/// such header, and retrying will not help until the window rolls over or the
/// limit is raised. The header is the only thing that distinguishes them.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ErrorKind {
    BadRequest,
    Unauthorized,
    Forbidden,
    RateLimited,
    QuotaExceeded,
    ServerError,
    Network,
    Io,
}

impl ErrorKind {
    /// The wire spelling, which is also the name the shared conformance corpus
    /// uses.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::BadRequest => "bad_request",
            Self::Unauthorized => "unauthorized",
            Self::Forbidden => "forbidden",
            Self::RateLimited => "rate_limited",
            Self::QuotaExceeded => "quota_exceeded",
            Self::ServerError => "server_error",
            Self::Network => "network",
            Self::Io => "io",
        }
    }
}

impl std::fmt::Display for ErrorKind {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

impl Error {
    pub fn kind(&self) -> ErrorKind {
        match self {
            Self::Api { kind, .. } => *kind,
            Self::Network(_) => ErrorKind::Network,
            Self::Io(_) => ErrorKind::Io,
            Self::Config(_) => ErrorKind::BadRequest,
        }
    }

    /// Whether retrying this exact request could succeed.
    ///
    /// A transfer that ended early is worth another attempt and a full disk is
    /// not, and both arrive as [`Error::Io`], so the two are separated by the
    /// inner [`std::io::ErrorKind`] rather than lumped together.
    pub fn retryable(&self) -> bool {
        match self {
            Self::Io(e) => e.kind() == std::io::ErrorKind::UnexpectedEof,
            _ => matches!(
                self.kind(),
                ErrorKind::RateLimited | ErrorKind::ServerError | ErrorKind::Network
            ),
        }
    }

    /// The API's own `rc`, or the transport failure's text.
    pub fn message(&self) -> String {
        match self {
            Self::Api { message, .. } => message.clone(),
            // reqwest names a timeout only in its source chain.
            Self::Network(e) if e.is_timeout() => format!("timed out: {e}"),
            Self::Network(e) => e.to_string(),
            Self::Io(e) => e.to_string(),
            Self::Config(m) => m.clone(),
        }
    }

    /// The HTTP status, or `None` when no response was received.
    pub fn status(&self) -> Option<u16> {
        match self {
            Self::Api { status, .. } => Some(*status),
            _ => None,
        }
    }

    /// How long the server asked us to wait before retrying.
    pub fn retry_after(&self) -> Option<Duration> {
        match self {
            Self::Api { retry_after, .. } => *retry_after,
            _ => None,
        }
    }

    pub(crate) fn from_response(status: u16, retry_after: Option<Duration>, body: &str) -> Self {
        let message =
            envelope_rc(body).unwrap_or_else(|| format!("request failed with status {status}"));
        Self::Api { kind: kind_for_status(status, retry_after), message, status, retry_after }
    }
}

/// What a status code means for a caller. Object storage answers a spent
/// presigned link with the same codes the API uses, so the mapping is shared
/// rather than written twice.
pub(crate) fn kind_for_status(status: u16, retry_after: Option<Duration>) -> ErrorKind {
    match status {
        // Present means transient, absent means an allowance is spent. Nothing
        // else in the response separates the two.
        429 if retry_after.is_some() => ErrorKind::RateLimited,
        429 => ErrorKind::QuotaExceeded,
        401 => ErrorKind::Unauthorized,
        403 => ErrorKind::Forbidden,
        // Any other 4xx is a CLIENT error. Falling through to the server_error
        // default would make it retryable, so a misspelled database id would be
        // retried twice before failing. Three of the four VPNDetection SDKs
        // shipped exactly that. Classify on the RANGE, not on an enumerated
        // list.
        400..=499 => ErrorKind::BadRequest,
        _ => ErrorKind::ServerError,
    }
}

/// The API refuses with `{"rc": "..."}` on every endpoint, so the code it names
/// is what a caller is told rather than a status invented here.
fn envelope_rc(body: &str) -> Option<String> {
    #[derive(Deserialize)]
    struct Envelope {
        rc: Option<String>,
    }
    let envelope: Envelope = serde_json::from_str(body).ok()?;
    envelope.rc.filter(|rc| !rc.is_empty())
}