ic-query 0.103.1

Internet Computer query library for CloudEngine, NNS, SNS, ICRC, system canisters, and public network metadata
Documentation
//! Module: nns::governance::error
//!
//! Responsibility: expose portable and native-wrapper Governance failures.
//! Does not own: validation, transport execution, or process error presentation.
//! Boundary: preserves transport details without coupling portable callers to a runtime.

use super::NnsGovernanceSourceProvenance;
use thiserror::Error as ThisError;

///
/// NnsGovernanceError
///
/// Portable failure returned while collecting or assembling a Governance report.
///

#[derive(Debug, ThisError)]
pub enum NnsGovernanceError {
    /// A caller-supplied collection timestamp is not a valid UTC date and time.
    #[error("invalid NNS Governance {field} timestamp: {value:?}")]
    InvalidTimestamp {
        /// Request, continuation, or report field containing the timestamp.
        field: &'static str,
        /// Rejected UTC timestamp text.
        value: String,
    },

    /// A continuation or restored collection goes backward in time.
    #[error("{end_field} ({end}) precedes {start_field} ({start})")]
    InvalidTimestampOrder {
        /// Earlier boundary's field name.
        start_field: &'static str,
        /// Earlier boundary's canonical UTC value.
        start: String,
        /// Later boundary's field name.
        end_field: &'static str,
        /// Rejected later boundary's canonical UTC value.
        end: String,
    },

    /// The requested network is not the supported mainnet identity.
    #[error("direct NNS Governance reports support only the mainnet `ic` network, not {network:?}")]
    UnsupportedNetwork {
        /// Rejected network identity.
        network: String,
    },

    /// The selected transport cannot be executed by the source adapter.
    #[error("invalid NNS Governance source selection: {reason}")]
    InvalidSourceSelection {
        /// Validation failure.
        reason: String,
    },

    /// Returned provenance did not match the requested transport.
    #[error("NNS Governance source evidence does not match the request: {reason}")]
    SourceEvidenceMismatch {
        /// Evidence mismatch.
        reason: String,
    },

    /// Native IC agent setup failed.
    #[error("failed to build IC agent for {endpoint}: {reason}")]
    AgentBuild {
        /// Endpoint used to build the agent.
        endpoint: String,
        /// Agent construction failure.
        reason: String,
    },

    /// A native IC agent query failed.
    #[error("NNS Governance agent call {method} failed: {reason}")]
    AgentCall {
        /// Governance method being queried.
        method: &'static str,
        /// Query failure.
        reason: String,
    },

    /// A replicated inter-canister call could not be submitted.
    #[error("NNS Governance inter-canister call {method} failed: {reason}")]
    InterCanisterCall {
        /// Governance method being called.
        method: &'static str,
        /// Cycle-balance or call-perform failure.
        reason: String,
    },

    /// A replicated inter-canister call returned an IC reject.
    #[error(
        "NNS Governance inter-canister call {method} was rejected with code {reject_code}: {message}"
    )]
    InterCanisterCallRejected {
        /// Governance method being called.
        method: &'static str,
        /// Raw IC reject code.
        reject_code: u32,
        /// Reject message returned by the IC.
        message: String,
    },

    /// A Candid request could not be encoded.
    #[error("failed to encode Candid {message}: {reason}")]
    CandidEncode {
        /// Candid request type.
        message: &'static str,
        /// Encoding failure.
        reason: String,
    },

    /// A Candid response could not be decoded.
    #[error("failed to decode Candid {message}: {reason}")]
    CandidDecode {
        /// Candid response type.
        message: &'static str,
        /// Decoding failure.
        reason: String,
    },

    /// A response exceeded the library's explicit raw-response byte bound.
    #[error("NNS Governance {method} response was {actual_bytes} bytes; limit is {maximum_bytes}")]
    ResponseTooLarge {
        /// Governance method being decoded.
        method: &'static str,
        /// Actual response size.
        actual_bytes: usize,
        /// Maximum accepted response size.
        maximum_bytes: usize,
    },

    /// Governance returned its typed application-level error.
    #[error("NNS Governance rejected the metrics query with code {error_type}: {message}")]
    Governance {
        /// Raw Governance error type.
        error_type: i32,
        /// Governance error message.
        message: String,
    },

    /// Governance returned a non-finite metric that JSON cannot preserve.
    #[error("NNS Governance metric {field} bucket {key} has non-finite value {value}")]
    InvalidMetrics {
        /// Native Governance metric field.
        field: &'static str,
        /// Raw metric bucket key.
        key: u64,
        /// Rejected non-finite bucket value.
        value: f64,
    },
    /// A resumable collection was configured without any page capacity.
    #[error("invalid NNS Governance collection page limit 0; expected at least one page")]
    InvalidCollectionMaxPages,

    /// Serialized or caller-modified resumable collection state is inconsistent.
    #[error("invalid NNS Governance collection state: {reason}")]
    InvalidCollectionState {
        /// Deterministic state invariant that failed.
        reason: String,
    },

    /// A continuation request changed an identity fixed when collection started.
    #[error(
        "NNS Governance collection request changed {field}: received {actual}, expected {expected}"
    )]
    CollectionRequestMismatch {
        /// Fixed request field that changed.
        field: &'static str,
        /// Value retained by the collection state.
        expected: String,
        /// Value supplied by the continuation request.
        actual: String,
    },

    /// A caller attempted to advance a collection that already exhausted the API.
    #[error("NNS Governance collection is already complete after {pages_fetched} pages")]
    CollectionComplete {
        /// Pages admitted before API exhaustion.
        pages_fetched: u32,
    },

    /// A caller attempted to advance a collection after consuming its page budget.
    #[error(
        "NNS Governance collection reached its {max_pages}-page limit after {pages_fetched} pages"
    )]
    CollectionPageLimitReached {
        /// Pages admitted before the stopped advance.
        pages_fetched: u32,
        /// Configured cumulative page ceiling.
        max_pages: u32,
    },

    /// A later collection page was returned by a different collector.
    #[error("NNS Governance collection source changed: received {actual:?}, expected {expected:?}")]
    CollectionSourceChanged {
        /// Concrete source retained from the first admitted page.
        expected: NnsGovernanceSourceProvenance,
        /// Concrete source returned with the candidate page.
        actual: NnsGovernanceSourceProvenance,
    },

    /// Cumulative page or row accounting exceeded its integer representation.
    #[error("NNS Governance collection accounting overflow")]
    CollectionAccountingOverflow,
}

#[cfg(feature = "nns-host")]
crate::candid_call::impl_candid_call_error!(NnsGovernanceError);