ic_query/ic/model/requests/
canisters.rs

1//! Module: ic::model::requests::canisters
2//!
3//! Responsibility: official Dashboard canister detail, count, and page request contracts.
4//! Does not own: network metrics, network resources, transport, or reports.
5//! Boundary: keeps shared filters and explicit bounded cursor-page intent together.
6
7use serde::Serialize;
8
9///
10/// IcCanisterRequest
11///
12/// Request accepted by the official Dashboard canister report builder.
13///
14
15#[derive(Clone, Debug, Eq, PartialEq)]
16pub struct IcCanisterRequest {
17    /// Dashboard API base endpoint.
18    pub source_endpoint: String,
19    /// Collection time as Unix seconds.
20    pub now_unix_secs: u64,
21    /// Canister principal to inspect.
22    pub canister_id: String,
23}
24
25impl IcCanisterRequest {
26    /// Construct a live Dashboard canister request.
27    #[must_use]
28    pub fn new(
29        source_endpoint: impl Into<String>,
30        now_unix_secs: u64,
31        canister_id: impl Into<String>,
32    ) -> Self {
33        Self {
34            source_endpoint: source_endpoint.into(),
35            now_unix_secs,
36            canister_id: canister_id.into(),
37        }
38    }
39}
40
41///
42/// IcCanisterFilters
43///
44/// Official Dashboard filters shared by canister count and page requests.
45///
46
47#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize)]
48pub struct IcCanisterFilters {
49    /// Select canisters according to whether the Dashboard records a name.
50    pub has_name: Option<bool>,
51    /// Select canisters assigned to this Subnet principal.
52    pub subnet_id: Option<String>,
53    /// Select canisters controlled by this principal.
54    pub controller_id: Option<String>,
55    /// Raw Dashboard language labels to include.
56    pub languages: Vec<String>,
57    /// Raw Dashboard canister classifications to include.
58    pub canister_types: Vec<String>,
59    /// Raw Dashboard text search, between two and one hundred characters.
60    pub query: Option<String>,
61}
62
63///
64/// IcCanisterCountRequest
65///
66/// Request for one bounded official Dashboard canister-count lookup.
67///
68
69#[derive(Clone, Debug, Eq, PartialEq)]
70pub struct IcCanisterCountRequest {
71    /// Dashboard API v4 base endpoint.
72    pub source_endpoint: String,
73    /// Collection time as Unix seconds.
74    pub now_unix_secs: u64,
75    /// Filters applied by the Dashboard.
76    pub filters: IcCanisterFilters,
77}
78
79impl IcCanisterCountRequest {
80    /// Construct a live Dashboard canister-count request without filters.
81    #[must_use]
82    pub fn new(source_endpoint: impl Into<String>, now_unix_secs: u64) -> Self {
83        Self {
84            source_endpoint: source_endpoint.into(),
85            now_unix_secs,
86            filters: IcCanisterFilters::default(),
87        }
88    }
89
90    /// Set the Dashboard filters used by this request.
91    #[must_use]
92    pub fn with_filters(mut self, filters: IcCanisterFilters) -> Self {
93        self.filters = filters;
94        self
95    }
96}
97
98///
99/// IcCanisterPageRequest
100///
101/// Request for one bounded official Dashboard canister page.
102///
103
104#[derive(Clone, Debug, Eq, PartialEq)]
105pub struct IcCanisterPageRequest {
106    /// Dashboard API v4 base endpoint.
107    pub source_endpoint: String,
108    /// Collection time as Unix seconds.
109    pub now_unix_secs: u64,
110    /// Filters applied by the Dashboard.
111    pub filters: IcCanisterFilters,
112    /// Maximum rows requested from the API.
113    pub limit: u16,
114    /// Exclusive forward cursor returned by an earlier page.
115    pub after: Option<String>,
116    /// Exclusive backward cursor returned by an earlier page.
117    pub before: Option<String>,
118}
119
120impl IcCanisterPageRequest {
121    /// Construct a live Dashboard page request with the default bounded limit.
122    #[must_use]
123    pub fn new(source_endpoint: impl Into<String>, now_unix_secs: u64) -> Self {
124        Self {
125            source_endpoint: source_endpoint.into(),
126            now_unix_secs,
127            filters: IcCanisterFilters::default(),
128            limit: crate::ic::DEFAULT_IC_CANISTER_PAGE_LIMIT,
129            after: None,
130            before: None,
131        }
132    }
133
134    /// Set the Dashboard filters used by this request.
135    #[must_use]
136    pub fn with_filters(mut self, filters: IcCanisterFilters) -> Self {
137        self.filters = filters;
138        self
139    }
140
141    /// Set the maximum number of returned rows.
142    #[must_use]
143    pub const fn with_limit(mut self, limit: u16) -> Self {
144        self.limit = limit;
145        self
146    }
147
148    /// Set an exclusive forward cursor.
149    #[must_use]
150    pub fn with_after(mut self, after: impl Into<String>) -> Self {
151        self.after = Some(after.into());
152        self
153    }
154
155    /// Set an exclusive backward cursor.
156    #[must_use]
157    pub fn with_before(mut self, before: impl Into<String>) -> Self {
158        self.before = Some(before.into());
159        self
160    }
161}
ic_query/ic/model/requests/canisters.rs

ic_query/ic/model/requests/
canisters.rs
