Skip to main content

docsrs_cli/crates_io/
types.rs

1//! Agent-facing wire types for `search-crates` and request-echo derivation.
2
3use serde::{Deserialize, Serialize};
4use url::Url;
5
6use super::urls::clamp_search_pagination;
7use crate::cli::SortKind;
8use crate::config::MAX_PER_PAGE;
9use crate::domain::SearchQuery;
10
11/// One hit from crates.io search.
12#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
13pub struct CrateSearchHit {
14    /// Crate name on crates.io.
15    pub name: String,
16    /// Short crate description (may be empty).
17    pub description: String,
18    /// Total download count.
19    pub downloads: u64,
20    /// Newest or default version string for display.
21    pub version: String,
22    /// Documentation URL when provided by crates.io.
23    #[serde(skip_serializing_if = "Option::is_none")]
24    pub documentation: Option<String>,
25    /// Highest published version when present.
26    #[serde(skip_serializing_if = "Option::is_none")]
27    pub max_version: Option<String>,
28    /// Highest stable version when present.
29    #[serde(skip_serializing_if = "Option::is_none")]
30    pub max_stable_version: Option<String>,
31    /// Default version selected by crates.io.
32    #[serde(skip_serializing_if = "Option::is_none")]
33    pub default_version: Option<String>,
34    /// Recent download count when present.
35    #[serde(skip_serializing_if = "Option::is_none")]
36    pub recent_downloads: Option<u64>,
37    /// Whether the query matched the crate name exactly.
38    #[serde(skip_serializing_if = "Option::is_none")]
39    pub exact_match: Option<bool>,
40    /// Whether the default version is yanked.
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub yanked: Option<bool>,
43    /// Source repository URL when present.
44    #[serde(skip_serializing_if = "Option::is_none")]
45    pub repository: Option<String>,
46    /// Project homepage URL when present.
47    #[serde(skip_serializing_if = "Option::is_none")]
48    pub homepage: Option<String>,
49}
50
51/// Pagination meta from crates.io (may contain `page=` or `seek=` tokens).
52#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
53pub struct SearchMeta {
54    /// Total hits reported by crates.io.
55    pub total: u64,
56    /// Opaque next-page token when more results exist.
57    #[serde(skip_serializing_if = "Option::is_none")]
58    pub next_page: Option<String>,
59    /// Opaque previous-page token when available.
60    #[serde(skip_serializing_if = "Option::is_none")]
61    pub prev_page: Option<String>,
62}
63
64/// Full search-crates data payload.
65#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
66pub struct SearchCratesData {
67    /// Original search query string.
68    pub query: String,
69    /// 1-based page number used for the request.
70    pub page: u32,
71    /// Page size used for the request.
72    pub per_page: u32,
73    /// Sort order API token.
74    pub sort: String,
75    /// Search hits on this page.
76    pub hits: Vec<CrateSearchHit>,
77    /// Pagination metadata from crates.io.
78    pub meta: SearchMeta,
79    /// True when the HTTP body was served from the local disk cache.
80    pub cache_hit: bool,
81    /// True when hits were reduced to fit `--max-output-bytes` (JSON path).
82    pub truncated: bool,
83}
84
85/// Echo fields for `search-crates` taken from the **effective request URL**
86/// (single source of truth after URL planning, including `--page-token`).
87#[derive(Debug, Clone, PartialEq, Eq)]
88pub struct SearchEcho {
89    /// Query string (`q=`).
90    pub query: String,
91    /// 1-based page.
92    pub page: u32,
93    /// Page size.
94    pub per_page: u32,
95    /// Sort token.
96    pub sort: String,
97}
98
99impl SearchEcho {
100    /// Build from CLI-side fallbacks before URL planning.
101    pub fn from_cli(query: &SearchQuery, page: u32, per_page: u32, sort: SortKind) -> Self {
102        let (per_page, page) = clamp_search_pagination(per_page, page);
103        Self {
104            query: query.as_str().to_string(),
105            page,
106            per_page,
107            sort: sort.as_api_str().to_string(),
108        }
109    }
110}
111
112/// Derive echo params from the planned URL query string.
113///
114/// Missing pairs fall back to `fallback` so pure `seek=` tokens and partial
115/// tokens still produce a coherent agent-facing payload.
116pub fn echo_params_from_url(url: &Url, fallback: &SearchEcho) -> SearchEcho {
117    let mut query = fallback.query.clone();
118    let mut page = fallback.page;
119    let mut per_page = fallback.per_page;
120    let mut sort = fallback.sort.clone();
121    for (k, v) in url.query_pairs() {
122        match k.as_ref() {
123            "q" => query = v.into_owned(),
124            "page" => {
125                if let Ok(n) = v.parse::<u32>() {
126                    page = n.max(1);
127                }
128            }
129            "per_page" => {
130                if let Ok(n) = v.parse::<u32>() {
131                    per_page = n.clamp(1, MAX_PER_PAGE);
132                }
133            }
134            "sort" => sort = v.into_owned(),
135            _ => {}
136        }
137    }
138    let (per_page, page) = clamp_search_pagination(per_page, page);
139    SearchEcho {
140        query,
141        page,
142        per_page,
143        sort,
144    }
145}