Skip to main content

ask/
http.rs

1//! A small injectable HTTP client abstraction shared by the registry lookup,
2//! the ecosystem resolvers, and (later) the web/llms-txt sources.
3//!
4//! The TypeScript code calls the global `fetch`; porting that verbatim would
5//! make every network path untestable without a live server. Instead callers
6//! take a `&dyn HttpClient`, so production wires [`UreqClient`] (a 10s-timeout
7//! ureq agent) while tests inject [`mock::MockClient`] with canned responses —
8//! the same parity-by-unit-test approach used for the pure modules.
9
10use std::time::Duration;
11
12/// A completed HTTP response: the numeric status and the body as text. Non-2xx
13/// responses are returned as `Ok` (not errors) so callers can branch on 404 vs
14/// other statuses exactly like the TS `response.ok` / `response.status` checks.
15#[derive(Debug, Clone)]
16pub struct HttpResponse {
17    pub status: u16,
18    pub body: String,
19}
20
21impl HttpResponse {
22    /// `true` for a 2xx status (parity with `fetch`'s `response.ok`).
23    pub fn ok(&self) -> bool {
24        (200..300).contains(&self.status)
25    }
26}
27
28/// A completed HTTP response with a binary body (for archive downloads).
29#[derive(Debug, Clone)]
30pub struct BytesResponse {
31    pub status: u16,
32    pub body: Vec<u8>,
33}
34
35impl BytesResponse {
36    /// `true` for a 2xx status (parity with `fetch`'s `response.ok`).
37    pub fn ok(&self) -> bool {
38        (200..300).contains(&self.status)
39    }
40}
41
42/// Upper bound on a downloaded archive body (50 MiB) — well above any docs
43/// tarball, but a guard against a runaway/hostile response.
44const MAX_ARCHIVE_BYTES: u64 = 50 * 1024 * 1024;
45
46/// A GET-only HTTP client. `get` reads the body as text; `get_bytes` reads it as
47/// raw bytes with optional request headers (used for GitHub/npm tarball
48/// downloads). A transport failure (DNS, connect, timeout, read) is an `Err`,
49/// while any HTTP status (including 4xx/5xx) is an `Ok`.
50pub trait HttpClient {
51    fn get(&self, url: &str) -> anyhow::Result<HttpResponse>;
52
53    fn get_bytes(&self, url: &str, headers: &[(&str, &str)]) -> anyhow::Result<BytesResponse>;
54}
55
56/// The production client: a ureq agent with a 10s global timeout (parity with
57/// the TS `AbortSignal.timeout(10_000)`) that surfaces HTTP status codes rather
58/// than turning 4xx/5xx into transport errors.
59pub struct UreqClient {
60    agent: ureq::Agent,
61}
62
63impl UreqClient {
64    pub fn new() -> Self {
65        let agent: ureq::Agent = ureq::Agent::config_builder()
66            .timeout_global(Some(Duration::from_secs(10)))
67            .http_status_as_error(false)
68            .build()
69            .into();
70        Self { agent }
71    }
72}
73
74impl Default for UreqClient {
75    fn default() -> Self {
76        Self::new()
77    }
78}
79
80impl HttpClient for UreqClient {
81    fn get(&self, url: &str) -> anyhow::Result<HttpResponse> {
82        let mut response = self.agent.get(url).call()?;
83        let status = response.status().as_u16();
84        let body = response.body_mut().read_to_string()?;
85        Ok(HttpResponse { status, body })
86    }
87
88    fn get_bytes(&self, url: &str, headers: &[(&str, &str)]) -> anyhow::Result<BytesResponse> {
89        let mut request = self.agent.get(url);
90        for (name, value) in headers {
91            request = request.header(*name, *value);
92        }
93        let mut response = request.call()?;
94        let status = response.status().as_u16();
95        let body = response
96            .body_mut()
97            .with_config()
98            .limit(MAX_ARCHIVE_BYTES)
99            .read_to_vec()?;
100        Ok(BytesResponse { status, body })
101    }
102}
103
104/// Percent-encode a string the way JavaScript's `encodeURIComponent` does:
105/// everything except the unreserved set `A-Za-z0-9-_.!~*'()` is UTF-8 encoded to
106/// `%XX` (uppercase hex). Used for registry catch-all path segments (scoped npm
107/// names contain `/` and `@`) and Maven Solr query params.
108pub fn encode_uri_component(input: &str) -> String {
109    const HEX: &[u8; 16] = b"0123456789ABCDEF";
110    let mut out = String::with_capacity(input.len());
111    for &b in input.as_bytes() {
112        let unreserved = b.is_ascii_alphanumeric()
113            || matches!(
114                b,
115                b'-' | b'_' | b'.' | b'!' | b'~' | b'*' | b'\'' | b'(' | b')'
116            );
117        if unreserved {
118            out.push(b as char);
119        } else {
120            out.push('%');
121            out.push(HEX[(b >> 4) as usize] as char);
122            out.push(HEX[(b & 0x0f) as usize] as char);
123        }
124    }
125    out
126}
127
128/// In-memory HTTP client for tests. Maps exact URLs to canned responses; an
129/// unmapped URL returns a transport error (simulating a network failure).
130#[cfg(test)]
131pub mod mock {
132    use std::collections::HashMap;
133
134    use super::{BytesResponse, HttpClient, HttpResponse};
135
136    #[derive(Default)]
137    pub struct MockClient {
138        responses: HashMap<String, HttpResponse>,
139        bytes: HashMap<String, BytesResponse>,
140    }
141
142    impl MockClient {
143        pub fn new() -> Self {
144            Self::default()
145        }
146
147        /// Register a canned response for an exact URL.
148        pub fn with(mut self, url: &str, status: u16, body: &str) -> Self {
149            self.responses.insert(
150                url.to_string(),
151                HttpResponse {
152                    status,
153                    body: body.to_string(),
154                },
155            );
156            self
157        }
158
159        /// Register a canned binary response for an exact URL.
160        pub fn with_bytes(mut self, url: &str, status: u16, body: Vec<u8>) -> Self {
161            self.bytes
162                .insert(url.to_string(), BytesResponse { status, body });
163            self
164        }
165    }
166
167    impl HttpClient for MockClient {
168        fn get(&self, url: &str) -> anyhow::Result<HttpResponse> {
169            self.responses
170                .get(url)
171                .cloned()
172                .ok_or_else(|| anyhow::anyhow!("MockClient: no response registered for {url}"))
173        }
174
175        fn get_bytes(&self, url: &str, _headers: &[(&str, &str)]) -> anyhow::Result<BytesResponse> {
176            self.bytes.get(url).cloned().ok_or_else(|| {
177                anyhow::anyhow!("MockClient: no bytes response registered for {url}")
178            })
179        }
180    }
181}
182
183#[cfg(test)]
184mod tests {
185    use super::*;
186
187    #[test]
188    fn encode_uri_component_matches_js() {
189        assert_eq!(encode_uri_component("next"), "next");
190        assert_eq!(
191            encode_uri_component("@mastra/client-js"),
192            "%40mastra%2Fclient-js"
193        );
194        assert_eq!(encode_uri_component("a b"), "a%20b");
195        // Unreserved punctuation is left intact.
196        assert_eq!(encode_uri_component("-_.!~*'()"), "-_.!~*'()");
197        // Multi-byte UTF-8 is percent-encoded per byte.
198        assert_eq!(encode_uri_component("é"), "%C3%A9");
199    }
200
201    #[test]
202    fn response_ok_only_for_2xx() {
203        let mk = |status| HttpResponse {
204            status,
205            body: String::new(),
206        };
207        assert!(mk(200).ok());
208        assert!(mk(299).ok());
209        assert!(!mk(404).ok());
210        assert!(!mk(500).ok());
211        assert!(!mk(301).ok());
212    }
213
214    #[test]
215    fn mock_client_returns_canned_and_errors_on_miss() {
216        use super::mock::MockClient;
217        let client = MockClient::new().with("https://x/y", 200, "{\"ok\":true}");
218        let resp = client.get("https://x/y").unwrap();
219        assert_eq!(resp.status, 200);
220        assert!(resp.body.contains("ok"));
221        assert!(client.get("https://x/other").is_err());
222    }
223}