ic-query 0.80.1

Internet Computer query library for CloudEngine, NNS, SNS, ICRC, system canisters, and public network metadata
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

//! Module: sns::report::model::requests::neurons
//!
//! Responsibility: request DTOs for SNS neuron reports and cache commands.
//! Does not own: command option parsing, cache storage, or live neuron fetches.
//! Boundary: carries validated neuron inputs into SNS report builders.

use super::lookup::SnsLookupRequest;
use crate::sns::report::SnsNeuronsCacheSort;
use std::path::PathBuf;

///
/// SnsNeuronRequest
///
/// Request accepted by the exact SNS neuron detail report builder.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub struct SnsNeuronRequest {
    /// SNS target, explicit endpoint, network and caller clock.
    pub lookup: SnsLookupRequest,
    /// Exact 32-byte neuron id encoded as 64 lowercase hexadecimal characters.
    pub neuron_id: String,
}

impl SnsNeuronRequest {
    /// Construct one exact SNS neuron detail request.
    #[must_use]
    pub fn new(lookup: SnsLookupRequest, neuron_id: impl Into<String>) -> Self {
        Self {
            lookup,
            neuron_id: neuron_id.into(),
        }
    }
}

///
/// SnsNeuronCollection
///
/// Acquisition inputs for a bounded live page or a view over a complete cache.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub enum SnsNeuronCollection {
    /// One live API page, optionally scoped to a permission owner.
    Live {
        /// Optional principal whose permissions select the page.
        owner_principal_id: Option<String>,
    },
    /// A whole-collection cache view with local ordering.
    Cached {
        /// Caller-selected managed cache root.
        cache_root: PathBuf,
        /// Ordering applied after loading the complete snapshot.
        sort: SnsNeuronsCacheSort,
    },
}

impl SnsNeuronCollection {
    pub(in crate::sns::report) const fn sort_label(&self) -> &'static str {
        match self {
            Self::Live { .. } => "api",
            Self::Cached { sort, .. } => sort.as_str(),
        }
    }
}

///
/// SnsNeuronsRequest
///
/// A bounded live neuron page or a view over a complete neuron cache.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub struct SnsNeuronsRequest {
    /// Explicit target, endpoint, network and caller clock.
    pub lookup: SnsLookupRequest,
    /// Maximum displayed rows; does not change snapshot identity.
    pub limit: u32,
    /// Inputs specific to the selected acquisition route.
    pub collection: SnsNeuronCollection,
    /// Include additional human-facing detail.
    pub verbose: bool,
}

impl SnsNeuronsRequest {
    /// Request one live API page with optional owner filtering.
    #[must_use]
    pub const fn live(
        lookup: SnsLookupRequest,
        limit: u32,
        owner_principal_id: Option<String>,
    ) -> Self {
        Self {
            lookup,
            limit,
            collection: SnsNeuronCollection::Live { owner_principal_id },
            verbose: false,
        }
    }

    /// Request a locally ordered view of a complete snapshot.
    #[must_use]
    pub fn cached(
        lookup: SnsLookupRequest,
        limit: u32,
        cache_root: impl Into<PathBuf>,
        sort: SnsNeuronsCacheSort,
    ) -> Self {
        Self {
            lookup,
            limit,
            collection: SnsNeuronCollection::Cached {
                cache_root: cache_root.into(),
                sort,
            },
            verbose: false,
        }
    }

    /// Select detailed text rendering.
    #[must_use]
    pub const fn with_verbose(mut self, verbose: bool) -> Self {
        self.verbose = verbose;
        self
    }
}