ic_query/ic/model/reports.rs
1//! Module: ic::model::reports
2//!
3//! Responsibility: public serialized Dashboard report, row, and provenance contracts.
4//! Does not own: requests, host source data, errors, transport, or projection.
5//! Boundary: preserves raw Dashboard values and explicit off-chain provenance.
6
7use super::requests::{IcCanisterFilters, IcDailyStatsQuery, IcMetricQuery};
8use serde::Serialize;
9
10///
11/// IcCanisterUpgrade
12///
13/// One proposal-linked canister upgrade recorded by the Dashboard API.
14///
15
16#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
17pub struct IcCanisterUpgrade {
18 /// Proposal execution time as raw Unix seconds.
19 pub executed_timestamp_seconds: u64,
20 /// Wasm module hash as raw lowercase hexadecimal text.
21 pub module_hash: String,
22 /// NNS proposal that installed this module.
23 pub proposal_id: u64,
24}
25
26///
27/// IcDashboardReportProvenance
28///
29/// Shared off-chain provenance and authority guarantees for Dashboard reports.
30///
31
32#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
33pub struct IcDashboardReportProvenance {
34 /// Report schema version.
35 pub schema_version: u32,
36 /// Network represented by the official Dashboard API.
37 pub network: String,
38 /// Authority that supplied the report fields.
39 pub authority: String,
40 /// Dashboard API base endpoint queried by the source.
41 pub source_endpoint: String,
42 /// Time this report was collected.
43 pub fetched_at: String,
44 /// Collector identity.
45 pub fetched_by: String,
46 /// Whether the API response is cryptographically certified IC state.
47 pub certified: bool,
48 /// Whether every returned value is guaranteed to describe one point in time.
49 pub point_in_time_guaranteed: bool,
50}
51
52///
53/// IcMetricObservation
54///
55/// One raw timestamp and value returned by the Dashboard Metrics API.
56///
57
58#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
59pub struct IcMetricObservation {
60 /// Observation timestamp as Unix seconds.
61 pub timestamp_unix_secs: u64,
62 /// Raw value string returned by the Dashboard.
63 pub value: String,
64}
65
66///
67/// IcMetricSeries
68///
69/// One named raw series in a Dashboard metric response.
70///
71
72#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
73pub struct IcMetricSeries {
74 /// Raw Dashboard response field that names this series.
75 pub name: String,
76 /// Observations in strictly increasing timestamp order.
77 pub observations: Vec<IcMetricObservation>,
78}
79
80///
81/// IcMetricReport
82///
83/// One bounded time-series response from the official Dashboard Metrics API.
84///
85
86#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
87pub struct IcMetricReport {
88 /// Shared Dashboard provenance, flattened in serialized report JSON.
89 #[serde(flatten)]
90 pub provenance: IcDashboardReportProvenance,
91 /// Metric and explicit time-series bounds, flattened in report JSON.
92 #[serde(flatten)]
93 pub query: IcMetricQuery,
94 /// Number of named series returned by the API.
95 pub returned_series_count: usize,
96 /// Total number of observations across all returned series.
97 pub returned_observation_count: usize,
98 /// Raw named time series in canonical series-name order.
99 pub series: Vec<IcMetricSeries>,
100}
101
102///
103/// IcDailyStatsRow
104///
105/// Selected raw daily network-activity values returned by the Dashboard API.
106///
107
108#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
109pub struct IcDailyStatsRow {
110 /// Raw UTC calendar day returned by the Dashboard.
111 pub day: String,
112 /// Observation timestamp as Unix seconds.
113 pub timestamp_unix_secs: u64,
114 /// Raw average query-transaction rate.
115 pub average_query_transactions_per_second: String,
116 /// Raw average update-transaction rate.
117 pub average_update_transactions_per_second: String,
118 /// Raw average total-transaction rate.
119 pub average_transactions_per_second: String,
120 /// Raw maximum query-transaction rate.
121 pub max_query_transactions_per_second: String,
122 /// Raw maximum update-transaction rate.
123 pub max_update_transactions_per_second: String,
124 /// Raw maximum total-transaction rate.
125 pub max_total_transactions_per_second: String,
126 /// Raw average block-production rate.
127 pub blocks_per_second_average: String,
128}
129
130///
131/// IcDailyStatsReport
132///
133/// One bounded daily network-activity response from the official Dashboard API.
134///
135
136#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
137pub struct IcDailyStatsReport {
138 /// Shared Dashboard provenance, flattened in serialized report JSON.
139 #[serde(flatten)]
140 pub provenance: IcDashboardReportProvenance,
141 /// Exact requested time bounds, flattened in report JSON.
142 #[serde(flatten)]
143 pub query: IcDailyStatsQuery,
144 /// Number of daily rows returned by the API.
145 pub returned_day_count: usize,
146 /// Rows in strictly increasing timestamp order.
147 pub rows: Vec<IcDailyStatsRow>,
148}
149
150///
151/// IcBoundaryNodeDataCenterRow
152///
153/// One raw data-center aggregate returned by the boundary-node API.
154///
155
156#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
157pub struct IcBoundaryNodeDataCenterRow {
158 /// Dashboard data-center identifier.
159 pub dc_id: String,
160 /// Raw data-center display name.
161 pub name: String,
162 /// Raw infrastructure-owner label.
163 pub owner: String,
164 /// Raw Dashboard region label.
165 pub region: String,
166 /// Raw decimal latitude.
167 pub latitude: String,
168 /// Raw decimal longitude.
169 pub longitude: String,
170 /// Raw decimal count of boundary nodes assigned to this data center.
171 pub total_nodes: String,
172}
173
174///
175/// IcBoundaryNodeDataCentersReport
176///
177/// One complete response from the official boundary-node data-center resource.
178///
179
180#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
181pub struct IcBoundaryNodeDataCentersReport {
182 /// Shared Dashboard provenance, flattened in serialized report JSON.
183 #[serde(flatten)]
184 pub provenance: IcDashboardReportProvenance,
185 /// Number of data-center rows returned by the API.
186 pub data_center_count: usize,
187 /// Sum of the raw per-data-center boundary-node counts.
188 pub total_node_count: u64,
189 /// Rows in canonical data-center-id order, including zero-node locations.
190 pub rows: Vec<IcBoundaryNodeDataCenterRow>,
191}
192
193///
194/// IcCanisterReport
195///
196/// One live canister metadata report from the official Dashboard API.
197///
198
199#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
200pub struct IcCanisterReport {
201 /// Shared Dashboard provenance, flattened in serialized report JSON.
202 #[serde(flatten)]
203 pub provenance: IcDashboardReportProvenance,
204 /// Canonical canister principal.
205 pub canister_id: String,
206 /// Dashboard database row identifier.
207 pub dashboard_id: u64,
208 /// Raw optional Dashboard canister classification.
209 pub canister_type: Option<String>,
210 /// Raw Dashboard canister name; an empty string means no name was recorded.
211 pub name: String,
212 /// Canonical Subnet principal recorded by the Dashboard.
213 pub subnet_id: String,
214 /// Canonically ordered controller principals recorded by the Dashboard.
215 pub controllers: Vec<String>,
216 /// Raw Dashboard language label; an empty string means no language was recorded.
217 pub language: String,
218 /// Raw current module hash; an empty string means no hash was recorded.
219 pub module_hash: String,
220 /// Raw Dashboard row update timestamp.
221 pub dashboard_updated_at: String,
222 /// Number of proposal-linked upgrades when history is available.
223 pub upgrade_count: Option<usize>,
224 /// Proposal-linked upgrade history, or `None` when the Dashboard returned `null`.
225 pub upgrades: Option<Vec<IcCanisterUpgrade>>,
226}
227
228///
229/// IcCanisterCountReport
230///
231/// One filtered canister count from the official Dashboard API.
232///
233
234#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
235pub struct IcCanisterCountReport {
236 /// Shared Dashboard provenance, flattened in serialized report JSON.
237 #[serde(flatten)]
238 pub provenance: IcDashboardReportProvenance,
239 /// Filters applied by the Dashboard.
240 pub filters: IcCanisterFilters,
241 /// Number of matching Dashboard canister records.
242 pub total: u64,
243}
244
245///
246/// IcCanisterPageController
247///
248/// One controller entry returned by the Dashboard canister collection API.
249///
250
251#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
252pub struct IcCanisterPageController {
253 /// Canonical controller principal.
254 pub principal_id: String,
255 /// Raw optional Dashboard metadata associated with the controller.
256 pub raw_metadata: Option<String>,
257}
258
259///
260/// IcCanisterPageRow
261///
262/// One discovery row from a bounded Dashboard canister page.
263///
264
265#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
266pub struct IcCanisterPageRow {
267 /// Canonical canister principal.
268 pub canister_id: String,
269 /// Dashboard database row identifier.
270 pub dashboard_id: u64,
271 /// Raw optional Dashboard canister classification.
272 pub canister_type: Option<String>,
273 /// Raw Dashboard canister name.
274 pub name: String,
275 /// Canonical Subnet principal recorded by the Dashboard.
276 pub subnet_id: String,
277 /// Canonically ordered controller entries recorded by the Dashboard.
278 pub controllers: Vec<IcCanisterPageController>,
279 /// Raw Dashboard language label.
280 pub language: String,
281 /// Raw current module hash.
282 pub module_hash: String,
283 /// Raw Dashboard row update timestamp.
284 pub dashboard_updated_at: String,
285}
286
287///
288/// IcCanisterPageReport
289///
290/// One explicitly bounded page from the official Dashboard canister collection.
291///
292
293#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
294pub struct IcCanisterPageReport {
295 /// Shared Dashboard provenance, flattened in serialized report JSON.
296 #[serde(flatten)]
297 pub provenance: IcDashboardReportProvenance,
298 /// Filters applied by the Dashboard.
299 pub filters: IcCanisterFilters,
300 /// Maximum rows requested from the API.
301 pub requested_limit: u16,
302 /// Number of rows returned in this report.
303 pub returned_count: usize,
304 /// Exclusive forward cursor supplied to this request.
305 pub after: Option<String>,
306 /// Exclusive backward cursor supplied to this request.
307 pub before: Option<String>,
308 /// Cursor for an explicit request for the preceding page.
309 pub previous_cursor: Option<String>,
310 /// Cursor for an explicit request for the following page.
311 pub next_cursor: Option<String>,
312 /// Canister discovery rows in Dashboard canister-id order.
313 pub rows: Vec<IcCanisterPageRow>,
314}