Skip to main content

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}