ic_query/nns/neuron/report/error.rs
1//! Module: nns::neuron::report::error
2//!
3//! Responsibility: expose portable and native-wrapper NNS neuron failures.
4//! Does not own: transport execution, cache mechanics, or process presentation.
5//! Boundary: keeps canister and custom callers independent of native host dependencies.
6
7#[cfg(feature = "nns-host")]
8use crate::HostCacheError;
9use crate::nns::governance::NnsGovernanceError;
10#[cfg(feature = "nns-host")]
11use std::path::PathBuf;
12use thiserror::Error as ThisError;
13
14///
15/// NnsNeuronError
16///
17/// Portable failure returned while collecting or assembling neuron reports.
18///
19
20#[derive(Debug, ThisError)]
21pub enum NnsNeuronError {
22 /// Shared Governance request, transport, or provenance validation failed.
23 #[error(transparent)]
24 Governance(#[from] NnsGovernanceError),
25
26 /// The requested page size is outside Governance's supported range.
27 #[error("invalid NNS neuron page size {page_size}; expected 1..={max_page_size}")]
28 InvalidPageSize {
29 /// Rejected page size.
30 page_size: u32,
31 /// Largest page supported by Governance.
32 max_page_size: u32,
33 },
34
35 /// Governance returned its typed application-level error.
36 #[error("NNS Governance rejected the neuron query with code {error_type}: {message}")]
37 GovernanceResponse {
38 /// Raw Governance error type.
39 error_type: i32,
40 /// Governance error message.
41 message: String,
42 },
43
44 /// Governance has no publicly readable view for the requested neuron id.
45 #[error("NNS neuron {neuron_id} was not found")]
46 NeuronNotFound {
47 /// Requested neuron identifier.
48 neuron_id: u64,
49 },
50
51 /// Governance returned a neuron row without its required identifier.
52 #[error("NNS Governance returned a neuron row without an id")]
53 MissingNeuronId,
54
55 /// A source page or detail row violated the neuron contract.
56 #[error("invalid NNS neuron response: {reason}")]
57 InvalidResponse {
58 /// Response invariant that failed.
59 reason: String,
60 },
61}
62
63///
64/// NnsNeuronHostError
65///
66/// Native wrapper failure for neuron live calls, caches, and refreshes.
67///
68
69#[cfg(feature = "nns-host")]
70#[derive(Debug, ThisError)]
71pub enum NnsNeuronHostError {
72 /// A cache-only read could not find the required complete snapshot.
73 #[error("NNS neurons cache is missing at {}", path.display())]
74 MissingNeuronCache {
75 /// Expected complete snapshot path.
76 path: PathBuf,
77 },
78
79 /// Local distribution input or aggregation failed.
80 #[error(transparent)]
81 Distribution(#[from] super::NnsNeuronDistributionError),
82
83 /// Portable neuron collection or validation failed.
84 #[error(transparent)]
85 Neuron(#[from] NnsNeuronError),
86
87 /// A stored neuron snapshot failed family-specific validation.
88 #[error("invalid NNS neuron cache at {}: {reason}", path.display())]
89 InvalidCache {
90 /// Cache path being validated.
91 path: PathBuf,
92 /// Cache invariant that failed.
93 reason: String,
94 },
95
96 /// Shared cache IO or lock handling failed.
97 #[error(transparent)]
98 Cache(#[from] HostCacheError),
99}