appblocklist 1.0.0

//! Client for the [AppBlockList](https://www.appblocklist.com) App Lookup API.
//!
//! One call takes an iOS bundle ID, an App Store ID (with or without the `id`
//! prefix) or an Android package name and returns the app's name, developer,
//! store genre, age rating, ranked filtering categories and IAB category.
//!
//! ```no_run
//! let client = appblocklist::Client::from_env()?;
//! let app = client.lookup("com.zhiliaoapp.musically")?;
//! if app.found && app.in_category(&["Social Networking"]) {
//!     println!("block {}", app.bundle_id);
//! }
//! # Ok::<(), appblocklist::Error>(())
//! ```
//!
//! A 404 is not an error: it comes back as an [`App`] with `found == false`.

use serde::{Deserialize, Deserializer, Serialize};
use std::collections::HashSet;
use std::fmt;
use std::thread;
use std::time::Duration;

/// Version of this crate.
pub const VERSION: &str = "1.0.0";
/// API root. The lookup endpoint is `DEFAULT_BASE_URL + "/app"`.
pub const DEFAULT_BASE_URL: &str = "https://www.appblocklist.com/api/v1";
/// Environment variable read by [`Client::from_env`].
pub const ENV_API_KEY: &str = "APPBLOCKLIST_API_KEY";
/// Longest ID the API accepts.
pub const MAX_ID_LENGTH: usize = 200;
/// User-Agent sent with every request.
pub const USER_AGENT: &str = "appblocklist-rust/1.0.0 (+https://www.appblocklist.com)";

/// One answer from the lookup endpoint.
///
/// When `found` is false the other fields are empty, except `android_package`
/// for apps listed on Google Play but not yet categorized, and `message`,
/// which carries the API's explanation.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct App {
    #[serde(default)]
    pub found: bool,
    #[serde(default)]
    pub name: String,
    #[serde(default)]
    pub developer: String,
    #[serde(default)]
    pub bundle_id: String,
    /// Returned by the API as a string; numbers are accepted too.
    #[serde(default, deserialize_with = "string_or_number")]
    pub app_store_id: String,
    /// Google Play twin, or an empty string.
    #[serde(default)]
    pub android_package: String,
    #[serde(default)]
    pub app_store_genre: String,
    /// App Store age rating such as `4+`, `9+`, `12+` or `17+`.
    #[serde(default)]
    pub age_rating: String,
    /// Ranked, most descriptive first. One or more of 58 categories.
    #[serde(default, deserialize_with = "vec_or_null")]
    pub filtering_categories: Vec<String>,
    #[serde(default)]
    pub developer_domain: String,
    #[serde(default)]
    pub iab_category: String,
    /// The `error` text sent with a 404.
    #[serde(default, rename = "error", skip_serializing_if = "Option::is_none")]
    pub message: Option<String>,
}

impl App {
    /// The most descriptive filtering category, if any.
    pub fn primary_category(&self) -> Option<&str> {
        self.filtering_categories.first().map(String::as_str)
    }

    /// True when the app carries any of `categories` (case-insensitive).
    pub fn in_category<S: AsRef<str>>(&self, categories: &[S]) -> bool {
        self.filtering_categories.iter().any(|have| {
            categories
                .iter()
                .any(|want| have.trim().eq_ignore_ascii_case(want.as_ref().trim()))
        })
    }

    /// True when an Android package name is known for the app.
    pub fn on_google_play(&self) -> bool {
        !self.android_package.is_empty()
    }

    /// Identifiers an MDM needs to block this app on both platforms.
    pub fn block_ids(&self) -> Vec<&str> {
        let mut ids = Vec::new();
        if !self.bundle_id.is_empty() {
            ids.push(self.bundle_id.as_str());
        }
        if !self.android_package.is_empty() && self.android_package != self.bundle_id {
            ids.push(self.android_package.as_str());
        }
        ids
    }
}

fn string_or_number<'de, D: Deserializer<'de>>(d: D) -> Result<String, D::Error> {
    Ok(match serde_json::Value::deserialize(d)? {
        serde_json::Value::String(s) => s,
        serde_json::Value::Null => String::new(),
        other => other.to_string(),
    })
}

fn vec_or_null<'de, D: Deserializer<'de>>(d: D) -> Result<Vec<String>, D::Error> {
    Ok(Option::<Vec<String>>::deserialize(d)?.unwrap_or_default())
}

/// Everything that can go wrong in a lookup.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Error {
    /// No key passed and `APPBLOCKLIST_API_KEY` not set.
    MissingApiKey,
    /// HTTP 400, or rejected locally before sending.
    InvalidId(String),
    /// HTTP 401: missing or invalid key.
    Unauthorized(String),
    /// HTTP 403: the key has used its monthly lookups.
    QuotaExceeded {
        message: String,
        monthly_lookups: Option<u64>,
    },
    /// HTTP 500 or other 5xx: temporary, retry later.
    Server { status: u16, message: String },
    /// Any other status the API does not document.
    Unexpected { status: u16, message: String },
    /// Network, TLS or timeout problem.
    Transport(String),
    /// The body was not the JSON the API sends.
    Decode(String),
}

impl Error {
    /// HTTP status, when the error came from an answer.
    pub fn status(&self) -> Option<u16> {
        match self {
            Error::InvalidId(_) => Some(400),
            Error::Unauthorized(_) => Some(401),
            Error::QuotaExceeded { .. } => Some(403),
            Error::Server { status, .. } | Error::Unexpected { status, .. } => Some(*status),
            _ => None,
        }
    }

    /// True when retrying the same request later can succeed.
    pub fn is_temporary(&self) -> bool {
        matches!(self, Error::Server { .. } | Error::Transport(_))
    }

    /// True when no further lookups with this key can succeed right now.
    pub fn is_fatal(&self) -> bool {
        matches!(
            self,
            Error::MissingApiKey | Error::Unauthorized(_) | Error::QuotaExceeded { .. }
        )
    }
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Error::MissingApiKey => write!(f, "appblocklist: no API key (set {})", ENV_API_KEY),
            Error::InvalidId(m) => write!(f, "appblocklist: invalid id: {}", m),
            Error::Unauthorized(m) => write!(f, "appblocklist: unauthorized: {}", m),
            Error::QuotaExceeded { message, .. } => {
                write!(f, "appblocklist: monthly lookups used up: {}", message)
            }
            Error::Server { status, message } => {
                write!(f, "appblocklist: server error {}: {}", status, message)
            }
            Error::Unexpected { status, message } => {
                write!(f, "appblocklist: unexpected HTTP {}: {}", status, message)
            }
            Error::Transport(m) => write!(f, "appblocklist: transport: {}", m),
            Error::Decode(m) => write!(f, "appblocklist: decode: {}", m),
        }
    }
}

impl std::error::Error for Error {}

/// Trim an ID and check it locally: non-empty, at most 200 characters,
/// no whitespace inside. The API does the full format check.
pub fn validate_id(id: &str) -> Result<&str, Error> {
    let id = id.trim();
    if id.is_empty() {
        return Err(Error::InvalidId("empty id".into()));
    }
    if id.chars().count() > MAX_ID_LENGTH {
        return Err(Error::InvalidId(format!(
            "id longer than {} characters",
            MAX_ID_LENGTH
        )));
    }
    if id.chars().any(char::is_whitespace) {
        return Err(Error::InvalidId("id contains whitespace".into()));
    }
    Ok(id)
}

/// Turn an HTTP status and body into a result, exactly as [`Client::lookup`]
/// does. Useful for replaying recorded answers in tests.
pub fn parse_response(status: u16, body: &str) -> Result<App, Error> {
    match status {
        200 => serde_json::from_str::<App>(body).map_err(|e| Error::Decode(e.to_string())),
        404 => {
            let mut app = serde_json::from_str::<App>(body).unwrap_or_else(|_| App {
                message: Some(body.trim().to_string()),
                ..App::default()
            });
            app.found = false;
            Ok(app)
        }
        _ => {
            let v: serde_json::Value = serde_json::from_str(body).unwrap_or(serde_json::Value::Null);
            let message = v
                .get("error")
                .and_then(|e| e.as_str())
                .map(str::to_string)
                .unwrap_or_else(|| body.trim().to_string());
            Err(match status {
                400 => Error::InvalidId(message),
                401 => Error::Unauthorized(message),
                403 => Error::QuotaExceeded {
                    message,
                    monthly_lookups: v.get("monthly_lookups").and_then(|m| {
                        m.as_u64()
                            .or_else(|| m.as_str().and_then(|s| s.trim().parse().ok()))
                    }),
                },
                500..=599 => Error::Server { status, message },
                _ => Error::Unexpected { status, message },
            })
        }
    }
}

/// Blocking API client. Cheap to clone; clones share a connection pool.
#[derive(Clone)]
pub struct Client {
    api_key: String,
    base_url: String,
    agent: ureq::Agent,
    max_retries: u32,
    retry_wait: Duration,
}

impl fmt::Debug for Client {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Client")
            .field("base_url", &self.base_url)
            .field("max_retries", &self.max_retries)
            .finish_non_exhaustive()
    }
}

impl Client {
    /// Client with an explicit key and a 30 second timeout.
    pub fn new(api_key: impl Into<String>) -> Self {
        Client {
            api_key: api_key.into().trim().to_string(),
            base_url: DEFAULT_BASE_URL.to_string(),
            agent: ureq::AgentBuilder::new()
                .timeout(Duration::from_secs(30))
                .user_agent(USER_AGENT)
                .build(),
            max_retries: 2,
            retry_wait: Duration::from_secs(1),
        }
    }

    /// Client with the key from `APPBLOCKLIST_API_KEY`.
    pub fn from_env() -> Result<Self, Error> {
        match std::env::var(ENV_API_KEY) {
            Ok(k) if !k.trim().is_empty() => Ok(Client::new(k)),
            _ => Err(Error::MissingApiKey),
        }
    }

    /// Use another API root (for a local mock server, for example).
    pub fn with_base_url(mut self, base_url: impl Into<String>) -> Self {
        self.base_url = base_url.into().trim_end_matches('/').to_string();
        self
    }

    /// Use your own `ureq::Agent` (proxy, custom TLS, other timeouts).
    /// Set a User-Agent on it with `AgentBuilder::user_agent(USER_AGENT)`.
    pub fn with_agent(mut self, agent: ureq::Agent) -> Self {
        self.agent = agent;
        self
    }

    /// How often a 5xx or network error is retried, and the first pause
    /// (doubled on every retry).
    pub fn with_retries(mut self, max_retries: u32, first_wait: Duration) -> Self {
        self.max_retries = max_retries;
        self.retry_wait = first_wait;
        self
    }

    /// Look up one app by iOS bundle ID, App Store ID or Android package
    /// name. Each 200 answer counts as one lookup.
    pub fn lookup(&self, id: &str) -> Result<App, Error> {
        let id = validate_id(id)?;
        if self.api_key.is_empty() {
            return Err(Error::MissingApiKey);
        }
        let mut wait = self.retry_wait;
        let mut attempt = 0;
        loop {
            match self.once(id) {
                Err(e) if e.is_temporary() && attempt < self.max_retries => {
                    thread::sleep(wait);
                    wait *= 2;
                    attempt += 1;
                }
                other => return other,
            }
        }
    }

    fn once(&self, id: &str) -> Result<App, Error> {
        let url = format!("{}/app", self.base_url);
        let result = self
            .agent
            .get(&url)
            .query("id", id)
            .set("X-API-Key", &self.api_key)
            .set("Accept", "application/json")
            .call();
        let (status, response) = match result {
            Ok(r) => (r.status(), r),
            Err(ureq::Error::Status(code, r)) => (code, r),
            Err(ureq::Error::Transport(t)) => return Err(Error::Transport(t.to_string())),
        };
        let body = response
            .into_string()
            .map_err(|e| Error::Transport(e.to_string()))?;
        parse_response(status, &body)
    }

    /// Look up many IDs one after another, as the service asks. Blank and
    /// repeated IDs are skipped. Per-ID errors are kept in the output; a
    /// fatal error (401, 403, missing key) stops the loop and is returned
    /// together with the results collected so far.
    pub fn lookup_many<I, S>(&self, ids: I, pause: Duration) -> (Vec<(String, Result<App, Error>)>, Option<Error>)
    where
        I: IntoIterator<Item = S>,
        S: AsRef<str>,
    {
        let mut seen = HashSet::new();
        let mut out = Vec::new();
        for raw in ids {
            let id = raw.as_ref().trim().to_string();
            if id.is_empty() || !seen.insert(id.clone()) {
                continue;
            }
            if !out.is_empty() && !pause.is_zero() {
                thread::sleep(pause);
            }
            let res = self.lookup(&id);
            if let Err(e) = &res {
                if e.is_fatal() {
                    return (out, Some(e.clone()));
                }
            }
            out.push((id, res));
        }
        (out, None)
    }
}

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

    #[test]
    fn validates_locally() {
        assert_eq!(validate_id("  id835599320 ").unwrap(), "id835599320");
        assert!(matches!(validate_id(""), Err(Error::InvalidId(_))));
        assert!(matches!(validate_id("com.example app"), Err(Error::InvalidId(_))));
        assert!(validate_id(&"a".repeat(MAX_ID_LENGTH + 1)).is_err());
        assert!(validate_id(&"a".repeat(MAX_ID_LENGTH)).is_ok());
    }

    #[test]
    fn missing_key_is_reported_before_any_request() {
        let c = Client::new("").with_base_url("http://127.0.0.1:1");
        assert_eq!(c.lookup("com.example"), Err(Error::MissingApiKey));
    }
}