ic_query/nns/governance/
error.rs

1//! Module: nns::governance::error
2//!
3//! Responsibility: expose portable and native-wrapper Governance failures.
4//! Does not own: validation, transport execution, or process error presentation.
5//! Boundary: preserves transport details without coupling portable callers to a runtime.
6
7#[cfg(feature = "nns-host")]
8use crate::{nns::NnsGovernanceQueryError, runtime::RuntimeError};
9use thiserror::Error as ThisError;
10
11///
12/// NnsGovernanceError
13///
14/// Portable failure returned while collecting or assembling a Governance report.
15///
16
17#[derive(Debug, ThisError)]
18pub enum NnsGovernanceError {
19    /// The requested network is not the supported mainnet identity.
20    #[error("direct NNS Governance reports support only the mainnet `ic` network, not {network:?}")]
21    UnsupportedNetwork {
22        /// Rejected network identity.
23        network: String,
24    },
25
26    /// The selected transport cannot be executed by the source adapter.
27    #[error("invalid NNS Governance source selection: {reason}")]
28    InvalidSourceSelection {
29        /// Validation failure.
30        reason: String,
31    },
32
33    /// Returned provenance did not match the requested transport.
34    #[error("NNS Governance source evidence does not match the request: {reason}")]
35    SourceEvidenceMismatch {
36        /// Evidence mismatch.
37        reason: String,
38    },
39
40    /// Native IC agent setup failed.
41    #[error("failed to build IC agent for {endpoint}: {reason}")]
42    AgentBuild {
43        /// Endpoint used to build the agent.
44        endpoint: String,
45        /// Agent construction failure.
46        reason: String,
47    },
48
49    /// A native IC agent query failed.
50    #[error("NNS Governance agent call {method} failed: {reason}")]
51    AgentCall {
52        /// Governance method being queried.
53        method: &'static str,
54        /// Query failure.
55        reason: String,
56    },
57
58    /// A replicated inter-canister call could not be submitted.
59    #[error("NNS Governance inter-canister call {method} failed: {reason}")]
60    InterCanisterCall {
61        /// Governance method being called.
62        method: &'static str,
63        /// Cycle-balance or call-perform failure.
64        reason: String,
65    },
66
67    /// A replicated inter-canister call returned an IC reject.
68    #[error(
69        "NNS Governance inter-canister call {method} was rejected with code {reject_code}: {message}"
70    )]
71    InterCanisterCallRejected {
72        /// Governance method being called.
73        method: &'static str,
74        /// Raw IC reject code.
75        reject_code: u32,
76        /// Reject message returned by the IC.
77        message: String,
78    },
79
80    /// A Candid request could not be encoded.
81    #[error("failed to encode Candid {message}: {reason}")]
82    CandidEncode {
83        /// Candid request type.
84        message: &'static str,
85        /// Encoding failure.
86        reason: String,
87    },
88
89    /// A Candid response could not be decoded.
90    #[error("failed to decode Candid {message}: {reason}")]
91    CandidDecode {
92        /// Candid response type.
93        message: &'static str,
94        /// Decoding failure.
95        reason: String,
96    },
97
98    /// A response exceeded the library's explicit raw-response byte bound.
99    #[error("NNS Governance {method} response was {actual_bytes} bytes; limit is {maximum_bytes}")]
100    ResponseTooLarge {
101        /// Governance method being decoded.
102        method: &'static str,
103        /// Actual response size.
104        actual_bytes: usize,
105        /// Maximum accepted response size.
106        maximum_bytes: usize,
107    },
108
109    /// Governance returned its typed application-level error.
110    #[error("NNS Governance rejected the metrics query with code {error_type}: {message}")]
111    Governance {
112        /// Raw Governance error type.
113        error_type: i32,
114        /// Governance error message.
115        message: String,
116    },
117
118    /// Governance returned a non-finite metric that JSON cannot preserve.
119    #[error("NNS Governance metric {field} bucket {key} has non-finite value {value}")]
120    InvalidMetrics {
121        /// Native Governance metric field.
122        field: &'static str,
123        /// Raw metric bucket key.
124        key: u64,
125        /// Rejected non-finite bucket value.
126        value: f64,
127    },
128}
129
130#[cfg(feature = "nns-host")]
131impl From<NnsGovernanceQueryError> for NnsGovernanceError {
132    fn from(value: NnsGovernanceQueryError) -> Self {
133        match value {
134            NnsGovernanceQueryError::AgentBuild { endpoint, reason } => {
135                Self::AgentBuild { endpoint, reason }
136            }
137            NnsGovernanceQueryError::AgentCall { method, reason } => {
138                Self::AgentCall { method, reason }
139            }
140            NnsGovernanceQueryError::CandidEncode { message, reason } => {
141                Self::CandidEncode { message, reason }
142            }
143            NnsGovernanceQueryError::CandidDecode { message, reason } => {
144                Self::CandidDecode { message, reason }
145            }
146        }
147    }
148}
149
150///
151/// NnsGovernanceHostError
152///
153/// Failure returned by the synchronous native Governance convenience builders.
154///
155
156#[cfg(feature = "nns-host")]
157#[derive(Debug, ThisError)]
158pub enum NnsGovernanceHostError {
159    /// Portable collection or report validation failed.
160    #[error(transparent)]
161    Governance(#[from] NnsGovernanceError),
162
163    /// The synchronous host runtime could not execute the live query.
164    #[error(transparent)]
165    Runtime(#[from] RuntimeError),
166}
ic_query/nns/governance/error.rs

ic_query/nns/governance/
error.rs
