ic-query 0.103.1

Internet Computer query library for CloudEngine, NNS, SNS, ICRC, system canisters, and public network metadata
Documentation
//! Module: nns::proposals::report::error
//!
//! Responsibility: expose portable and native-wrapper NNS proposal failures.
//! Does not own: transport execution, cache mechanics, or process presentation.
//! Boundary: keeps canister/custom callers independent of native host dependencies.

#[cfg(feature = "nns-host")]
use crate::HostCacheError;
use crate::nns::governance::NnsGovernanceError;
#[cfg(feature = "nns-host")]
use std::path::PathBuf;
use thiserror::Error as ThisError;

///
/// NnsProposalError
///
/// Portable failure returned while collecting or assembling proposal reports.
///

#[derive(Debug, ThisError)]
pub enum NnsProposalError {
    /// Shared Governance request, transport, or provenance validation failed.
    #[error(transparent)]
    Governance(#[from] NnsGovernanceError),

    /// The requested page size is outside the bounded proposal contract.
    #[error("invalid NNS proposal page limit {limit}; expected 1..={maximum}")]
    InvalidLimit {
        /// Requested live-page row limit.
        limit: u32,
        /// Largest limit supported by Governance.
        maximum: u32,
    },

    /// Governance returned more proposal rows than requested.
    #[error("NNS proposal page returned {actual} rows; requested at most {requested}")]
    PageTooLarge {
        /// Number of rows returned by the source.
        actual: usize,
        /// Row ceiling supplied to the source.
        requested: u32,
    },

    /// A proposal page row did not include its required identifier.
    #[error("NNS proposal list page returned a row without a proposal id")]
    MissingProposalIdInPage,

    /// A proposal page used the reserved zero identifier.
    #[error("NNS proposal list page returned proposal id zero")]
    InvalidProposalIdInPage,

    /// A proposal page repeated an identifier.
    #[error("NNS proposal page returned duplicate proposal id {proposal_id}")]
    DuplicateProposalId {
        /// Identifier repeated within the returned page.
        proposal_id: u64,
    },

    /// A proposal did not satisfy the exclusive page cursor.
    #[error(
        "NNS proposal page returned id {proposal_id}; expected every id below {before_proposal_id}"
    )]
    ProposalCursorMismatch {
        /// Returned proposal that violates the exclusive cursor.
        proposal_id: u64,
        /// Requested exclusive upper proposal-id bound.
        before_proposal_id: u64,
    },

    /// Governance did not return the requested proposal.
    #[error("NNS proposal {proposal_id} was not found")]
    ProposalNotFound {
        /// Exact identifier requested by the caller.
        proposal_id: u64,
    },

    /// Governance returned a different proposal than requested.
    #[error("NNS proposal detail returned id {actual:?}; expected {expected}")]
    ProposalIdMismatch {
        /// Exact identifier requested by the caller.
        expected: u64,
        /// Identifier supplied in the returned row, if present.
        actual: Option<u64>,
    },
}

///
/// NnsProposalHostError
///
/// Native wrapper failure for proposal live calls, caches, and refreshes.
///

#[cfg(feature = "nns-host")]
#[derive(Debug, ThisError)]
pub enum NnsProposalHostError {
    /// Local activity input or aggregation failed.
    #[error(transparent)]
    Activity(#[from] super::NnsProposalActivityError),

    /// Portable proposal collection or validation failed.
    #[error(transparent)]
    Proposal(#[from] NnsProposalError),

    /// Confined cache IO or refresh locking failed.
    #[error(transparent)]
    Cache(#[from] HostCacheError),

    /// A cache-only read could not find the required complete snapshot.
    #[error("NNS proposals cache is missing at {}", path.display())]
    MissingProposalCache {
        /// Expected complete snapshot path.
        path: PathBuf,
    },

    /// A retained proposal snapshot failed its current contract.
    #[error("invalid NNS proposal cache at {}: {reason}", path.display())]
    InvalidCache {
        /// Snapshot file that failed validation.
        path: PathBuf,
        /// Snapshot validation diagnostic.
        reason: String,
    },
}