Skip to main content

ic_query/nns/neuron/report/collection/
mod.rs

1//! Module: nns::neuron::report::collection
2//!
3//! Responsibility: advance caller-persisted complete public-neuron walks one page at a time.
4//! Does not own: stable memory, filesystem caches, scheduling, retries, or publication.
5//! Boundary: validates resumable input and derives the next state from one admitted source page.
6
7use super::{
8    NnsNeuronError,
9    model::{NnsNeuronListReport, NnsNeuronListRequest},
10    source::{NnsNeuronSource, build_nns_neuron_list_report_with_source, validate_page_size},
11};
12use crate::nns::governance::{
13    GovernanceCollectionState, NnsGovernanceError, NnsGovernanceRequest,
14    governance_collection_accessors, validate_governance_request,
15};
16use serde::{Deserialize, Serialize};
17
18/// Version of the persistable resumable NNS neuron collection state.
19pub const NNS_NEURON_COLLECTION_STATE_SCHEMA_VERSION: u32 = 1;
20
21///
22/// NnsNeuronCollectionState
23///
24/// Serializable continuation state for an explicitly bounded public-neuron walk.
25///
26
27#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
28#[serde(deny_unknown_fields)]
29pub struct NnsNeuronCollectionState {
30    #[serde(flatten)]
31    collection: GovernanceCollectionState,
32    neurons_fetched: u64,
33    next_start_neuron_id: Option<u64>,
34}
35
36impl NnsNeuronCollectionState {
37    /// Start an empty neuron walk with explicit per-page and cumulative call ceilings.
38    pub fn new(
39        request: &NnsGovernanceRequest,
40        page_size: u32,
41        max_pages: u32,
42    ) -> Result<Self, NnsNeuronError> {
43        validate_governance_request(request)?;
44        validate_page_size(page_size)?;
45        if max_pages == 0 {
46            return Err(NnsGovernanceError::InvalidCollectionMaxPages.into());
47        }
48        Ok(Self {
49            collection: GovernanceCollectionState::new(request, page_size, max_pages),
50            neurons_fetched: 0,
51            next_start_neuron_id: None,
52        })
53    }
54
55    #[cfg(feature = "nns-host")]
56    pub(in crate::nns) const fn from_complete_collection(
57        collection: GovernanceCollectionState,
58        rows: u64,
59    ) -> Self {
60        Self {
61            collection,
62            neurons_fetched: rows,
63            next_start_neuron_id: None,
64        }
65    }
66
67    #[cfg(feature = "nns-host")]
68    pub(in crate::nns) fn collection_evidence(
69        &self,
70    ) -> crate::nns::governance::collection::NnsGovernanceCollectionEvidence {
71        crate::nns::governance::collection::NnsGovernanceCollectionEvidence::from_state(
72            &self.collection,
73        )
74    }
75
76    governance_collection_accessors!(next_start_neuron_id);
77
78    /// Return the number of successfully admitted neuron rows.
79    #[must_use]
80    pub const fn neurons_fetched(&self) -> u64 {
81        self.neurons_fetched
82    }
83
84    /// Return the exclusive lower neuron-id bound for the next page.
85    #[must_use]
86    pub const fn next_start_neuron_id(&self) -> Option<u64> {
87        self.next_start_neuron_id
88    }
89}
90
91///
92/// NnsNeuronCollectionStep
93///
94/// One admitted bounded page and the continuation state that follows it.
95///
96
97#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
98pub struct NnsNeuronCollectionStep {
99    /// Page returned by the shared public-neuron report builder.
100    pub page: NnsNeuronListReport,
101    /// Validated state to persist only after retaining the page.
102    pub state: NnsNeuronCollectionState,
103}
104
105/// Advance a resumable public-neuron walk by exactly one caller-runtime source call.
106pub async fn advance_nns_neuron_collection_with_source(
107    request: &NnsGovernanceRequest,
108    state: &NnsNeuronCollectionState,
109    source: &dyn NnsNeuronSource,
110) -> Result<NnsNeuronCollectionStep, NnsNeuronError> {
111    validate_governance_request(request)?;
112    validate_collection_state(state)?;
113    state
114        .collection
115        .validate_continuation(request, state.next_start_neuron_id.is_some())?;
116
117    let mut page_request = NnsNeuronListRequest::new(request.clone(), state.collection.page_size);
118    page_request.exclusive_start_neuron_id = state.next_start_neuron_id;
119    let page = build_nns_neuron_list_report_with_source(&page_request, source).await?;
120    let (collection, neurons_fetched) = state.collection.after_page(
121        request,
122        page.context.source.clone(),
123        state.neurons_fetched,
124        page.neurons.len(),
125    )?;
126    let next_start_neuron_id = page.next_start_neuron_id;
127    let next_state = NnsNeuronCollectionState {
128        collection,
129        neurons_fetched,
130        next_start_neuron_id,
131    };
132    Ok(NnsNeuronCollectionStep {
133        page,
134        state: next_state,
135    })
136}
137
138pub(super) fn validate_collection_state(
139    state: &NnsNeuronCollectionState,
140) -> Result<(), NnsNeuronError> {
141    state
142        .collection
143        .validate(NNS_NEURON_COLLECTION_STATE_SCHEMA_VERSION)?;
144    validate_page_size(state.collection.page_size)?;
145
146    let neurons_fetched = state.neurons_fetched;
147    let maximum_rows = state
148        .collection
149        .validate_row_bounds("neurons_fetched", neurons_fetched)?;
150
151    state
152        .collection
153        .validate_lifecycle(
154            neurons_fetched,
155            maximum_rows,
156            state.next_start_neuron_id.is_some(),
157            neurons_fetched < maximum_rows,
158        )
159        .map_err(Into::into)
160}
161
162#[cfg(test)]
163mod tests;