ic_query/nns/proposals/report/
error.rs

1//! Module: nns::proposals::report::error
2//!
3//! Responsibility: expose portable and native-wrapper NNS proposal failures.
4//! Does not own: transport execution, cache mechanics, or process presentation.
5//! Boundary: keeps canister/custom callers independent of native host dependencies.
6
7use crate::nns::governance::{NnsGovernanceError, NnsGovernanceSourceProvenance};
8#[cfg(feature = "nns-host")]
9use crate::{
10    HostCacheError, nns::governance::NnsGovernanceAttemptReadError, runtime::RuntimeError,
11};
12#[cfg(feature = "nns-host")]
13use std::path::PathBuf;
14use thiserror::Error as ThisError;
15
16///
17/// NnsProposalError
18///
19/// Portable failure returned while collecting or assembling proposal reports.
20///
21
22#[derive(Debug, ThisError)]
23pub enum NnsProposalError {
24    /// Shared Governance request, transport, or provenance validation failed.
25    #[error(transparent)]
26    Governance(#[from] NnsGovernanceError),
27
28    /// The requested page size is outside the bounded proposal contract.
29    #[error("invalid NNS proposal page limit {limit}; expected 1..={maximum}")]
30    InvalidLimit {
31        /// Requested live-page row limit.
32        limit: u32,
33        /// Largest limit supported by Governance.
34        maximum: u32,
35    },
36
37    /// Governance returned more proposal rows than requested.
38    #[error("NNS proposal page returned {actual} rows; requested at most {requested}")]
39    PageTooLarge {
40        /// Number of rows returned by the source.
41        actual: usize,
42        /// Row ceiling supplied to the source.
43        requested: u32,
44    },
45
46    /// A proposal page row did not include its required identifier.
47    #[error("NNS proposal list page returned a row without a proposal id")]
48    MissingProposalIdInPage,
49
50    /// A proposal page used the reserved zero identifier.
51    #[error("NNS proposal list page returned proposal id zero")]
52    InvalidProposalIdInPage,
53
54    /// A proposal page repeated an identifier.
55    #[error("NNS proposal page returned duplicate proposal id {proposal_id}")]
56    DuplicateProposalId {
57        /// Identifier repeated within the returned page.
58        proposal_id: u64,
59    },
60
61    /// A proposal did not satisfy the exclusive page cursor.
62    #[error(
63        "NNS proposal page returned id {proposal_id}; expected every id below {before_proposal_id}"
64    )]
65    ProposalCursorMismatch {
66        /// Returned proposal that violates the exclusive cursor.
67        proposal_id: u64,
68        /// Requested exclusive upper proposal-id bound.
69        before_proposal_id: u64,
70    },
71
72    /// Governance did not return the requested proposal.
73    #[error("NNS proposal {proposal_id} was not found")]
74    ProposalNotFound {
75        /// Exact identifier requested by the caller.
76        proposal_id: u64,
77    },
78
79    /// Governance returned a different proposal than requested.
80    #[error("NNS proposal detail returned id {actual:?}; expected {expected}")]
81    ProposalIdMismatch {
82        /// Exact identifier requested by the caller.
83        expected: u64,
84        /// Identifier supplied in the returned row, if present.
85        actual: Option<u64>,
86    },
87
88    /// A resumable collection was configured without any page capacity.
89    #[error("invalid NNS proposal collection page limit 0; expected at least one page")]
90    InvalidCollectionMaxPages,
91
92    /// Serialized or caller-modified resumable collection state is inconsistent.
93    #[error("invalid NNS proposal collection state: {reason}")]
94    InvalidCollectionState {
95        /// Deterministic state invariant that failed.
96        reason: String,
97    },
98
99    /// A continuation request changed an identity fixed when collection started.
100    #[error(
101        "NNS proposal collection request changed {field}: received {actual}, expected {expected}"
102    )]
103    CollectionRequestMismatch {
104        /// Fixed request field that changed.
105        field: &'static str,
106        /// Value retained by the collection state.
107        expected: String,
108        /// Value supplied by the continuation request.
109        actual: String,
110    },
111
112    /// A caller attempted to advance a collection that already exhausted the API.
113    #[error("NNS proposal collection is already complete after {pages_fetched} pages")]
114    CollectionComplete {
115        /// Pages admitted before API exhaustion.
116        pages_fetched: u32,
117    },
118
119    /// A caller attempted to advance a collection after consuming its page budget.
120    #[error(
121        "NNS proposal collection reached its {max_pages}-page limit after {pages_fetched} pages"
122    )]
123    CollectionPageLimitReached {
124        /// Pages admitted before the stopped advance.
125        pages_fetched: u32,
126        /// Configured cumulative page ceiling.
127        max_pages: u32,
128    },
129
130    /// A later collection page was returned by a different collector.
131    #[error("NNS proposal collection source changed: received {actual:?}, expected {expected:?}")]
132    CollectionSourceChanged {
133        /// Concrete source retained from the first admitted page.
134        expected: NnsGovernanceSourceProvenance,
135        /// Concrete source returned with the candidate page.
136        actual: NnsGovernanceSourceProvenance,
137    },
138
139    /// Cumulative page or row accounting exceeded its integer representation.
140    #[error("NNS proposal collection accounting overflow")]
141    CollectionAccountingOverflow,
142}
143
144///
145/// NnsProposalHostError
146///
147/// Native wrapper failure for proposal live calls, caches, and refreshes.
148///
149
150#[cfg(feature = "nns-host")]
151#[derive(Debug, ThisError)]
152pub enum NnsProposalHostError {
153    /// Local activity input or aggregation failed.
154    #[error(transparent)]
155    Activity(#[from] super::NnsProposalActivityError),
156
157    /// Portable proposal collection or validation failed.
158    #[error(transparent)]
159    Proposal(#[from] NnsProposalError),
160
161    /// Confined cache IO or refresh locking failed.
162    #[error(transparent)]
163    Cache(#[from] HostCacheError),
164
165    /// A snapshot's stored identity disagrees with the requested collection.
166    #[error(
167        "cached NNS proposal snapshot identity mismatch at {}: {field} is {actual}, expected {expected}",
168        path.display()
169    )]
170    CacheIdentityMismatch {
171        /// Snapshot file with inconsistent identity.
172        path: PathBuf,
173        /// Identity field that failed validation.
174        field: &'static str,
175        /// Value required by the requested collection.
176        expected: String,
177        /// Value found in the snapshot.
178        actual: String,
179    },
180
181    /// Collection stopped before API exhaustion and did not replace the snapshot.
182    #[error(
183        "NNS proposal refresh did not publish a complete snapshot after {pages_fetched} pages and {rows_fetched} rows: {reason}"
184    )]
185    IncompleteRefresh {
186        /// Number of pages admitted before collection stopped.
187        pages_fetched: u32,
188        /// Number of rows admitted before collection stopped.
189        rows_fetched: usize,
190        /// Failure to establish a complete sequential collection.
191        reason: String,
192    },
193
194    /// A cache-only read could not find the required complete snapshot.
195    #[error("NNS proposals cache is missing at {}\n\nRun `icq nns proposal refresh` to fetch a complete snapshot.", path.display())]
196    MissingProposalCache {
197        /// Expected complete snapshot path.
198        path: PathBuf,
199    },
200
201    /// A retained refresh-attempt sidecar failed its current contract.
202    #[error("invalid NNS proposal refresh attempt at {}: {reason}", path.display())]
203    InvalidRefreshAttempt {
204        /// Refresh-attempt sidecar that failed validation.
205        path: PathBuf,
206        /// Sidecar validation diagnostic.
207        reason: String,
208    },
209
210    /// A retained proposal snapshot failed its current contract.
211    #[error("invalid NNS proposal cache at {}: {reason}", path.display())]
212    InvalidCache {
213        /// Snapshot file that failed validation.
214        path: PathBuf,
215        /// Snapshot validation diagnostic.
216        reason: String,
217    },
218
219    /// The native runtime bridge could not execute the query.
220    #[error("failed to create Tokio runtime for NNS proposal query: {0}")]
221    Runtime(#[from] RuntimeError),
222}
223
224#[cfg(feature = "nns-host")]
225impl From<NnsGovernanceAttemptReadError> for NnsProposalHostError {
226    fn from(error: NnsGovernanceAttemptReadError) -> Self {
227        match error {
228            NnsGovernanceAttemptReadError::Cache(error) => Self::Cache(error),
229            NnsGovernanceAttemptReadError::Invalid { path, reason } => {
230                Self::InvalidRefreshAttempt { path, reason }
231            }
232        }
233    }
234}
ic_query/nns/proposals/report/error.rs

ic_query/nns/proposals/report/
error.rs
