ic_query/cache/completeness/
mod.rs

1//! Module: cache::completeness
2//!
3//! Responsibility: define and validate complete paged-collection evidence.
4//! Does not own: family cache envelopes, row validation, or filesystem IO.
5//! Boundary: preserves the raw persisted status while centralizing the one
6//! complete-collection contract shared by NNS, SNS, and ICRC caches.
7
8use serde::{Deserialize as SerdeDeserialize, Serialize};
9
10const API_EXHAUSTED_STATUS: &str = "api_exhausted";
11
12///
13/// CacheCollectionCompleteness
14///
15/// Persisted evidence that a paged cache collection exhausted its source API.
16///
17
18#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
19pub struct CacheCollectionCompleteness {
20    /// Raw persisted completeness status; complete collections use `api_exhausted`.
21    pub status: String,
22    /// Maximum rows requested per page, or observed width of an unpaged inventory (at least one).
23    pub page_size: u32,
24    /// Number of source pages collected.
25    pub page_count: u32,
26    /// Number of unique rows retained in the complete cache.
27    pub row_count: usize,
28    /// Whether every page is guaranteed to describe one source instant.
29    pub point_in_time_guaranteed: bool,
30}
31
32impl CacheCollectionCompleteness {
33    /// Construct evidence for an API-exhausted paged collection.
34    #[must_use]
35    pub fn api_exhausted(
36        page_size: u32,
37        page_count: u32,
38        row_count: usize,
39        point_in_time_guaranteed: bool,
40    ) -> Self {
41        Self {
42            status: API_EXHAUSTED_STATUS.to_string(),
43            page_size,
44            page_count,
45            row_count,
46            point_in_time_guaranteed,
47        }
48    }
49
50    /// Return whether the raw status claims source API exhaustion.
51    #[must_use]
52    pub fn is_api_exhausted(&self) -> bool {
53        self.status == API_EXHAUSTED_STATUS
54    }
55}
56
57/// Validate shared API-exhaustion, page, and row-count evidence.
58pub fn validate_cache_collection_completeness(
59    completeness: &CacheCollectionCompleteness,
60    actual_row_count: usize,
61) -> Result<(), String> {
62    if !completeness.is_api_exhausted() {
63        return Err(format!(
64            "completeness status is {}, expected {API_EXHAUSTED_STATUS}",
65            completeness.status
66        ));
67    }
68    if completeness.page_size == 0 {
69        return Err("completeness page_size must be greater than zero".to_string());
70    }
71    if completeness.page_count == 0 {
72        return Err("completeness page_count must be greater than zero".to_string());
73    }
74    if completeness.row_count != actual_row_count {
75        return Err(format!(
76            "completeness row_count is {}, actual row count is {actual_row_count}",
77            completeness.row_count
78        ));
79    }
80    let maximum_row_count = u64::from(completeness.page_size) * u64::from(completeness.page_count);
81    if actual_row_count as u128 > u128::from(maximum_row_count) {
82        return Err(format!(
83            "completeness row_count is {actual_row_count}, maximum for {} pages of size {} is {maximum_row_count}",
84            completeness.page_count, completeness.page_size
85        ));
86    }
87    Ok(())
88}
89
90#[cfg(test)]
91mod tests;
ic_query/cache/completeness/mod.rs

ic_query/cache/completeness/
mod.rs
