ic-query 0.96.0

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
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

//! Module: sns::report::model::reports::cache
//!
//! Responsibility: shared SNS complete-snapshot cache inspection DTOs.
//! Does not own: cache discovery, collection-specific storage, or rendering.
//! Boundary: preserves fields common to neuron cache list/status reports.

use super::SnsRefreshAttemptStatus;
use crate::cache::CacheValidationStatus;
use serde::Serialize;

///
/// SnsCacheListReport
///
/// Serializable report listing one family of complete local SNS caches.
///

#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct SnsCacheListReport {
    pub schema_version: u32,
    pub network: String,
    pub cache_root: String,
    pub caches: Vec<SnsCacheSummary>,
}

///
/// SnsCacheStatusReport
///
/// Serializable report describing one explicitly addressed SNS cache.
///

#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct SnsCacheStatusReport {
    pub schema_version: u32,
    pub network: String,
    pub cache_root: String,
    pub input: String,
    pub found: bool,
    pub cache: Option<SnsCacheSummary>,
    pub expected_cache_path: String,
    /// Independent refresh-attempt sidecar path.
    pub refresh_attempt_path: String,
    /// Latest admitted attempt evidence, independent of snapshot validity.
    pub latest_attempt: Option<SnsRefreshAttemptStatus>,
}

///
/// SnsCacheSummary
///
/// Serializable summary of one complete SNS snapshot cache.
///

#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct SnsCacheSummary {
    /// Inspected snapshot path, including invalid files.
    pub cache_path: String,
    /// Independent refresh-attempt sidecar path.
    pub refresh_attempt_path: String,
    /// Latest admitted attempt evidence, independent of snapshot validity.
    pub latest_attempt: Option<SnsRefreshAttemptStatus>,
    /// Admitted complete facts or the original content refusal.
    #[serde(flatten)]
    pub admission: SnsCacheAdmission,
}

impl SnsCacheSummary {
    /// Return facts only for an admitted complete snapshot.
    #[must_use]
    pub const fn valid(&self) -> Option<&SnsValidCacheSummary> {
        match &self.admission {
            SnsCacheAdmission::Valid { data } => Some(data),
            SnsCacheAdmission::Invalid { .. } => None,
        }
    }

    /// Return the cache admission outcome.
    #[must_use]
    pub const fn cache_status(&self) -> CacheValidationStatus {
        match self.admission {
            SnsCacheAdmission::Valid { .. } => CacheValidationStatus::Valid,
            SnsCacheAdmission::Invalid { .. } => CacheValidationStatus::Invalid,
        }
    }

    /// Original diagnostic for invalid content.
    #[must_use]
    pub fn cache_error(&self) -> Option<&str> {
        match &self.admission {
            SnsCacheAdmission::Invalid { cache_error } => Some(cache_error),
            SnsCacheAdmission::Valid { .. } => None,
        }
    }
}

///
/// SnsCacheAdmission
///
/// Complete snapshot facts or the original admission failure, never fabricated metadata.
///

#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
#[serde(tag = "cache_status", rename_all = "snake_case")]
pub enum SnsCacheAdmission {
    /// Admitted complete snapshot.
    Valid {
        /// Admitted complete collection facts.
        #[serde(flatten)]
        data: SnsValidCacheSummary,
    },
    /// Content failed admission; the envelope retains its path and independent attempt.
    Invalid {
        /// Original admission failure.
        cache_error: String,
    },
}

///
/// SnsValidCacheSummary
///
/// Identity and collection facts from an admitted complete SNS snapshot.
///

#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct SnsValidCacheSummary {
    /// Observed SNS-W list position.

    /// Observed SNS name.

    /// Admitted Governance principal.

    /// Admitted Governance principal.
    pub governance_canister_id: String,
    /// Rows in the admitted complete collection.
    pub row_count: usize,
    /// Pages collected through API exhaustion.
    pub page_count: u32,
    /// Requested rows per source page.
    pub page_size: u32,
    /// Admitted collection timestamp.
    pub fetched_at: String,
    /// Explicit endpoint that supplied the admitted snapshot.
    pub source_endpoint: String,
}