ic-query 0.52.6

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

//! Module: snapshot_cache::paged
//!
//! Responsibility: accumulate admitted rows across paged API walks.
//! Does not own: source fetching, progress rendering, or cache publication.
//! Boundary: tracks page counters and cursors after family-owned page validation.

///
/// CompletePagedCollection
///
/// Admitted rows and pagination metadata from a complete API walk.
///

#[cfg(feature = "sns-host")]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct CompletePagedCollection<Row> {
    pub rows: Vec<Row>,
    pub page_count: u32,
    pub last_cursor: Option<String>,
}

///
/// PagedCollectionPage
///
/// Per-page progress and SNS exhaustion evidence for the refresh runner.
///

pub struct PagedCollectionPage {
    #[cfg(feature = "sns-host")]
    page_len: usize,
    new_rows: usize,
    pub last_cursor_text: Option<String>,
}

///
/// PagedCollectionState
///
/// Accumulates validated rows while walking a cursor-based collection.
///

#[cfg(feature = "sns-host")]
pub struct PagedCollectionState<Row, Cursor> {
    rows: Vec<Row>,
    page_count: u32,
    next_cursor: Option<Cursor>,
}

#[cfg(feature = "sns-host")]
impl<Row, Cursor> Default for PagedCollectionState<Row, Cursor> {
    fn default() -> Self {
        Self {
            rows: Vec::new(),
            page_count: 0,
            next_cursor: None,
        }
    }
}

#[cfg(feature = "sns-host")]
impl<Row, Cursor> PagedCollectionState<Row, Cursor> {
    pub fn new() -> Self {
        Self::default()
    }

    pub const fn page_count(&self) -> u32 {
        self.page_count
    }

    pub const fn row_count(&self) -> usize {
        self.rows.len()
    }

    pub const fn next_cursor(&self) -> Option<&Cursor> {
        self.next_cursor.as_ref()
    }

    pub const fn has_next_cursor(&self) -> bool {
        self.next_cursor.is_some()
    }

    /// Record admitted rows while retaining the unmodified API page length for exhaustion.
    pub fn ingest_page(
        &mut self,
        rows: Vec<Row>,
        page_len: usize,
        next_cursor: Option<Cursor>,
        cursor_text: impl FnOnce(&Cursor) -> String,
    ) -> PagedCollectionPage {
        self.page_count = self.page_count.saturating_add(1);
        let last_cursor_text = next_cursor.as_ref().map(cursor_text);
        let new_rows = rows.len();
        self.rows.extend(rows);
        self.next_cursor = next_cursor;

        PagedCollectionPage {
            page_len,
            new_rows,
            last_cursor_text,
        }
    }

    pub fn into_complete(
        self,
        cursor_text: impl FnOnce(&Cursor) -> String,
    ) -> CompletePagedCollection<Row> {
        CompletePagedCollection {
            rows: self.rows,
            page_count: self.page_count,
            last_cursor: self.next_cursor.as_ref().map(cursor_text),
        }
    }
}

impl PagedCollectionPage {
    /// Describe one validated NNS page, whose rows are all newly admitted.
    #[must_use]
    #[cfg(feature = "nns-host")]
    pub const fn new(new_rows: usize, last_cursor_text: Option<String>) -> Self {
        Self {
            #[cfg(feature = "sns-host")]
            page_len: new_rows,
            new_rows,
            last_cursor_text,
        }
    }

    #[cfg(feature = "sns-host")]
    pub fn exhausts_collection(&self, page_size: u32, has_next_cursor: bool) -> bool {
        self.page_len < usize::try_from(page_size).unwrap_or(usize::MAX) || !has_next_cursor
    }

    pub const fn has_no_new_rows(&self) -> bool {
        self.new_rows == 0
    }
}