Skip to main content

docsrs_cli/
crates_io.rs

1//! crates.io search-crates operation.
2
3use serde::{Deserialize, Serialize};
4use url::Url;
5
6use crate::config::{HOST_CRATES_IO, MAX_PER_PAGE};
7use crate::error::{AppError, AppResult, ErrorKind};
8use crate::http::{HttpClient, content_type_looks_json, decode_utf8};
9
10/// One hit from crates.io search.
11#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
12pub struct CrateSearchHit {
13    /// Crate name on crates.io.
14    pub name: String,
15    /// Short crate description (may be empty).
16    pub description: String,
17    /// Total download count.
18    pub downloads: u64,
19    /// Newest or default version string for display.
20    pub version: String,
21    /// Documentation URL when provided by crates.io.
22    #[serde(skip_serializing_if = "Option::is_none")]
23    pub documentation: Option<String>,
24    /// Highest published version when present.
25    #[serde(skip_serializing_if = "Option::is_none")]
26    pub max_version: Option<String>,
27    /// Highest stable version when present.
28    #[serde(skip_serializing_if = "Option::is_none")]
29    pub max_stable_version: Option<String>,
30    /// Default version selected by crates.io.
31    #[serde(skip_serializing_if = "Option::is_none")]
32    pub default_version: Option<String>,
33    /// Recent download count when present.
34    #[serde(skip_serializing_if = "Option::is_none")]
35    pub recent_downloads: Option<u64>,
36    /// Whether the query matched the crate name exactly.
37    #[serde(skip_serializing_if = "Option::is_none")]
38    pub exact_match: Option<bool>,
39    /// Whether the default version is yanked.
40    #[serde(skip_serializing_if = "Option::is_none")]
41    pub yanked: Option<bool>,
42    /// Source repository URL when present.
43    #[serde(skip_serializing_if = "Option::is_none")]
44    pub repository: Option<String>,
45    /// Project homepage URL when present.
46    #[serde(skip_serializing_if = "Option::is_none")]
47    pub homepage: Option<String>,
48}
49
50/// Pagination meta from crates.io (may contain `page=` or `seek=` tokens).
51#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
52pub struct SearchMeta {
53    /// Total hits reported by crates.io.
54    pub total: u64,
55    /// Opaque next-page token when more results exist.
56    #[serde(skip_serializing_if = "Option::is_none")]
57    pub next_page: Option<String>,
58    /// Opaque previous-page token when available.
59    #[serde(skip_serializing_if = "Option::is_none")]
60    pub prev_page: Option<String>,
61}
62
63/// Full search-crates data payload.
64#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
65pub struct SearchCratesData {
66    /// Original search query string.
67    pub query: String,
68    /// 1-based page number used for the request.
69    pub page: u32,
70    /// Page size used for the request.
71    pub per_page: u32,
72    /// Sort order API token.
73    pub sort: String,
74    /// Search hits on this page.
75    pub hits: Vec<CrateSearchHit>,
76    /// Pagination metadata from crates.io.
77    pub meta: SearchMeta,
78}
79
80#[derive(Debug, Deserialize)]
81struct ApiResponse {
82    crates: Vec<ApiCrate>,
83    meta: ApiMeta,
84}
85
86#[derive(Debug, Deserialize)]
87struct ApiCrate {
88    name: String,
89    description: Option<String>,
90    downloads: u64,
91    newest_version: Option<String>,
92    max_version: Option<String>,
93    max_stable_version: Option<String>,
94    default_version: Option<String>,
95    documentation: Option<String>,
96    recent_downloads: Option<u64>,
97    exact_match: Option<bool>,
98    yanked: Option<bool>,
99    repository: Option<String>,
100    homepage: Option<String>,
101}
102
103#[derive(Debug, Deserialize)]
104struct ApiMeta {
105    total: u64,
106    next_page: Option<String>,
107    prev_page: Option<String>,
108}
109
110/// Clamp crates.io pagination to product bounds (`per_page` 1..=100, `page` >= 1).
111///
112/// Dry-run `planned_params` and the request URL MUST use these same values so
113/// agents never see `page=0` in params while the URL has `page=1`.
114pub fn clamp_search_pagination(per_page: u32, page: u32) -> (u32, u32) {
115    (per_page.clamp(1, MAX_PER_PAGE), page.max(1))
116}
117
118/// Build the planned crates.io search URL.
119///
120/// # Errors
121///
122/// Returns [`ErrorKind::Internal`] when the base URL cannot be parsed.
123pub fn planned_url(query: &str, per_page: u32, sort: &str, page: u32) -> AppResult<Url> {
124    planned_url_on_host(HOST_CRATES_IO, query, per_page, sort, page)
125}
126
127/// Build search URL against an arbitrary host (used by tests / local mocks).
128///
129/// # Errors
130///
131/// Returns [`ErrorKind::Internal`] when `host` does not form a valid base URL.
132pub fn planned_url_on_host(
133    host: &str,
134    query: &str,
135    per_page: u32,
136    sort: &str,
137    page: u32,
138) -> AppResult<Url> {
139    let (per_page, page) = clamp_search_pagination(per_page, page);
140    let scheme = if host.starts_with("http://") || host.starts_with("https://") {
141        ""
142    } else {
143        "https://"
144    };
145    let base = if scheme.is_empty() {
146        format!("{host}/api/v1/crates")
147    } else {
148        format!("{scheme}{host}/api/v1/crates")
149    };
150    let mut url = Url::parse(&base)
151        .map_err(|e| AppError::with_source(ErrorKind::Internal, "invalid crates.io base URL", e))?;
152    {
153        let mut q = url.query_pairs_mut();
154        q.append_pair("q", query);
155        q.append_pair("per_page", &per_page.to_string());
156        q.append_pair("sort", sort);
157        q.append_pair("page", &page.to_string());
158    }
159    Ok(url)
160}
161
162/// Parse crates.io JSON body into product types (offline-testable).
163///
164/// # Errors
165///
166/// Returns [`ErrorKind::Parse`] when `text` is not valid crates.io search JSON.
167pub fn parse_search_body(
168    text: &str,
169    query: &str,
170    page: u32,
171    per_page: u32,
172    sort: &str,
173) -> AppResult<SearchCratesData> {
174    let (per_page, page) = clamp_search_pagination(per_page, page);
175    let parsed: ApiResponse = serde_json::from_str(text).map_err(|e| {
176        AppError::with_source(ErrorKind::Parse, "failed to parse crates.io JSON", e)
177    })?;
178
179    let hits = parsed
180        .crates
181        .into_iter()
182        .map(|c| CrateSearchHit {
183            name: c.name,
184            description: c
185                .description
186                .filter(|s| !s.is_empty())
187                .unwrap_or_else(|| "No description available".to_string()),
188            downloads: c.downloads,
189            // `or_else` avoids eager clone of `max_version` when `newest_version` is Some.
190            version: c
191                .newest_version
192                .or_else(|| c.max_version.clone())
193                .unwrap_or_else(|| "unknown".to_string()),
194            documentation: c.documentation,
195            max_version: c.max_version,
196            max_stable_version: c.max_stable_version,
197            default_version: c.default_version,
198            recent_downloads: c.recent_downloads,
199            exact_match: c.exact_match,
200            yanked: c.yanked,
201            repository: c.repository,
202            homepage: c.homepage,
203        })
204        .collect();
205
206    Ok(SearchCratesData {
207        query: query.to_string(),
208        page,
209        per_page,
210        sort: sort.to_string(),
211        hits,
212        meta: SearchMeta {
213            total: parsed.meta.total,
214            next_page: parsed.meta.next_page,
215            prev_page: parsed.meta.prev_page,
216        },
217    })
218}
219
220/// Execute search-crates against crates.io (production origin).
221///
222/// # Errors
223///
224/// Propagates URL build, HTTP, UTF-8 decode, and JSON parse failures from
225/// [`search_crates_on_origin`].
226pub async fn search_crates(
227    http: &HttpClient,
228    query: &str,
229    per_page: u32,
230    sort: &str,
231    page: u32,
232) -> AppResult<SearchCratesData> {
233    search_crates_on_origin(
234        http,
235        &format!("https://{HOST_CRATES_IO}"),
236        query,
237        per_page,
238        sort,
239        page,
240    )
241    .await
242}
243
244/// Execute search-crates against a configurable origin (offline mocks).
245///
246/// # Errors
247///
248/// Returns [`ErrorKind::Internal`] when the origin URL is invalid.
249/// Propagates HTTP and parse errors from [`search_crates_at`].
250pub async fn search_crates_on_origin(
251    http: &HttpClient,
252    origin: &str,
253    query: &str,
254    per_page: u32,
255    sort: &str,
256    page: u32,
257) -> AppResult<SearchCratesData> {
258    let (per_page, page) = clamp_search_pagination(per_page, page);
259    let url = planned_url_on_host(origin, query, per_page, sort, page)?;
260    search_crates_at(http, &url, query, per_page, sort, page).await
261}
262
263/// Execute search against a pre-built URL (mock hosts in tests).
264///
265/// # Errors
266///
267/// Propagates HTTP transport errors from [`HttpClient::get_json`].
268/// Maps non-success HTTP statuses via [`AppError::from_http_status`].
269/// Returns [`ErrorKind::Parse`] when the body is not UTF-8 or not valid crates.io JSON.
270pub async fn search_crates_at(
271    http: &HttpClient,
272    url: &Url,
273    query: &str,
274    per_page: u32,
275    sort: &str,
276    page: u32,
277) -> AppResult<SearchCratesData> {
278    let resp = http.get_json(url).await?;
279    if resp.status.as_u16() == 404 {
280        return Err(AppError::from_http_status(404, "crates.io search"));
281    }
282    if !resp.status.is_success() {
283        return Err(AppError::from_http_status(
284            resp.status.as_u16(),
285            "crates.io search",
286        ));
287    }
288    if resp.content_type.is_some() && !content_type_looks_json(resp.content_type.as_deref()) {
289        tracing::warn!(
290            content_type = ?resp.content_type,
291            "unexpected Content-Type from crates.io"
292        );
293    }
294
295    let text = decode_utf8(&resp.body)?;
296    parse_search_body(&text, query, page, per_page, sort)
297}
298
299#[cfg(test)]
300mod tests {
301    use super::*;
302
303    #[test]
304    fn planned_url_clamps_and_encodes() {
305        let u = planned_url("serde json", 0, "alphabetical", 0).unwrap();
306        assert!(u.as_str().contains("per_page=1"));
307        assert!(u.as_str().contains("page=1"));
308        assert!(u.as_str().contains("sort=alphabetical"));
309        assert!(u.as_str().contains("q=serde"));
310        let u2 = planned_url("x", 500, "relevance", 3).unwrap();
311        assert!(u2.as_str().contains("per_page=100"));
312        assert!(u2.as_str().contains("page=3"));
313    }
314
315    #[test]
316    fn clamp_search_pagination_page_and_per_page() {
317        assert_eq!(clamp_search_pagination(0, 0), (1, 1));
318        assert_eq!(clamp_search_pagination(10, 0), (10, 1));
319        assert_eq!(clamp_search_pagination(500, 2), (100, 2));
320        assert_eq!(clamp_search_pagination(25, 3), (25, 3));
321    }
322
323    #[test]
324    fn parse_fixture_serde() {
325        let body = include_str!("../tests/fixtures/crates_io/search_serde.json");
326        let data = parse_search_body(body, "serde", 1, 10, "relevance").unwrap();
327        assert_eq!(data.hits.len(), 2);
328        assert_eq!(data.hits[0].name, "serde");
329        assert_eq!(data.hits[0].exact_match, Some(true));
330        assert_eq!(data.hits[0].version, "1.0.210");
331        assert_eq!(data.hits[1].description, "No description available");
332        assert_eq!(data.meta.total, 2);
333        assert_eq!(data.meta.next_page.as_deref(), Some("page=2"));
334    }
335
336    #[test]
337    fn parse_fixture_seek_meta() {
338        let body = include_str!("../tests/fixtures/crates_io/search_seek_meta.json");
339        let data = parse_search_body(body, "example", 1, 10, "downloads").unwrap();
340        assert_eq!(
341            data.meta.next_page.as_deref(),
342            Some("seek=ABC123&per_page=10")
343        );
344        assert_eq!(data.meta.prev_page.as_deref(), Some("page=1"));
345        assert_eq!(data.hits[0].version, "0.1.0");
346    }
347
348    #[test]
349    fn parse_invalid_json() {
350        let err = parse_search_body("{", "q", 1, 10, "relevance").unwrap_err();
351        assert_eq!(err.kind(), ErrorKind::Parse);
352    }
353
354    #[test]
355    fn parse_missing_versions_uses_unknown() {
356        let body = r#"{"crates":[{"name":"x","downloads":1}],"meta":{"total":1}}"#;
357        let data = parse_search_body(body, "x", 1, 10, "new").unwrap();
358        assert_eq!(data.hits[0].version, "unknown");
359        assert!(data.meta.next_page.is_none());
360    }
361
362    #[test]
363    fn planned_url_on_host_http_base() {
364        let u = planned_url_on_host("http://127.0.0.1:9", "q", 10, "new", 1).unwrap();
365        assert!(u.as_str().starts_with("http://127.0.0.1:9/api/v1/crates"));
366    }
367}