Skip to main content

docsrs_cli/docs_rs/
types.rs

1//! Wire payloads for docs.rs operations (JSON data contracts).
2
3use serde::{Deserialize, Serialize};
4
5/// Crate overview (rustdoc crate docblock, not git README).
6#[derive(Debug, Clone, Serialize, Deserialize)]
7pub struct ReadmeData {
8    /// Requested crate name.
9    pub crate_name: String,
10    /// Requested version token.
11    pub version: String,
12    /// Version resolved by docs.rs redirects when known.
13    #[serde(skip_serializing_if = "Option::is_none")]
14    pub resolved_version: Option<String>,
15    /// Markdown extracted from the crate overview.
16    pub markdown: String,
17    /// True when the overview body is empty.
18    pub empty: bool,
19    /// True when output was truncated by `max_output_bytes`.
20    pub truncated: bool,
21    /// Final source URL of the HTML page.
22    pub source_url: String,
23    /// True when the HTTP body was served from the local disk cache.
24    pub cache_hit: bool,
25}
26
27/// Typed item documentation payload.
28#[derive(Debug, Clone, Serialize, Deserialize)]
29pub struct GetItemData {
30    /// Requested crate name.
31    pub crate_name: String,
32    /// Normalized item kind string.
33    pub item_type: String,
34    /// Requested item path.
35    pub item_path: String,
36    /// Last path segment (leaf name) for agent convenience.
37    pub item_name: String,
38    /// Requested version token.
39    pub version: String,
40    /// Version resolved by docs.rs redirects when known.
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub resolved_version: Option<String>,
43    /// Markdown extracted from the item page.
44    pub markdown: String,
45    /// True when the item body is empty.
46    pub empty: bool,
47    /// True when output was truncated by `max_output_bytes`.
48    pub truncated: bool,
49    /// Final source URL of the HTML page.
50    pub source_url: String,
51    /// Page title when available.
52    pub title: String,
53    /// True when the HTTP body was served from the local disk cache.
54    pub cache_hit: bool,
55    /// How markdown was scoped for associated methods. Success path is `method` only (1.2.0+ fail-closed; missing anchors are errors).
56    #[serde(skip_serializing_if = "Option::is_none")]
57    pub extraction: Option<String>,
58    /// Canonical rustdoc path when a reexport/root path was resolved via all.html.
59    #[serde(skip_serializing_if = "Option::is_none")]
60    pub resolved_item_path: Option<String>,
61}
62
63/// Single all.html hit.
64#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
65pub struct SearchInCrateHit {
66    /// Symbol or path name from all.html.
67    pub name: String,
68    /// Item kind string (`struct`, `fn`, …).
69    pub kind: String,
70    /// Absolute URL of the item documentation page.
71    pub url: String,
72    /// Match quality score (0 = best). Omitted when query is empty.
73    #[serde(skip_serializing_if = "Option::is_none")]
74    pub score: Option<u8>,
75}
76
77/// search-in-crate result set (`truncated` is true when hits were cut by `--limit`
78/// and/or by `--max-output-bytes` output budget).
79#[derive(Debug, Clone, Serialize, Deserialize)]
80pub struct SearchInCrateData {
81    /// Requested crate name.
82    pub crate_name: String,
83    /// Text filter applied to hits.
84    pub query: String,
85    /// Requested version token.
86    pub version: String,
87    /// Echo of the applied item-type filter when set.
88    #[serde(skip_serializing_if = "Option::is_none")]
89    pub item_type: Option<String>,
90    /// Match mode applied (`exact` | `prefix` | `substring`).
91    pub match_mode: String,
92    /// Total classified hits before the limit.
93    pub total: usize,
94    /// Number of hits actually emitted.
95    pub emitted: usize,
96    /// Emitted hits.
97    pub hits: Vec<SearchInCrateHit>,
98    /// True when the hit list was cut by `--limit` (`total > emitted`).
99    pub truncated: bool,
100    /// Final source URL of the all.html page.
101    pub source_url: String,
102    /// True when the HTTP body was served from the local disk cache.
103    pub cache_hit: bool,
104}
105