ic_query/cache/model/
mod.rs

1//! Module: cache::model
2//!
3//! Responsibility: define shared cache-validation and refresh-attempt contracts.
4//! Does not own: filesystem traversal, cache-family validation, or CLI output.
5//! Boundary: preserves typed family validation and refresh-attempt evidence.
6
7use serde::{Deserialize as SerdeDeserialize, Serialize};
8use std::fmt;
9
10///
11/// CacheValidationStatus
12///
13/// Semantic validation result for an existing family-specific cache.
14///
15
16#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
17#[serde(rename_all = "snake_case")]
18pub enum CacheValidationStatus {
19    /// The cache passed its family-specific schema, identity, and completeness checks.
20    #[serde(rename = "ok")]
21    Valid,
22    /// The cache exists but failed family-specific validation.
23    Invalid,
24}
25
26impl CacheValidationStatus {
27    /// Return the stable serialized status label.
28    #[must_use]
29    pub const fn as_str(self) -> &'static str {
30        match self {
31            Self::Valid => "ok",
32            Self::Invalid => "invalid",
33        }
34    }
35}
36
37impl fmt::Display for CacheValidationStatus {
38    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
39        formatter.write_str(self.as_str())
40    }
41}
42
43///
44/// CacheRefreshAttemptStatus
45///
46/// Lifecycle state for a complete-cache refresh attempt.
47///
48
49#[derive(Clone, Copy, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
50#[serde(rename_all = "snake_case")]
51pub enum CacheRefreshAttemptStatus {
52    /// A refresh started or published intermediate collection progress.
53    Running,
54    /// A refresh exhausted its source and published a complete cache.
55    Complete,
56    /// A refresh terminated without replacing the complete cache.
57    Failed,
58}
59
60impl CacheRefreshAttemptStatus {
61    /// Return the stable serialized lifecycle label.
62    #[must_use]
63    pub const fn as_str(self) -> &'static str {
64        match self {
65            Self::Running => "running",
66            Self::Complete => "complete",
67            Self::Failed => "failed",
68        }
69    }
70}
71
72impl fmt::Display for CacheRefreshAttemptStatus {
73    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
74        formatter.write_str(self.as_str())
75    }
76}
77
78#[cfg(test)]
79mod tests;
80
81///
82/// SnapshotRefreshAttemptStatus
83///
84/// Report-safe lifecycle evidence projected after a family validates its attempt sidecar.
85///
86
87#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
88pub struct SnapshotRefreshAttemptStatus {
89    /// Current lifecycle status.
90    pub status: CacheRefreshAttemptStatus,
91    /// Attempt start timestamp.
92    pub started_at: String,
93    /// Latest attempt update timestamp.
94    pub updated_at: String,
95    /// Requested page size.
96    pub page_size: u32,
97    /// Successfully retained pages.
98    pub pages_fetched: u32,
99    /// Successfully retained rows.
100    pub rows_fetched: usize,
101    /// Latest exclusive cursor.
102    pub last_cursor: Option<String>,
103    /// Terminal failure evidence.
104    pub last_error: Option<String>,
105}
ic_query/cache/model/mod.rs

ic_query/cache/model/
mod.rs
