ic_query/cache/
completeness.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 from the source per page.
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    Ok(())
81}
82
83#[cfg(test)]
84mod tests {
85    use super::*;
86
87    #[test]
88    fn completeness_requires_api_exhaustion_and_consistent_page_evidence() {
89        for page_size in 0..=2 {
90            for page_count in 0..=2 {
91                for declared_row_count in 0..=2 {
92                    for actual_row_count in 0..=2 {
93                        let completeness = CacheCollectionCompleteness::api_exhausted(
94                            page_size,
95                            page_count,
96                            declared_row_count,
97                            false,
98                        );
99                        let expected_valid = page_size > 0
100                            && page_count > 0
101                            && declared_row_count == actual_row_count;
102
103                        assert_eq!(
104                            validate_cache_collection_completeness(&completeness, actual_row_count)
105                                .is_ok(),
106                            expected_valid,
107                            "page_size={page_size}, page_count={page_count}, declared_row_count={declared_row_count}, actual_row_count={actual_row_count}"
108                        );
109                    }
110                }
111            }
112        }
113
114        let mut unknown = CacheCollectionCompleteness::api_exhausted(1, 1, 0, false);
115        unknown.status = "unknown".to_string();
116        assert_eq!(
117            validate_cache_collection_completeness(&unknown, 0),
118            Err("completeness status is unknown, expected api_exhausted".to_string())
119        );
120        assert_eq!(
121            serde_json::to_value(CacheCollectionCompleteness::api_exhausted(1, 1, 0, false))
122                .expect("serialize completeness")["status"],
123            "api_exhausted"
124        );
125    }
126}
ic_query/cache/completeness.rs

ic_query/cache/
completeness.rs
