ic_query/nns/neuron/report/collection/
mod.rs1use 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
18pub const NNS_NEURON_COLLECTION_STATE_SCHEMA_VERSION: u32 = 1;
20
21#[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 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 #[must_use]
80 pub const fn neurons_fetched(&self) -> u64 {
81 self.neurons_fetched
82 }
83
84 #[must_use]
86 pub const fn next_start_neuron_id(&self) -> Option<u64> {
87 self.next_start_neuron_id
88 }
89}
90
91#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
98pub struct NnsNeuronCollectionStep {
99 pub page: NnsNeuronListReport,
101 pub state: NnsNeuronCollectionState,
103}
104
105pub 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;