1use serde::{Deserialize, Serialize};
4use url::Url;
5
6use crate::cli::SortKind;
7use crate::config::{
8 MAX_CRATE_DESCRIPTION_CHARS, MAX_CRATE_NAME_CHARS, MAX_PER_PAGE, MAX_URL_FIELD_CHARS,
9 MAX_VERSION_CHARS,
10};
11use crate::domain::{AllowedOrigin, SearchQuery};
12use crate::error::{AppError, AppResult, ErrorKind};
13use crate::http::{HttpClient, decode_utf8, require_content_type_json};
14
15fn truncate_chars(s: &str, max_chars: usize) -> String {
20 if s.chars().count() <= max_chars {
21 return s.to_string();
22 }
23 s.chars().take(max_chars).collect()
24}
25
26fn cap_optional_field(value: Option<String>, max_chars: usize) -> Option<String> {
28 value.and_then(|s| {
29 let t = s.trim();
30 if t.is_empty() {
31 None
32 } else {
33 Some(truncate_chars(t, max_chars))
34 }
35 })
36}
37
38#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
40pub struct CrateSearchHit {
41 pub name: String,
43 pub description: String,
45 pub downloads: u64,
47 pub version: String,
49 #[serde(skip_serializing_if = "Option::is_none")]
51 pub documentation: Option<String>,
52 #[serde(skip_serializing_if = "Option::is_none")]
54 pub max_version: Option<String>,
55 #[serde(skip_serializing_if = "Option::is_none")]
57 pub max_stable_version: Option<String>,
58 #[serde(skip_serializing_if = "Option::is_none")]
60 pub default_version: Option<String>,
61 #[serde(skip_serializing_if = "Option::is_none")]
63 pub recent_downloads: Option<u64>,
64 #[serde(skip_serializing_if = "Option::is_none")]
66 pub exact_match: Option<bool>,
67 #[serde(skip_serializing_if = "Option::is_none")]
69 pub yanked: Option<bool>,
70 #[serde(skip_serializing_if = "Option::is_none")]
72 pub repository: Option<String>,
73 #[serde(skip_serializing_if = "Option::is_none")]
75 pub homepage: Option<String>,
76}
77
78#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
80pub struct SearchMeta {
81 pub total: u64,
83 #[serde(skip_serializing_if = "Option::is_none")]
85 pub next_page: Option<String>,
86 #[serde(skip_serializing_if = "Option::is_none")]
88 pub prev_page: Option<String>,
89}
90
91#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
93pub struct SearchCratesData {
94 pub query: String,
96 pub page: u32,
98 pub per_page: u32,
100 pub sort: String,
102 pub hits: Vec<CrateSearchHit>,
104 pub meta: SearchMeta,
106 pub cache_hit: bool,
108 pub truncated: bool,
110}
111
112#[derive(Debug, Clone, PartialEq, Eq)]
115pub struct SearchEcho {
116 pub query: String,
118 pub page: u32,
120 pub per_page: u32,
122 pub sort: String,
124}
125
126impl SearchEcho {
127 pub fn from_cli(query: &SearchQuery, page: u32, per_page: u32, sort: SortKind) -> Self {
129 let (per_page, page) = clamp_search_pagination(per_page, page);
130 Self {
131 query: query.as_str().to_string(),
132 page,
133 per_page,
134 sort: sort.as_api_str().to_string(),
135 }
136 }
137}
138
139pub fn echo_params_from_url(url: &Url, fallback: &SearchEcho) -> SearchEcho {
144 let mut query = fallback.query.clone();
145 let mut page = fallback.page;
146 let mut per_page = fallback.per_page;
147 let mut sort = fallback.sort.clone();
148 for (k, v) in url.query_pairs() {
149 match k.as_ref() {
150 "q" => query = v.into_owned(),
151 "page" => {
152 if let Ok(n) = v.parse::<u32>() {
153 page = n.max(1);
154 }
155 }
156 "per_page" => {
157 if let Ok(n) = v.parse::<u32>() {
158 per_page = n.clamp(1, MAX_PER_PAGE);
159 }
160 }
161 "sort" => sort = v.into_owned(),
162 _ => {}
163 }
164 }
165 let (per_page, page) = clamp_search_pagination(per_page, page);
166 SearchEcho {
167 query,
168 page,
169 per_page,
170 sort,
171 }
172}
173
174#[derive(Debug, Deserialize)]
175struct ApiResponse {
176 crates: Vec<ApiCrate>,
177 meta: ApiMeta,
178}
179
180#[derive(Debug, Deserialize)]
181struct ApiCrate {
182 name: String,
183 description: Option<String>,
184 downloads: u64,
185 newest_version: Option<String>,
186 max_version: Option<String>,
187 max_stable_version: Option<String>,
188 default_version: Option<String>,
189 documentation: Option<String>,
190 recent_downloads: Option<u64>,
191 exact_match: Option<bool>,
192 yanked: Option<bool>,
193 repository: Option<String>,
194 homepage: Option<String>,
195}
196
197#[derive(Debug, Deserialize)]
198struct ApiMeta {
199 total: u64,
200 next_page: Option<String>,
201 prev_page: Option<String>,
202}
203
204pub fn clamp_search_pagination(per_page: u32, page: u32) -> (u32, u32) {
209 (per_page.clamp(1, MAX_PER_PAGE), page.max(1))
210}
211
212pub fn validate_search_pagination(per_page: u32, page: u32) -> AppResult<(u32, u32)> {
219 if page < 1 {
220 return Err(AppError::new(
221 ErrorKind::InvalidInput,
222 "page must be >= 1 (got 0 or missing)",
223 ));
224 }
225 if !(1..=MAX_PER_PAGE).contains(&per_page) {
226 return Err(AppError::new(
227 ErrorKind::InvalidInput,
228 format!("per_page must be 1..={MAX_PER_PAGE} (got {per_page})"),
229 ));
230 }
231 Ok((per_page, page))
232}
233
234fn crates_api_base(origin: &AllowedOrigin) -> String {
236 format!("{}/api/v1/crates", origin.as_str().trim_end_matches('/'))
237}
238
239pub fn planned_url(query: &SearchQuery, per_page: u32, sort: SortKind, page: u32) -> AppResult<Url> {
245 planned_url_on_host(&AllowedOrigin::crates_io_default(), query, per_page, sort, page)
246}
247
248pub fn planned_url_on_host(
254 origin: &AllowedOrigin,
255 query: &SearchQuery,
256 per_page: u32,
257 sort: SortKind,
258 page: u32,
259) -> AppResult<Url> {
260 let (per_page, page) = clamp_search_pagination(per_page, page);
261 let base = crates_api_base(origin);
262 let mut url = Url::parse(&base)
263 .map_err(|e| AppError::with_source(ErrorKind::Internal, "invalid crates.io base URL", e))?;
264 {
265 let mut q = url.query_pairs_mut();
266 q.append_pair("q", query.as_str());
267 q.append_pair("per_page", &per_page.to_string());
268 q.append_pair("sort", sort.as_api_str());
269 q.append_pair("page", &page.to_string());
270 }
271 Ok(url)
272}
273
274pub fn planned_url_with_page_token(
286 origin: &AllowedOrigin,
287 query: &SearchQuery,
288 per_page: u32,
289 sort: SortKind,
290 page_token: &str,
291) -> AppResult<Url> {
292 let token = page_token.trim();
293 if token.is_empty() {
294 return Err(AppError::new(
295 ErrorKind::InvalidInput,
296 "page-token is empty",
297 ));
298 }
299 if token.chars().any(|c| c.is_control())
302 || token.len() > crate::config::MAX_URL_FIELD_CHARS
303 {
304 return Err(AppError::new(
305 ErrorKind::InvalidInput,
306 "page-token is invalid (control characters or exceeds max length)",
307 ));
308 }
309 if let Ok(page) = token.parse::<u32>() {
311 return planned_url_on_host(origin, query, per_page, sort, page);
312 }
313 let base = crates_api_base(origin);
314 let base_url = Url::parse(&base)
315 .map_err(|e| AppError::with_source(ErrorKind::Internal, "invalid crates.io base URL", e))?;
316
317 let qs = token.trim_start_matches('?');
318 if qs.contains('=') {
320 let mut url = base_url;
321 url.set_query(Some(qs));
322 return Ok(url);
323 }
324 let (per_page, _) = clamp_search_pagination(per_page, 1);
326 let mut url = base_url;
327 {
328 let mut q = url.query_pairs_mut();
329 q.append_pair("q", query.as_str());
330 q.append_pair("per_page", &per_page.to_string());
331 q.append_pair("sort", sort.as_api_str());
332 q.append_pair("seek", qs);
333 }
334 Ok(url)
335}
336pub fn parse_search_body(
342 text: &str,
343 query: &str,
344 page: u32,
345 per_page: u32,
346 sort: &str,
347 cache_hit: bool,
348) -> AppResult<SearchCratesData> {
349 let (per_page, page) = clamp_search_pagination(per_page, page);
350 let parsed: ApiResponse = serde_json::from_str(text).map_err(|e| {
351 AppError::with_source(ErrorKind::Parse, "failed to parse crates.io JSON", e)
352 })?;
353
354 let hits = parsed
355 .crates
356 .into_iter()
357 .map(|c| {
358 let version_raw = c
359 .newest_version
360 .or_else(|| c.max_version.clone())
361 .unwrap_or_else(|| "unknown".to_string());
362 CrateSearchHit {
363 name: truncate_chars(&c.name, MAX_CRATE_NAME_CHARS),
366 description: c
367 .description
368 .filter(|s| !s.is_empty())
369 .map(|s| truncate_chars(&s, MAX_CRATE_DESCRIPTION_CHARS))
370 .unwrap_or_else(|| "No description available".to_string()),
371 downloads: c.downloads,
372 version: truncate_chars(&version_raw, MAX_VERSION_CHARS),
373 documentation: cap_optional_field(c.documentation, MAX_URL_FIELD_CHARS),
374 max_version: cap_optional_field(c.max_version, MAX_VERSION_CHARS),
375 max_stable_version: cap_optional_field(c.max_stable_version, MAX_VERSION_CHARS),
376 default_version: cap_optional_field(c.default_version, MAX_VERSION_CHARS),
377 recent_downloads: c.recent_downloads,
378 exact_match: c.exact_match,
379 yanked: c.yanked,
380 repository: cap_optional_field(c.repository, MAX_URL_FIELD_CHARS),
381 homepage: cap_optional_field(c.homepage, MAX_URL_FIELD_CHARS),
382 }
383 })
384 .collect();
385
386 Ok(SearchCratesData {
387 query: query.to_string(),
388 page,
389 per_page,
390 sort: sort.to_string(),
391 hits,
392 meta: SearchMeta {
393 total: parsed.meta.total,
394 next_page: cap_optional_field(parsed.meta.next_page, MAX_URL_FIELD_CHARS),
395 prev_page: cap_optional_field(parsed.meta.prev_page, MAX_URL_FIELD_CHARS),
396 },
397 cache_hit,
398 truncated: false,
399 })
400}
401
402pub async fn search_crates(
409 http: &HttpClient,
410 query: &SearchQuery,
411 per_page: u32,
412 sort: SortKind,
413 page: u32,
414) -> AppResult<SearchCratesData> {
415 search_crates_on_origin(
416 http,
417 &AllowedOrigin::crates_io_default(),
418 query,
419 per_page,
420 sort,
421 page,
422 )
423 .await
424}
425
426pub async fn search_crates_on_origin(
433 http: &HttpClient,
434 origin: &AllowedOrigin,
435 query: &SearchQuery,
436 per_page: u32,
437 sort: SortKind,
438 page: u32,
439) -> AppResult<SearchCratesData> {
440 let (per_page, page) = clamp_search_pagination(per_page, page);
441 let url = planned_url_on_host(origin, query, per_page, sort, page)?;
442 search_crates_at(http, &url, query, per_page, sort, page).await
443}
444
445pub async fn search_crates_at(
456 http: &HttpClient,
457 url: &Url,
458 query: &SearchQuery,
459 per_page: u32,
460 sort: SortKind,
461 page: u32,
462) -> AppResult<SearchCratesData> {
463 let fallback = SearchEcho::from_cli(query, page, per_page, sort);
464 let echo = echo_params_from_url(url, &fallback);
465 let resp = http.get_json(url).await?;
466 if resp.status.as_u16() == 404 {
467 return Err(AppError::from_http_status(404, "crates.io search"));
468 }
469 if resp.status.as_u16() == 400 {
470 return Err(AppError::from_http_status(
472 400,
473 "crates.io search (page-token or query rejected by remote)",
474 ));
475 }
476 if !resp.status.is_success() {
477 return Err(AppError::from_http_status(
478 resp.status.as_u16(),
479 "crates.io search",
480 ));
481 }
482 require_content_type_json(resp.content_type.as_deref())?;
484
485 let text = decode_utf8(&resp.body)?;
486 parse_search_body(
487 &text,
488 &echo.query,
489 echo.page,
490 echo.per_page,
491 &echo.sort,
492 resp.cache_hit,
493 )
494}
495
496#[cfg(test)]
497mod tests {
498 use super::*;
499 use crate::cli::SortKind;
500 use crate::domain::SearchQuery;
501
502 fn q(s: &str) -> SearchQuery {
503 SearchQuery::parse(s, true).unwrap()
504 }
505
506 #[test]
507 fn planned_url_clamps_and_encodes() {
508 let u = planned_url(&q("serde json"), 0, SortKind::Alphabetical, 0).unwrap();
509 assert!(u.as_str().contains("per_page=1"));
510 assert!(u.as_str().contains("page=1"));
511 assert!(u.as_str().contains("sort=alphabetical"));
512 assert!(u.as_str().contains("q=serde"));
513 let u2 = planned_url(&q("x"), 500, SortKind::Relevance, 3).unwrap();
514 assert!(u2.as_str().contains("per_page=100"));
515 assert!(u2.as_str().contains("page=3"));
516 }
517
518 #[test]
519 fn clamp_search_pagination_page_and_per_page() {
520 assert_eq!(clamp_search_pagination(0, 0), (1, 1));
521 assert_eq!(clamp_search_pagination(10, 0), (10, 1));
522 assert_eq!(clamp_search_pagination(500, 2), (100, 2));
523 assert_eq!(clamp_search_pagination(25, 3), (25, 3));
524 }
525
526 #[test]
527 fn validate_search_pagination_rejects_invalid() {
528 assert!(validate_search_pagination(10, 0).is_err());
529 assert!(validate_search_pagination(0, 1).is_err());
530 assert!(validate_search_pagination(200, 1).is_err());
531 assert_eq!(validate_search_pagination(25, 3).unwrap(), (25, 3));
532 assert_eq!(validate_search_pagination(100, 1).unwrap(), (100, 1));
533 }
534
535 #[test]
536 fn parse_fixture_serde() {
537 let body = include_str!("../tests/fixtures/crates_io/search_serde.json");
538 let data = parse_search_body(body, "serde", 1, 10, "relevance", false).unwrap();
539 assert_eq!(data.hits.len(), 2);
540 assert_eq!(data.hits[0].name, "serde");
541 assert_eq!(data.hits[0].exact_match, Some(true));
542 assert_eq!(data.hits[0].version, "1.0.210");
543 assert_eq!(data.hits[1].description, "No description available");
544 assert_eq!(data.meta.total, 2);
545 assert_eq!(data.meta.next_page.as_deref(), Some("page=2"));
546 }
547
548 #[test]
549 fn parse_fixture_seek_meta() {
550 let body = include_str!("../tests/fixtures/crates_io/search_seek_meta.json");
551 let data = parse_search_body(body, "example", 1, 10, "downloads", false).unwrap();
552 assert_eq!(
553 data.meta.next_page.as_deref(),
554 Some("seek=ABC123&per_page=10")
555 );
556 assert_eq!(data.meta.prev_page.as_deref(), Some("page=1"));
557 assert_eq!(data.hits[0].version, "0.1.0");
558 }
559
560 #[test]
561 fn parse_invalid_json() {
562 let err = parse_search_body("{", "q", 1, 10, "relevance", false).unwrap_err();
563 assert_eq!(err.kind(), ErrorKind::Parse);
564 }
565
566 #[test]
567 fn parse_missing_versions_uses_unknown() {
568 let body = r#"{"crates":[{"name":"x","downloads":1}],"meta":{"total":1}}"#;
569 let data = parse_search_body(body, "x", 1, 10, "new", false).unwrap();
570 assert_eq!(data.hits[0].version, "unknown");
571 assert!(data.meta.next_page.is_none());
572 }
573
574 #[test]
575 fn planned_url_on_host_http_base() {
576 let origin = AllowedOrigin::parse_with("http://127.0.0.1:9", true).unwrap();
577 let u = planned_url_on_host(&origin, &q("q"), 10, SortKind::New, 1).unwrap();
578 assert!(u.as_str().starts_with("http://127.0.0.1:9/api/v1/crates"));
579 }
580
581 #[test]
582 fn echo_params_from_page_token_url() {
583 let fallback = SearchEcho::from_cli(&q(""), 1, 10, SortKind::Relevance);
584 let origin = AllowedOrigin::crates_io_default();
585 let url = planned_url_with_page_token(
586 &origin,
587 &q(""),
588 10,
589 SortKind::Relevance,
590 "?q=serde&per_page=2&sort=relevance&page=2",
591 )
592 .unwrap();
593 let echo = echo_params_from_url(&url, &fallback);
594 assert_eq!(echo.query, "serde");
595 assert_eq!(echo.page, 2);
596 assert_eq!(echo.per_page, 2);
597 assert_eq!(echo.sort, "relevance");
598 }
599
600 #[test]
601 fn echo_params_fallback_when_pairs_missing() {
602 let fallback = SearchEcho::from_cli(&q("local"), 3, 25, SortKind::Downloads);
603 let url = Url::parse("https://crates.io/api/v1/crates?seek=ABC").unwrap();
604 let echo = echo_params_from_url(&url, &fallback);
605 assert_eq!(echo.query, "local");
606 assert_eq!(echo.page, 3);
607 assert_eq!(echo.per_page, 25);
608 assert_eq!(echo.sort, "downloads");
609 }
610
611 #[test]
612 fn parse_caps_oversized_api_strings() {
613 let long_name = "a".repeat(MAX_CRATE_NAME_CHARS + 50);
614 let long_desc = "d".repeat(MAX_CRATE_DESCRIPTION_CHARS + 100);
615 let long_url = format!("https://example.com/{}", "p".repeat(MAX_URL_FIELD_CHARS));
616 let long_token = "t".repeat(MAX_URL_FIELD_CHARS + 10);
617 let body = format!(
618 r#"{{"crates":[{{"name":"{long_name}","description":"{long_desc}","downloads":1,"newest_version":"1.0.0","documentation":"{long_url}","repository":"{long_url}","homepage":"{long_url}"}}],"meta":{{"total":1,"next_page":"{long_token}","prev_page":"{long_token}"}}}}"#
619 );
620 let data = parse_search_body(&body, "q", 1, 10, "relevance", false).unwrap();
621 assert_eq!(data.hits[0].name.chars().count(), MAX_CRATE_NAME_CHARS);
622 assert_eq!(
623 data.hits[0].description.chars().count(),
624 MAX_CRATE_DESCRIPTION_CHARS
625 );
626 assert_eq!(
627 data.hits[0]
628 .documentation
629 .as_ref()
630 .map(|s| s.chars().count()),
631 Some(MAX_URL_FIELD_CHARS)
632 );
633 assert_eq!(
634 data.meta.next_page.as_ref().map(|s| s.chars().count()),
635 Some(MAX_URL_FIELD_CHARS)
636 );
637 assert_eq!(
638 data.meta.prev_page.as_ref().map(|s| s.chars().count()),
639 Some(MAX_URL_FIELD_CHARS)
640 );
641 }
642
643 #[test]
644 fn truncate_chars_preserves_short_and_utf8() {
645 assert_eq!(truncate_chars("abc", 10), "abc");
646 assert_eq!(truncate_chars("abcdef", 3), "abc");
647 assert_eq!(truncate_chars("日本語abc", 2), "日本");
649 }
650}