Skip to main content

ic_query/cloud_engine/
mod.rs

1//! CloudEngine control-plane and official Dashboard report models, adapters.
2
3#[cfg(feature = "cloud-engine-host")]
4mod build;
5#[cfg(all(feature = "cloud-engine-host", feature = "subnet-catalog-host"))]
6mod list;
7mod model;
8mod node;
9mod provider;
10#[cfg(feature = "cloud-engine-host")]
11mod source;
12#[cfg(feature = "cloud-engine-host")]
13mod wire;
14
15#[cfg(feature = "cloud-engine-host")]
16use thiserror::Error as ThisError;
17
18#[cfg(feature = "cloud-engine-host")]
19pub use build::{
20    build_cloud_engine_operator_report_with_source, build_cloud_engine_prices_report_with_source,
21};
22#[cfg(all(feature = "cloud-engine-host", feature = "subnet-catalog-host"))]
23pub use list::build_cloud_engine_list_report_with_sources_and_progress;
24#[cfg(all(feature = "cloud-engine-host", feature = "subnet-catalog-host"))]
25pub use model::{CloudEngineListReport, CloudEngineListRow};
26pub use model::{
27    CloudEngineNodeType, CloudEngineOperatorReport, CloudEnginePriceRow, CloudEnginePricesReport,
28    CloudEngineReportContext,
29};
30#[cfg(feature = "cloud-engine-host")]
31pub use model::{
32    CloudEngineOperatorBindingSourceData, CloudEngineOperatorSourceData,
33    CloudEnginePricesSourceData,
34};
35pub use node::{
36    CLOUD_ENGINE_NODE_INCLUDED_STATUSES, CLOUD_ENGINE_NODE_REWARD_TYPE, CloudEngineNodeInfoReport,
37    CloudEngineNodeInfoRequest, CloudEngineNodeListReport, CloudEngineNodeListRequest,
38    CloudEngineNodeRow, MAX_CLOUD_ENGINE_NODE_ROWS,
39};
40#[cfg(feature = "dashboard-host")]
41pub use node::{
42    CloudEngineNodeInfoSourceData, CloudEngineNodeListSourceData, CloudEngineNodeSource,
43    build_cloud_engine_node_info_report_with_source,
44    build_cloud_engine_node_list_report_with_source,
45};
46pub use provider::{
47    CloudEngineProviderInfoReport, CloudEngineProviderInfoRequest, CloudEngineProviderListReport,
48    CloudEngineProviderListRequest, CloudEngineProviderLocation, CloudEngineProviderRow,
49    MAX_CLOUD_ENGINE_PROVIDER_LOCATIONS, MAX_CLOUD_ENGINE_PROVIDER_SOURCE_ROWS,
50};
51#[cfg(feature = "dashboard-host")]
52pub use provider::{
53    CloudEngineProviderInfoSourceData, CloudEngineProviderListSourceData,
54    CloudEngineProviderSource, build_cloud_engine_provider_info_report_with_source,
55    build_cloud_engine_provider_list_report_with_source,
56};
57#[cfg(feature = "cloud-engine-host")]
58pub use source::{CloudEngineOperatorBindingSource, CloudEngineSource, LiveCloudEngineSource};
59
60/// Mainnet CloudEngine control-plane registry canister principal.
61pub const MAINNET_CLOUD_ENGINE_CANISTER_ID: &str = "q6cfj-fyaaa-aaaar-qb77q-cai";
62
63/// Default replica endpoint used for live CloudEngine control-plane queries.
64pub const DEFAULT_CLOUD_ENGINE_SOURCE_ENDPOINT: &str = "https://icp-api.io";
65
66/// Default official Dashboard endpoint for CloudEngine provider and Type4 node reports.
67pub const DEFAULT_CLOUD_ENGINE_DASHBOARD_SOURCE_ENDPOINT: &str =
68    "https://ic-api.internetcomputer.org/api/v3";
69
70/// Maximum marketplace rows accepted from one live response.
71pub const MAX_CLOUD_ENGINE_PRICE_ROWS: usize = 1_000;
72
73/// Maximum Registry CloudEngine Subnets followed by one list invocation.
74pub const MAX_CLOUD_ENGINE_LIST_ROWS: usize = 100;
75
76/// Maximum claimed domains accepted from one engine operator.
77pub const MAX_CLOUD_ENGINE_DOMAINS: usize = 100;
78
79/// Maximum decimal digits accepted for one marketplace cycle amount.
80pub const MAX_CLOUD_ENGINE_CYCLE_DECIMAL_DIGITS: usize = 256;
81
82#[cfg(feature = "cloud-engine-host")]
83const CLOUD_ENGINE_REPORT_SCHEMA_VERSION: u32 = 1;
84#[cfg(feature = "cloud-engine-host")]
85const CLOUD_ENGINE_AUTHORITY: &str = "cloud_engine_control_plane_canister";
86
87///
88/// CloudEngineHostError
89///
90/// Failure while collecting or validating one live CloudEngine report.
91///
92
93#[cfg(feature = "cloud-engine-host")]
94#[derive(Debug, ThisError)]
95pub enum CloudEngineHostError {
96    /// The requested network is not the supported mainnet identity.
97    #[error(
98        "`icq cloud-engine` supports only the mainnet `ic` network\n\nThese reports query the mainnet CloudEngine control-plane canister.\n\nTry:\n  icq --network ic cloud-engine prices"
99    )]
100    UnsupportedNetwork {
101        /// Rejected network identity.
102        network: String,
103    },
104
105    /// A requested principal is invalid.
106    #[error("invalid {field}: {reason}")]
107    InvalidPrincipal {
108        /// Principal field being parsed.
109        field: &'static str,
110        /// Principal parsing failure.
111        reason: String,
112    },
113
114    /// The IC agent could not be constructed for the requested endpoint.
115    #[error("failed to build IC agent for {endpoint}: {reason}")]
116    AgentBuild {
117        /// Endpoint used to build the agent.
118        endpoint: String,
119        /// Agent construction failure.
120        reason: String,
121    },
122
123    /// The built-in CloudEngine control-plane principal could not be parsed.
124    #[error("invalid built-in CloudEngine canister principal: {reason}")]
125    CanisterId {
126        /// Principal parsing failure.
127        reason: String,
128    },
129
130    /// A CloudEngine control-plane query failed.
131    #[error("CloudEngine agent call {method} failed: {reason}")]
132    AgentCall {
133        /// Canister method being queried.
134        method: &'static str,
135        /// Agent call failure.
136        reason: String,
137    },
138
139    /// A CloudEngine query argument could not be Candid encoded.
140    #[error("failed to encode Candid {message}: {reason}")]
141    CandidEncode {
142        /// Candid request type.
143        message: &'static str,
144        /// Encoding failure.
145        reason: String,
146    },
147
148    /// A CloudEngine response could not be Candid decoded.
149    #[error("failed to decode Candid {message}: {reason}")]
150    CandidDecode {
151        /// Candid response type.
152        message: &'static str,
153        /// Decoding failure.
154        reason: String,
155    },
156
157    /// A custom CloudEngine source returned inconsistent or excessive data.
158    #[error("invalid CloudEngine source data: {reason}")]
159    InvalidSourceData {
160        /// Deterministic source-contract failure.
161        reason: String,
162    },
163
164    /// The Registry-backed Subnet Catalog could not supply the list inventory.
165    #[cfg(feature = "subnet-catalog-host")]
166    #[error(transparent)]
167    SubnetCatalog(#[from] crate::subnet_catalog::SubnetCatalogHostError),
168}
169
170#[cfg(feature = "cloud-engine-host")]
171fn enforce_mainnet_network(network: &str) -> Result<(), CloudEngineHostError> {
172    crate::network::enforce_mainnet_network_with(network, |network| {
173        CloudEngineHostError::UnsupportedNetwork { network }
174    })
175}
176
177#[cfg(all(test, feature = "cloud-engine-host"))]
178mod tests;