goat_cli/
client.rs

1//! A shared HTTP client for all GoaT API requests.
2//!
3//! [`GoatClient`](crate::client::GoatClient) wraps [`reqwest::Client`] so the underlying connection pool
4//! is created once and reused across all concurrent requests instead of being
5//! rebuilt on every call. Clone it freely — the inner client is
6//! reference-counted.
7
8use crate::error::{Error, ErrorKind, Result};
9use reqwest::header::ACCEPT;
10use reqwest::Client;
11use serde_json::Value;
12use std::time::Duration;
13
14/// Identify ourselves to the GoaT API.
15const USER_AGENT: &str = concat!("goat-cli/", env!("CARGO_PKG_VERSION"));
16
17/// The most requests to have in flight at once, so that large batches
18/// (e.g. a `-f` file of 500 taxa) don't flood the GoaT API.
19pub const MAX_CONCURRENT_REQUESTS: usize = 8;
20
21/// How many of `n` requests to run at once: at most
22/// [`MAX_CONCURRENT_REQUESTS`], and at least 1 (`buffered(0)` never completes).
23pub fn concurrency(n: usize) -> usize {
24    n.clamp(1, MAX_CONCURRENT_REQUESTS)
25}
26
27/// Shared HTTP client for the GoaT API.
28#[derive(Clone)]
29pub struct GoatClient {
30    inner: Client,
31}
32
33impl GoatClient {
34    /// Construct a new [`GoatClient`].
35    ///
36    /// Create once per program invocation, then clone into async tasks as
37    /// needed — cloning is cheap because the inner client is `Arc`-backed.
38    pub fn new() -> Self {
39        let inner = Client::builder()
40            .user_agent(USER_AGENT)
41            // responses (especially large TSVs) compress ~5x
42            .gzip(true)
43            // no overall timeout, as large searches can legitimately take a while.
44            .connect_timeout(Duration::from_secs(30))
45            .build()
46            .expect("static reqwest client configuration is valid");
47        Self { inner }
48    }
49
50    /// GET `url`, setting the `Accept` header to `accept`, and return the
51    /// response body as a [`String`].
52    ///
53    /// Connection failures and 5xx responses are retried using
54    /// [`again::retry`] with the default policy. Any other non-2xx response,
55    /// or a 2xx JSON body in which GoaT reports `"success": false`, is
56    /// returned as an [`ErrorKind::Api`] error.
57    pub async fn get_text(&self, url: &str, accept: &str) -> Result<String> {
58        let body = self.fetch(url, accept).await?;
59        // GoaT reports query errors as a JSON body with a 200 status, even
60        // when another format (e.g. TSV) was requested.
61        if body.trim_start().starts_with('{') {
62            if let Ok(v) = serde_json::from_str::<Value>(&body) {
63                check_status(&v)?;
64            }
65        }
66        Ok(body)
67    }
68
69    /// GET `url` expecting a JSON response body; parse and return a
70    /// [`serde_json::Value`].
71    pub async fn get_json(&self, url: &str) -> Result<Value> {
72        let body = self.fetch(url, "application/json").await?;
73        let v = serde_json::from_str(&body).map_err(|e| Error::new(ErrorKind::SerdeJSON(e)))?;
74        check_status(&v)?;
75        Ok(v)
76    }
77
78    /// GET `url` and return the body, erroring on a non-2xx status.
79    async fn fetch(&self, url: &str, accept: &str) -> Result<String> {
80        // Clone client and own the strings so the closure is 'static and Fn.
81        let client = self.inner.clone();
82        let url = url.to_owned();
83        let accept = accept.to_owned();
84
85        let resp = again::retry(move || {
86            let request = client.get(&url).header(ACCEPT, accept.as_str());
87            async move {
88                let resp = request.send().await?;
89                // only server errors are worth retrying
90                if resp.status().is_server_error() {
91                    resp.error_for_status()
92                } else {
93                    Ok(resp)
94                }
95            }
96        })
97        .await
98        .map_err(|e| Error::new(ErrorKind::Reqwest(e)))?;
99
100        let status = resp.status();
101        let body = resp
102            .text()
103            .await
104            .map_err(|e| Error::new(ErrorKind::Reqwest(e)))?;
105
106        if !status.is_success() {
107            return Err(Error::new(ErrorKind::Api(format!(
108                "HTTP {}: {}",
109                status,
110                error_message(&body)
111            ))));
112        }
113        Ok(body)
114    }
115}
116
117impl Default for GoatClient {
118    fn default() -> Self {
119        Self::new()
120    }
121}
122
123/// Error if a GoaT JSON response has `"status": {"success": false}`,
124/// either at the top level or, for `/report`, nested under `report`.
125fn check_status(v: &Value) -> Result<()> {
126    for status in [&v["status"], &v["report"]["status"]] {
127        if status["success"] == Value::Bool(false) {
128            let message = status["error"]
129                .as_str()
130                .unwrap_or("the request was unsuccessful");
131            return Err(Error::new(ErrorKind::Api(message.to_string())));
132        }
133    }
134    Ok(())
135}
136
137/// Pull a human readable message out of an error response body.
138fn error_message(body: &str) -> String {
139    if let Ok(v) = serde_json::from_str::<Value>(body) {
140        if let Some(m) = v["message"].as_str().or_else(|| v["status"]["error"].as_str()) {
141            return m.to_string();
142        }
143    }
144    let body = body.trim();
145    match body.char_indices().nth(200) {
146        Some((i, _)) => format!("{}...", &body[..i]),
147        None => body.to_string(),
148    }
149}
150
151#[cfg(test)]
152mod tests {
153    use super::*;
154    use serde_json::json;
155
156    #[test]
157    fn test_concurrency_is_capped_and_never_zero() {
158        assert_eq!(concurrency(0), 1);
159        assert_eq!(concurrency(3), 3);
160        assert_eq!(concurrency(500), MAX_CONCURRENT_REQUESTS);
161    }
162
163    #[test]
164    fn test_check_status_success() {
165        assert!(check_status(&json!({"status": {"success": true}, "count": 3})).is_ok());
166    }
167
168    #[test]
169    fn test_check_status_missing_status_is_ok() {
170        assert!(check_status(&json!({"count": 3})).is_ok());
171    }
172
173    #[test]
174    fn test_check_status_failure_reports_api_message() {
175        let v = json!({"status": {"success": false, "error": "invalid attribute name in foo > 1"}});
176        let err = check_status(&v).unwrap_err();
177        assert!(matches!(err.kind(), ErrorKind::Api(_)));
178        assert!(err.to_string().contains("invalid attribute name in foo > 1"));
179    }
180
181    #[test]
182    fn test_check_status_nested_report_failure() {
183        let v = json!({"status": {"success": true}, "report": {"status": {"success": false, "error": "unable to load report"}}});
184        let err = check_status(&v).unwrap_err();
185        assert!(err.to_string().contains("unable to load report"));
186    }
187
188    #[test]
189    fn test_error_message_prefers_json_message() {
190        let body = r#"{"message":"Parameter 'query' must be url encoded.","errors":[]}"#;
191        assert_eq!(error_message(body), "Parameter 'query' must be url encoded.");
192    }
193
194    #[test]
195    fn test_error_message_truncates_non_json() {
196        let body = "x".repeat(500);
197        assert_eq!(error_message(&body).len(), 203);
198    }
199}