canic_host/subnet_catalog/view/
mod.rs

1//! Module: subnet_catalog::view
2//!
3//! Responsibility: describe one validated catalog acquisition for operator review.
4//! Boundary: diagnostic observations are not desired-state or operation authority.
5
6use serde::Serialize;
7use std::path::PathBuf;
8
9///
10/// CatalogAcquisitionStage
11///
12/// Current host acquisition phase; collecting an endpoint never implies agreement.
13///
14
15#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
16#[serde(tag = "phase", rename_all = "snake_case")]
17pub enum CatalogAcquisitionStage {
18    CacheLookup,
19    Collecting {
20        endpoint: String,
21    },
22    Collected {
23        endpoint: String,
24        registry_version: u64,
25        query_calls: u64,
26    },
27    Complete {
28        cache_disposition: String,
29    },
30}
31
32///
33/// CatalogAcquisitionProgress
34///
35/// Read-only progress at the acquisition boundary, including its whole-operation budget.
36///
37
38#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
39pub struct CatalogAcquisitionProgress {
40    pub stage: CatalogAcquisitionStage,
41    pub completed_endpoints: usize,
42    pub active_endpoints: Vec<String>,
43    pub registry: Vec<RegistryCollectionProgress>,
44    pub elapsed_seconds: u64,
45    pub deadline_seconds: u64,
46}
47
48///
49/// SubnetCatalogObservation
50///
51/// Read-only host projection of snapshot identity and transient acquisition facts.
52///
53
54#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
55pub struct SubnetCatalogObservation {
56    pub cache_path: PathBuf,
57    pub cache_disposition: String,
58    pub fetched_at: String,
59    pub observed_at_unix_secs: u64,
60    pub age_seconds: Option<u64>,
61    pub max_age_seconds: u64,
62    pub registry_version: u64,
63    pub catalog_digest: String,
64    pub assurance: String,
65    pub source_endpoints: Vec<String>,
66}
67
68///
69/// RegistryCollectionProgress
70///
71/// Host diagnostic projection of the latest event for one endpoint.
72/// Query attempts exclude upstream transport-internal retries and verification calls.
73///
74
75#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
76pub struct RegistryCollectionProgress {
77    pub endpoint: String,
78    pub query_calls: u64,
79    pub stage: RegistryCollectionStage,
80}
81
82///
83/// RegistryCollectionStage
84///
85/// Typed Registry acquisition detail for host progress and timeout reports.
86/// Completed reads remain provisional until whole-catalog agreement validates.
87///
88
89#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
90#[serde(tag = "phase", rename_all = "snake_case")]
91pub enum RegistryCollectionStage {
92    Started,
93    Pinned {
94        registry_version: u64,
95    },
96    History {
97        registry_version: u64,
98        through_version: u64,
99        reused: bool,
100    },
101    Record {
102        registry_version: u64,
103        key: String,
104        completed: bool,
105    },
106    Retry {
107        method: String,
108        next_attempt: u8,
109        delay_millis: u64,
110    },
111}
canic_host/subnet_catalog/view/mod.rs

canic_host/subnet_catalog/view/
mod.rs
