Skip to main content

crate_plugin_kit/
registry.rs

1//! crates.io queries.
2//!
3//! Only two endpoints are used:
4//!
5//! | Purpose | Endpoint |
6//! | ---- | ---- |
7//! | Search by keyword | `GET {registry}/api/v1/crates?q=<kw>&per_page=N` |
8//! | Look up by exact name | `GET {registry}/api/v1/crates/<name>` |
9//!
10//! `registry` may point at a mirror (see [`crate::KitConfig::registry`]).
11//!
12//! crates.io requires a `User-Agent` and answers 403 without one. It is built from
13//! the host id plus this crate's version.
14
15use serde::Deserialize;
16
17use crate::config::KitConfig;
18use crate::error::{KitError, KitResult};
19
20/// One search result.
21#[derive(Debug, Clone)]
22pub struct CrateSummary {
23    /// Crate name.
24    pub name: String,
25    /// Latest version.
26    pub version: String,
27    /// Description.
28    pub description: Option<String>,
29    /// Total download count.
30    pub downloads: u64,
31}
32
33/// Detailed information about one crate.
34#[derive(Debug, Clone)]
35pub struct CrateInfo {
36    /// Crate name.
37    pub name: String,
38    /// Latest version.
39    pub version: String,
40    /// Description.
41    pub description: Option<String>,
42    /// Source repository URL (prebuilt downloads build the Release URL from it).
43    pub repository: Option<String>,
44}
45
46/// crates.io client.
47#[derive(Debug, Clone)]
48pub struct Registry {
49    base: String,
50    user_agent: String,
51}
52
53// ---- JSON shapes returned by the API ---------------------------------------
54
55#[derive(Deserialize)]
56struct SearchResponse {
57    #[serde(default)]
58    crates: Vec<SearchCrate>,
59}
60
61#[derive(Deserialize)]
62struct SearchCrate {
63    name: String,
64    #[serde(default)]
65    max_version: Option<String>,
66    #[serde(default)]
67    description: Option<String>,
68    #[serde(default)]
69    downloads: u64,
70}
71
72#[derive(Deserialize)]
73struct ViewResponse {
74    #[serde(rename = "crate")]
75    krate: ViewCrate,
76}
77
78#[derive(Deserialize)]
79struct ViewCrate {
80    name: String,
81    #[serde(default)]
82    max_version: Option<String>,
83    #[serde(default)]
84    description: Option<String>,
85    #[serde(default)]
86    repository: Option<String>,
87}
88
89impl Registry {
90    /// Builds a client from the config.
91    pub fn new(cfg: &KitConfig) -> Self {
92        Self {
93            base: cfg.registry.trim_end_matches('/').to_string(),
94            // crates.io wants contact information in the User-Agent, otherwise the
95            // requests may be rate-limited. The repository URL comes from
96            // `Cargo.toml`'s `repository` field (injected by Cargo at compile time)
97            // so that it cannot drift away from the manifest.
98            user_agent: format!(
99                "{} (crate-plugin-kit/{}; +{})",
100                cfg.id,
101                env!("CARGO_PKG_VERSION"),
102                env!("CARGO_PKG_REPOSITORY"),
103            ),
104        }
105    }
106
107    /// Searches by keyword.
108    pub fn search(&self, keyword: &str, limit: usize) -> KitResult<Vec<CrateSummary>> {
109        let url = format!(
110            "{}/api/v1/crates?q={}&per_page={}",
111            self.base,
112            percent_encode(keyword),
113            limit
114        );
115        let text = self.get_text(&url)?;
116
117        let parsed: SearchResponse = serde_json::from_str(&text)
118            .map_err(|e| KitError::Registry(format!("failed to parse search results: {e}")))?;
119
120        Ok(parsed
121            .crates
122            .into_iter()
123            .map(|c| CrateSummary {
124                name: c.name,
125                version: c.max_version.unwrap_or_default(),
126                description: c.description,
127                downloads: c.downloads,
128            })
129            .collect())
130    }
131
132    /// Looks up an exact name. Returns `Ok(None)` when it does not exist.
133    pub fn view(&self, name: &str) -> KitResult<Option<CrateInfo>> {
134        let url = format!("{}/api/v1/crates/{}", self.base, percent_encode(name));
135
136        let text = match self.get_text(&url) {
137            Ok(t) => t,
138            // A 404 means "this crate does not exist", which is not an error.
139            Err(KitError::Http(msg)) if msg.contains("404") => return Ok(None),
140            Err(e) => return Err(e),
141        };
142
143        let parsed: ViewResponse = serde_json::from_str(&text)
144            .map_err(|e| KitError::Registry(format!("failed to parse lookup result: {e}")))?;
145
146        Ok(Some(CrateInfo {
147            name: parsed.krate.name,
148            version: parsed.krate.max_version.unwrap_or_default(),
149            description: parsed.krate.description,
150            repository: parsed.krate.repository,
151        }))
152    }
153
154    fn get_text(&self, url: &str) -> KitResult<String> {
155        let mut res = ureq::get(url)
156            .header("User-Agent", &self.user_agent)
157            .header("Accept", "application/json")
158            .call()
159            .map_err(|e| KitError::Http(describe_ureq_error(&e, url)))?;
160
161        res.body_mut()
162            .read_to_string()
163            .map_err(|e| KitError::Http(format!("failed to read response body ({url}): {e}")))
164    }
165
166    /// Downloads one file into memory. Returns `Ok(None)` when there is nothing to
167    /// download (a 404, for instance).
168    ///
169    /// The prebuilt path uses it to fetch a single artifact file.
170    pub fn try_download(&self, url: &str, limit_bytes: u64) -> KitResult<Option<Vec<u8>>> {
171        match ureq::get(url).header("User-Agent", &self.user_agent).call() {
172            Ok(mut res) => {
173                let body = res
174                    .body_mut()
175                    .read_to_vec()
176                    .map_err(|e| KitError::Http(format!("failed to read {url}: {e}")))?;
177                if body.len() as u64 > limit_bytes {
178                    return Err(KitError::Http(format!(
179                        "{url} exceeds the size limit ({} bytes > {limit_bytes})",
180                        body.len()
181                    )));
182                }
183                Ok(Some(body))
184            }
185            Err(ureq::Error::StatusCode(404)) => Ok(None),
186            Err(e) => Err(KitError::Http(describe_ureq_error(&e, url))),
187        }
188    }
189}
190
191/// Turns a ureq error into a sentence a human can read, with the status code pulled
192/// out on its own because callers need to detect 404.
193fn describe_ureq_error(e: &ureq::Error, url: &str) -> String {
194    match e {
195        ureq::Error::StatusCode(code) => format!("HTTP {code} ({url})"),
196        other => format!("{other} ({url})"),
197    }
198}
199
200/// Minimal percent encoding: only the characters that are safe in a URL are left
201/// alone.
202///
203/// A dependency like `urlencoding` is not worth pulling in for this one function —
204/// crate names and search terms are short.
205fn percent_encode(s: &str) -> String {
206    let mut out = String::with_capacity(s.len());
207    for b in s.bytes() {
208        match b {
209            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
210                out.push(b as char)
211            }
212            _ => out.push_str(&format!("%{b:02X}")),
213        }
214    }
215    out
216}
217
218#[cfg(test)]
219mod tests {
220    use super::percent_encode;
221
222    #[test]
223    fn encodes_reserved_characters() {
224        assert_eq!(percent_encode("a b"), "a%20b");
225        assert_eq!(percent_encode("bmux-plugin"), "bmux-plugin");
226        assert_eq!(percent_encode("a/b?c"), "a%2Fb%3Fc");
227    }
228}