canic-host 0.110.19

Host-side App build and desired-state Fleet reconciliation library for Canic workspaces
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

//! Module: subnet_catalog::view
//!
//! Responsibility: describe one validated catalog acquisition for operator review.
//! Boundary: diagnostic observations are not desired-state or operation authority.

use serde::Serialize;
use std::path::PathBuf;

///
/// CatalogAcquisitionStage
///
/// Current host acquisition phase; collecting an endpoint never implies agreement.
///

#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
#[serde(tag = "phase", rename_all = "snake_case")]
pub enum CatalogAcquisitionStage {
    CacheLookup,
    Collecting {
        endpoint: String,
    },
    Collected {
        endpoint: String,
        registry_version: u64,
        query_calls: u64,
    },
    Complete {
        cache_disposition: String,
    },
}

///
/// CatalogAcquisitionProgress
///
/// Read-only progress at the acquisition boundary, including its whole-operation budget.
///

#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct CatalogAcquisitionProgress {
    pub stage: CatalogAcquisitionStage,
    pub completed_endpoints: usize,
    pub active_endpoints: Vec<String>,
    pub registry: Vec<RegistryCollectionProgress>,
    pub elapsed_seconds: u64,
    pub deadline_seconds: u64,
}

///
/// SubnetCatalogObservation
///
/// Read-only host projection of snapshot identity and transient acquisition facts.
///

#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct SubnetCatalogObservation {
    pub cache_path: PathBuf,
    pub cache_disposition: String,
    pub fetched_at: String,
    pub observed_at_unix_secs: u64,
    pub age_seconds: Option<u64>,
    pub max_age_seconds: u64,
    pub registry_version: u64,
    pub catalog_digest: String,
    pub assurance: String,
    pub source_endpoints: Vec<String>,
}

///
/// RegistryCollectionProgress
///
/// Host diagnostic projection of the latest event for one endpoint.
/// Query attempts exclude upstream transport-internal retries and verification calls.
///

#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct RegistryCollectionProgress {
    pub endpoint: String,
    pub query_calls: u64,
    pub stage: RegistryCollectionStage,
}

///
/// RegistryCollectionStage
///
/// Typed Registry acquisition detail for host progress and timeout reports.
/// Completed reads remain provisional until whole-catalog agreement validates.
///

#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
#[serde(tag = "phase", rename_all = "snake_case")]
pub enum RegistryCollectionStage {
    Started,
    Pinned {
        registry_version: u64,
    },
    History {
        registry_version: u64,
        through_version: u64,
        reused: bool,
    },
    Record {
        registry_version: u64,
        key: String,
        completed: bool,
    },
    Retry {
        method: String,
        next_attempt: u8,
        delay_millis: u64,
    },
}