ic_query/ic/node_status/
model.rs

1//! Module: ic::node_status::model
2//!
3//! Responsibility: public observed node-status requests, evidence, reports, and errors.
4//! Does not own: source calls, cache IO, projection, or rendering.
5//! Boundary: preserves raw Dashboard status data and explicit off-chain/cache provenance.
6
7use crate::ic::IcDashboardReportProvenance;
8use serde::{Deserialize as SerdeDeserialize, Serialize};
9use std::fmt;
10#[cfg(feature = "dashboard-host")]
11use std::path::PathBuf;
12use thiserror::Error as ThisError;
13
14///
15/// IcNodeStatusScope
16///
17/// Dashboard collection scope retained by an observed node-status snapshot.
18///
19
20#[derive(Clone, Copy, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
21#[serde(rename_all = "snake_case")]
22pub enum IcNodeStatusScope {
23    /// Dashboard's default public-mainnet node set, excluding cloud-engine Type4 nodes.
24    DashboardMainnetDefault,
25}
26
27impl IcNodeStatusScope {
28    /// Return the stable serialized scope label.
29    #[must_use]
30    pub const fn as_str(self) -> &'static str {
31        match self {
32            Self::DashboardMainnetDefault => super::IC_NODE_STATUS_SCOPE,
33        }
34    }
35}
36
37///
38/// IcNodeOperationalStatus
39///
40/// Known Dashboard node-status classification used for filtering and counts.
41///
42
43#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Serialize)]
44#[serde(rename_all = "snake_case")]
45pub enum IcNodeOperationalStatus {
46    /// The Dashboard reports the node as up.
47    Up,
48    /// The Dashboard reports the node as down.
49    Down,
50    /// The Dashboard reports the node as administratively disabled.
51    Disabled,
52    /// The Dashboard reports degraded operation.
53    Degraded,
54    /// The raw Dashboard value is not recognized by this release.
55    Unknown,
56}
57
58impl IcNodeOperationalStatus {
59    /// Classify raw Dashboard status text without discarding unknown future values.
60    #[must_use]
61    pub fn from_raw(raw: &str) -> Self {
62        match raw {
63            "UP" => Self::Up,
64            "DOWN" => Self::Down,
65            "DISABLED" => Self::Disabled,
66            "DEGRADED" => Self::Degraded,
67            _ => Self::Unknown,
68        }
69    }
70
71    /// Return the stable lowercase display label.
72    #[must_use]
73    pub const fn as_str(self) -> &'static str {
74        match self {
75            Self::Up => "up",
76            Self::Down => "down",
77            Self::Disabled => "disabled",
78            Self::Degraded => "degraded",
79            Self::Unknown => "unknown",
80        }
81    }
82}
83
84impl fmt::Display for IcNodeOperationalStatus {
85    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
86        formatter.write_str(self.as_str())
87    }
88}
89
90///
91/// IcNodeStatusCounts
92///
93/// Exact status totals derived from raw observed node rows.
94///
95
96#[derive(Clone, Debug, Default, Eq, PartialEq, SerdeDeserialize, Serialize)]
97pub struct IcNodeStatusCounts {
98    /// Total observed rows in the group.
99    pub total: usize,
100    /// Rows classified as `UP`.
101    pub up: usize,
102    /// Rows classified as `DOWN`.
103    pub down: usize,
104    /// Rows classified as `DISABLED`.
105    pub disabled: usize,
106    /// Rows classified as `DEGRADED`.
107    pub degraded: usize,
108    /// Rows whose raw status is not recognized.
109    pub unknown: usize,
110}
111
112impl IcNodeStatusCounts {
113    /// Return every row not classified as raw Dashboard `UP`.
114    #[must_use]
115    pub const fn non_up(&self) -> usize {
116        self.total.saturating_sub(self.up)
117    }
118}
119
120///
121/// IcNodeAssignmentStatusCounts
122///
123/// Operational-status totals partitioned by mutually exclusive assignment class.
124///
125
126#[derive(Clone, Debug, Default, Eq, PartialEq, SerdeDeserialize, Serialize)]
127pub struct IcNodeAssignmentStatusCounts {
128    /// Status totals for nodes with an observed assigned Subnet.
129    pub assigned: IcNodeStatusCounts,
130    /// Status totals for rows whose raw node type is `UNASSIGNED`.
131    pub unassigned: IcNodeStatusCounts,
132    /// Status totals for rows whose raw node type is `API_BOUNDARY`.
133    pub api_boundary: IcNodeStatusCounts,
134    /// Status totals for rows without a known assignment class.
135    pub unknown: IcNodeStatusCounts,
136}
137
138///
139/// IcNodeStatusGroupCounts
140///
141/// Overall and assignment-partitioned status totals for one aggregate group.
142///
143
144#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize)]
145pub struct IcNodeStatusGroupCounts {
146    /// Raw operational-status totals for the group.
147    pub statuses: IcNodeStatusCounts,
148    /// Raw operational-status totals partitioned by assignment class.
149    pub assignment_statuses: IcNodeAssignmentStatusCounts,
150}
151
152///
153/// IcNodeCountComparison
154///
155/// Ordering of one observed node count relative to another.
156///
157
158#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
159#[serde(rename_all = "snake_case")]
160pub enum IcNodeCountComparison {
161    /// The left-hand count is smaller.
162    Less,
163    /// The two counts are equal.
164    Equal,
165    /// The left-hand count is larger.
166    Greater,
167}
168
169impl IcNodeCountComparison {
170    /// Compare a left-hand count with a right-hand count.
171    #[must_use]
172    pub const fn from_counts(left: usize, right: usize) -> Self {
173        if left < right {
174            Self::Less
175        } else if left > right {
176            Self::Greater
177        } else {
178            Self::Equal
179        }
180    }
181
182    /// Return the stable lowercase label.
183    #[must_use]
184    pub const fn as_str(self) -> &'static str {
185        match self {
186            Self::Less => "less",
187            Self::Equal => "equal",
188            Self::Greater => "greater",
189        }
190    }
191}
192
193///
194/// IcNodeCountComparisonCounts
195///
196/// Number of provider groups in each node-count comparison outcome.
197///
198
199#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize)]
200pub struct IcNodeCountComparisonCounts {
201    /// Provider groups whose left-hand count is smaller.
202    pub less: usize,
203    /// Provider groups whose counts are equal.
204    pub equal: usize,
205    /// Provider groups whose left-hand count is larger.
206    pub greater: usize,
207}
208
209///
210/// IcNodeStatusRow
211///
212/// One raw node observation retained from the official Dashboard node resource.
213///
214
215#[derive(Clone, Debug, Eq, PartialEq, SerdeDeserialize, Serialize)]
216pub struct IcNodeStatusRow {
217    /// Canonical node principal.
218    pub node_id: String,
219    /// Canonical node-operator principal.
220    pub node_operator_id: String,
221    /// Canonical node-provider principal.
222    pub node_provider_id: String,
223    /// Off-chain Dashboard node-provider name.
224    pub node_provider_name: String,
225    /// Raw Dashboard node type.
226    pub node_type: String,
227    /// Raw Registry reward type reported by the Dashboard.
228    pub node_reward_type: String,
229    /// Raw Dashboard operational status.
230    pub status: String,
231    /// Raw Dashboard alert name when present.
232    pub alert_name: Option<String>,
233    /// Assigned Subnet principal when present.
234    pub subnet_id: Option<String>,
235    /// CloudEngine Subnet principal when reported by the selected Dashboard scope.
236    pub cloud_engine_subnet_id: Option<String>,
237    /// Dashboard data-center identifier.
238    pub data_center_id: String,
239    /// Dashboard data-center name.
240    pub data_center_name: String,
241    /// Dashboard infrastructure owner label.
242    pub owner: String,
243    /// Raw Dashboard geographic region label.
244    pub region: String,
245    /// Observed GuestOS version when reported.
246    pub guestos_version: Option<String>,
247    /// Observed GuestOS trusted-execution status when reported.
248    pub guestos_tee_active: Option<bool>,
249    /// Observed node IP address when reported.
250    pub ip_address: Option<String>,
251    /// Observed IPv4-connectivity state when reported.
252    pub ipv4_connectivity_status: Option<bool>,
253    /// Dashboard hardware-generation label when reported.
254    pub node_hardware_generation: Option<String>,
255}
256
257impl IcNodeStatusRow {
258    /// Return the known classification of this row's raw status.
259    #[must_use]
260    pub fn operational_status(&self) -> IcNodeOperationalStatus {
261        IcNodeOperationalStatus::from_raw(&self.status)
262    }
263
264    /// Return whether the raw row is anything other than known `UP`.
265    #[must_use]
266    pub fn is_non_up(&self) -> bool {
267        self.operational_status() != IcNodeOperationalStatus::Up
268    }
269}
270
271///
272/// IcNodeStatusCacheEvidence
273///
274/// Caller-relative local cache evidence attached to a projected status report.
275///
276
277#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
278pub struct IcNodeStatusCacheEvidence {
279    /// Canonical local cache path used by the report.
280    pub cache_path: String,
281    /// Whether the cache is within the default age policy for this caller's time.
282    pub cache_fresh: bool,
283    /// Cache age at report construction.
284    pub age_seconds: u64,
285    /// Age threshold used to classify freshness.
286    pub stale_after_seconds: u64,
287}
288
289///
290/// IcNodeStatusObservation
291///
292/// Shared source, scope, and optional cache evidence for status reports.
293///
294
295#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
296pub struct IcNodeStatusObservation {
297    #[serde(flatten)]
298    /// Official Dashboard source provenance.
299    pub source: IcDashboardReportProvenance,
300    /// Explicit node collection scope.
301    pub scope: IcNodeStatusScope,
302    /// Whether cloud-engine nodes were included in the source collection.
303    pub cloud_engine_nodes_included: bool,
304    /// Local cache evidence, absent for a pure live snapshot.
305    pub cache: Option<IcNodeStatusCacheEvidence>,
306}
307
308///
309/// IcNodeStatusSnapshot
310///
311/// Complete canonical observed node snapshot used by every status projection.
312///
313
314#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
315pub struct IcNodeStatusSnapshot {
316    #[serde(flatten)]
317    /// Shared source and scope evidence.
318    pub observation: IcNodeStatusObservation,
319    /// Canonically ordered raw node rows.
320    pub nodes: Vec<IcNodeStatusRow>,
321}
322
323///
324/// IcNodeStatusSourceData
325///
326/// Untrusted raw node rows and provenance returned by a Dashboard source capability.
327///
328
329#[cfg(feature = "dashboard-host")]
330#[derive(Clone, Debug, Eq, PartialEq)]
331pub struct IcNodeStatusSourceData {
332    /// Source-call provenance echoed by the source.
333    pub source: crate::ic::IcSourceRequest,
334    /// Explicit Dashboard collection scope.
335    pub scope: IcNodeStatusScope,
336    /// Whether the source claims cloud-engine node inclusion.
337    pub cloud_engine_nodes_included: bool,
338    /// Raw observed node rows.
339    pub nodes: Vec<IcNodeStatusRow>,
340}
341
342///
343/// IcNodeStatusView
344///
345/// Target and attention selection shared by node, Subnet, and provider views.
346///
347
348#[derive(Clone, Debug, Default, Eq, PartialEq)]
349pub struct IcNodeStatusView {
350    /// Optional exact identifier or unique principal prefix.
351    pub target: Option<String>,
352    /// Whether fully-up rows or groups are included without a target.
353    pub include_all: bool,
354}
355
356impl IcNodeStatusView {
357    /// Construct the default attention-only view.
358    #[must_use]
359    pub const fn attention() -> Self {
360        Self {
361            target: None,
362            include_all: false,
363        }
364    }
365
366    /// Select one exact identifier or unique principal prefix.
367    #[must_use]
368    pub fn with_target(mut self, target: impl Into<String>) -> Self {
369        self.target = Some(target.into());
370        self
371    }
372
373    /// Include fully-up rows as well as attention rows.
374    #[must_use]
375    pub const fn with_all(mut self, include_all: bool) -> Self {
376        self.include_all = include_all;
377        self
378    }
379}
380
381///
382/// IcNodeStatusReport
383///
384/// Node-level view over one complete observed status snapshot.
385///
386
387#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
388pub struct IcNodeStatusReport {
389    #[serde(flatten)]
390    /// Shared source, scope, and cache evidence.
391    pub observation: IcNodeStatusObservation,
392    /// Total rows in the complete source snapshot.
393    pub snapshot_node_count: usize,
394    /// Snapshot-wide overall and assignment-partitioned totals.
395    pub counts: IcNodeStatusGroupCounts,
396    /// Whether the view includes fully-up rows.
397    pub include_all: bool,
398    /// Target text supplied by the caller.
399    pub requested_target: Option<String>,
400    /// Canonical target resolved by exact or unique-prefix matching.
401    pub resolved_target: Option<String>,
402    /// Stable label describing how the target resolved.
403    pub resolved_from: Option<String>,
404    /// Number of returned node rows.
405    pub returned_node_count: usize,
406    /// Selected canonical node rows.
407    pub nodes: Vec<IcNodeStatusRow>,
408}
409
410///
411/// IcSubnetStatusRow
412///
413/// Observed operational counts and conservative threshold evidence for one Subnet.
414///
415
416#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
417pub struct IcSubnetStatusRow {
418    /// Canonical Subnet principal.
419    pub subnet_id: String,
420    /// Operational-status totals for observed assigned nodes.
421    pub statuses: IcNodeStatusCounts,
422    /// Byzantine fault count `floor((n - 1) / 3)` for the observed membership size.
423    pub fault_tolerance_node_count: usize,
424    /// Additional down nodes required for the down count to exceed the derived threshold.
425    pub additional_down_nodes_to_exceed_fault_tolerance: usize,
426    /// Additional non-up nodes required for the conservative count to exceed the threshold.
427    pub additional_non_up_nodes_to_exceed_fault_tolerance: usize,
428    /// Whether the observed down count already exceeds the derived threshold.
429    pub down_fault_tolerance_exceeded: bool,
430    /// Whether the observed conservative non-up count already exceeds the threshold.
431    pub conservative_non_up_fault_tolerance_exceeded: bool,
432    /// Raw non-up node evidence in canonical node order.
433    pub non_up_nodes: Vec<IcNodeStatusRow>,
434}
435
436///
437/// IcSubnetStatusReport
438///
439/// Subnet-level operational view over one complete observed node snapshot.
440///
441
442#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
443pub struct IcSubnetStatusReport {
444    #[serde(flatten)]
445    /// Shared source, scope, and cache evidence.
446    pub observation: IcNodeStatusObservation,
447    /// Total rows in the complete source snapshot.
448    pub snapshot_node_count: usize,
449    /// Snapshot rows with an assigned Subnet.
450    pub assigned_node_count: usize,
451    /// Number of observed Subnets before view filtering.
452    pub subnet_count: usize,
453    /// Number of observed Subnets containing a non-up node.
454    pub attention_subnet_count: usize,
455    /// Whether fully-up Subnets are included without a target.
456    pub include_all: bool,
457    /// Target text supplied by the caller.
458    pub requested_target: Option<String>,
459    /// Canonical Subnet target resolved by exact or unique-prefix matching.
460    pub resolved_target: Option<String>,
461    /// Stable label describing how the target resolved.
462    pub resolved_from: Option<String>,
463    /// Number of returned Subnet rows.
464    pub returned_subnet_count: usize,
465    /// Canonically ordered selected Subnet rows.
466    pub subnets: Vec<IcSubnetStatusRow>,
467}
468
469///
470/// IcNodeProviderStatusRow
471///
472/// Assignment and raw operational counts for one observed node provider.
473///
474
475#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
476pub struct IcNodeProviderStatusRow {
477    /// Canonical node-provider principal.
478    pub node_provider_id: String,
479    /// Off-chain Dashboard provider name.
480    pub node_provider_name: String,
481    /// Operational-status and assignment totals for the provider.
482    pub counts: IcNodeStatusGroupCounts,
483    /// Unassigned up-node count compared with assigned up-node count.
484    pub unassigned_up_vs_assigned_up: IcNodeCountComparison,
485    /// Unassigned non-up-node count compared with assigned non-up-node count.
486    pub unassigned_non_up_vs_assigned_non_up: IcNodeCountComparison,
487    /// Raw non-up node evidence in canonical node order.
488    pub non_up_nodes: Vec<IcNodeStatusRow>,
489}
490
491///
492/// IcNodeProviderStatusReport
493///
494/// Node-provider operational view over one complete observed node snapshot.
495///
496
497#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
498pub struct IcNodeProviderStatusReport {
499    #[serde(flatten)]
500    /// Shared source, scope, and cache evidence.
501    pub observation: IcNodeStatusObservation,
502    /// Total rows in the complete source snapshot.
503    pub snapshot_node_count: usize,
504    /// Number of observed provider principals before view filtering.
505    pub provider_count: usize,
506    /// Number of provider groups containing a non-up node.
507    pub attention_provider_count: usize,
508    /// All-provider outcomes for unassigned up nodes compared with assigned up nodes.
509    pub unassigned_up_vs_assigned_up_provider_counts: IcNodeCountComparisonCounts,
510    /// All-provider outcomes for unassigned non-up nodes compared with assigned non-up nodes.
511    pub unassigned_non_up_vs_assigned_non_up_provider_counts: IcNodeCountComparisonCounts,
512    /// Whether fully-up providers are included without a target.
513    pub include_all: bool,
514    /// Target text supplied by the caller.
515    pub requested_target: Option<String>,
516    /// Canonical provider target resolved by exact or unique-prefix matching.
517    pub resolved_target: Option<String>,
518    /// Stable label describing how the target resolved.
519    pub resolved_from: Option<String>,
520    /// Number of returned provider rows.
521    pub returned_provider_count: usize,
522    /// Canonically ordered selected provider rows.
523    pub providers: Vec<IcNodeProviderStatusRow>,
524}
525
526///
527/// IcNodeStatusProjectionError
528///
529/// Failure to resolve or project a requested observed status view.
530///
531
532#[derive(Clone, Debug, Eq, PartialEq, ThisError)]
533pub enum IcNodeStatusProjectionError {
534    /// Observation provenance, raw rows, canonical ordering, or counts are invalid.
535    #[error("invalid observed node-status snapshot: {reason}")]
536    InvalidSnapshot {
537        /// Deterministic validation failure.
538        reason: String,
539    },
540    /// The supplied target is empty after trimming.
541    #[error("{kind} target must not be empty")]
542    EmptyTarget {
543        /// Projection kind being selected.
544        kind: &'static str,
545    },
546    /// No observed identifier matches the supplied target.
547    #[error("{kind} target {target:?} did not match the observed snapshot")]
548    UnknownTarget {
549        /// Projection kind being selected.
550        kind: &'static str,
551        /// Unmatched target text.
552        target: String,
553    },
554    /// More than one observed identifier matches the supplied prefix.
555    #[error("{kind} prefix {prefix:?} is ambiguous; matches: {matches:?}")]
556    AmbiguousTarget {
557        /// Projection kind being selected.
558        kind: &'static str,
559        /// Ambiguous principal prefix.
560        prefix: String,
561        /// Canonically ordered matching principals.
562        matches: Vec<String>,
563    },
564}
565
566///
567/// IcNodeStatusCacheRequest
568///
569/// Stable identity of one network-level observed node-status cache.
570///
571
572#[cfg(feature = "dashboard-host")]
573#[derive(Clone, Debug, Eq, PartialEq)]
574pub struct IcNodeStatusCacheRequest {
575    /// Root directory containing all `ic-query` caches.
576    pub cache_root: PathBuf,
577    /// Requested network name.
578    pub network: String,
579}
580
581#[cfg(feature = "dashboard-host")]
582impl IcNodeStatusCacheRequest {
583    /// Construct one observed node-status cache identity.
584    #[must_use]
585    pub fn new(cache_root: impl Into<PathBuf>, network: impl Into<String>) -> Self {
586        Self {
587            cache_root: cache_root.into(),
588            network: network.into(),
589        }
590    }
591}
592
593///
594/// IcNodeStatusRefreshRequest
595///
596/// Settings for one forced observed node-status snapshot refresh.
597///
598
599#[cfg(feature = "dashboard-host")]
600#[derive(Clone, Debug, Eq, PartialEq)]
601pub struct IcNodeStatusRefreshRequest {
602    /// Stable cache identity.
603    pub cache: IcNodeStatusCacheRequest,
604    /// Explicit Dashboard API base endpoint.
605    pub source_endpoint: String,
606    /// Caller-supplied observation time as Unix seconds.
607    pub now_unix_secs: u64,
608}
609
610#[cfg(feature = "dashboard-host")]
611impl IcNodeStatusRefreshRequest {
612    /// Construct one forced node-status snapshot refresh request.
613    #[must_use]
614    pub fn new(
615        cache_root: impl Into<PathBuf>,
616        network: impl Into<String>,
617        source_endpoint: impl Into<String>,
618        now_unix_secs: u64,
619    ) -> Self {
620        Self {
621            cache: IcNodeStatusCacheRequest::new(cache_root, network),
622            source_endpoint: source_endpoint.into(),
623            now_unix_secs,
624        }
625    }
626}
627
628///
629/// IcNodeStatusReadRequest
630///
631/// Cache-backed status-view request shared by node, Subnet, and provider reports.
632///
633
634#[cfg(feature = "dashboard-host")]
635#[derive(Clone, Debug, Eq, PartialEq)]
636pub struct IcNodeStatusReadRequest {
637    /// Live and cache settings used when refresh is required.
638    pub refresh: IcNodeStatusRefreshRequest,
639    /// Projection target and attention selection.
640    pub view: IcNodeStatusView,
641    /// Whether to force a live replacement before reading.
642    pub force_refresh: bool,
643}
644
645#[cfg(feature = "dashboard-host")]
646impl IcNodeStatusReadRequest {
647    /// Construct one stale-refresh status-view request.
648    #[must_use]
649    pub fn new(
650        cache_root: impl Into<PathBuf>,
651        network: impl Into<String>,
652        source_endpoint: impl Into<String>,
653        now_unix_secs: u64,
654    ) -> Self {
655        Self {
656            refresh: IcNodeStatusRefreshRequest::new(
657                cache_root,
658                network,
659                source_endpoint,
660                now_unix_secs,
661            ),
662            view: IcNodeStatusView::attention(),
663            force_refresh: false,
664        }
665    }
666
667    /// Apply one target and attention selection.
668    #[must_use]
669    pub fn with_view(mut self, view: IcNodeStatusView) -> Self {
670        self.view = view;
671        self
672    }
673
674    /// Select a forced refresh before projecting the report.
675    #[must_use]
676    pub const fn with_force_refresh(mut self, force_refresh: bool) -> Self {
677        self.force_refresh = force_refresh;
678        self
679    }
680}
681
682///
683/// IcNodeStatusRefreshReport
684///
685/// Result of atomically replacing the complete observed node-status cache.
686///
687
688#[cfg(feature = "dashboard-host")]
689#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
690pub struct IcNodeStatusRefreshReport {
691    /// Cache/report schema version.
692    pub schema_version: u32,
693    /// Network identity attached to the replacement.
694    pub network: String,
695    /// Explicit Dashboard endpoint queried.
696    pub source_endpoint: String,
697    /// Canonical UTC collection timestamp.
698    pub fetched_at: String,
699    /// Collector identity.
700    pub fetched_by: String,
701    /// Published cache path.
702    pub cache_path: String,
703    /// Sibling refresh-lock path.
704    pub refresh_lock_path: String,
705    /// Whether an existing complete snapshot was replaced.
706    pub replaced_existing_cache: bool,
707    /// Number of published node rows.
708    pub node_count: usize,
709    /// Published overall and assignment-partitioned status totals.
710    pub counts: IcNodeStatusGroupCounts,
711}
712
713///
714/// IcNodeStatusHostError
715///
716/// Host source, cache, and projection failures for observed node-status reports.
717///
718
719#[cfg(feature = "dashboard-host")]
720#[derive(Debug, ThisError)]
721pub enum IcNodeStatusHostError {
722    /// The observed Dashboard source supports only public mainnet identity.
723    #[error("observed IC node status supports only the mainnet `ic` network, not {network:?}")]
724    UnsupportedNetwork {
725        /// Unsupported requested network.
726        network: String,
727    },
728    /// Live-source or source-validation failure.
729    #[error(transparent)]
730    Source(#[from] crate::ic::IcHostError),
731    /// Pure projection failure.
732    #[error(transparent)]
733    Projection(#[from] IcNodeStatusProjectionError),
734    /// Strict cache load found no complete snapshot.
735    #[error("observed node-status cache is missing at {}", path.display())]
736    MissingCache {
737        /// Expected cache path.
738        path: PathBuf,
739    },
740    /// Existing cache snapshot-key identity does not match its path.
741    #[error(
742        "observed node-status cache identity mismatch at {}: {field} is {actual:?}, expected {expected:?}",
743        path.display()
744    )]
745    CacheIdentityMismatch {
746        /// Cache path that failed validation.
747        path: PathBuf,
748        /// Identity field that differs.
749        field: &'static str,
750        /// Required identity value.
751        expected: String,
752        /// Stored identity value.
753        actual: String,
754    },
755    /// Existing cache is structurally readable but semantically invalid.
756    #[error("invalid observed node-status cache at {}: {reason}", path.display())]
757    InvalidCache {
758        /// Cache path that failed validation.
759        path: PathBuf,
760        /// Deterministic validation failure.
761        reason: String,
762    },
763    /// Shared generic JSON, filesystem, or refresh-lock cache failure.
764    #[error(transparent)]
765    Cache(#[from] crate::cache_file::HostCacheError),
766}
ic_query/ic/node_status/model.rs

ic_query/ic/node_status/
model.rs
