Skip to main content

federation_net/
health.rs

1//! Point-in-time health information for the transport and rendezvous loop.
2
3use std::fmt;
4use std::time::Duration;
5
6/// Coarse health state of a running network engine.
7#[derive(Debug, Clone, Copy, PartialEq, Eq)]
8pub enum NetworkHealthState {
9    /// The engine is starting or has no discovery mechanism configured.
10    Discovering,
11    /// Transport and rendezvous maintenance are operating normally.
12    Healthy,
13    /// A recent rendezvous operation failed and is being retried.
14    Recovering,
15    /// Repeated rendezvous failures indicate that the engine should be restarted.
16    Degraded,
17}
18
19impl NetworkHealthState {
20    /// Returns a compact stable label for logs and user interfaces.
21    pub fn as_str(self) -> &'static str {
22        match self {
23            Self::Discovering => "discovering",
24            Self::Healthy => "healthy",
25            Self::Recovering => "recovering",
26            Self::Degraded => "degraded",
27        }
28    }
29}
30
31impl fmt::Display for NetworkHealthState {
32    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
33        f.write_str(self.as_str())
34    }
35}
36
37/// Point-in-time health snapshot of a running network engine.
38///
39/// Zero connected peers is not itself an error: a network may legitimately
40/// contain only one online node. [`Self::restart_recommended`] is therefore
41/// based on repeated discovery failures as well as the absence of peers.
42#[derive(Debug, Clone, PartialEq, Eq)]
43pub struct NetworkHealthSnapshot {
44    /// Coarse state suitable for logs and user interfaces.
45    pub state: NetworkHealthState,
46    /// Number of currently connected peers.
47    pub connected_peers: usize,
48    /// Whether Mainline-DHT rendezvous discovery is enabled.
49    pub rendezvous_enabled: bool,
50    /// Consecutive failed or timed-out rendezvous rounds.
51    pub consecutive_rendezvous_failures: u32,
52    /// Consecutive rendezvous rounds in which every discovered peer dial failed.
53    pub consecutive_peer_dial_failures: u32,
54    /// Number of times the rendezvous client was rebuilt after failures.
55    pub rendezvous_restarts: u64,
56    /// Time elapsed since the most recent successful rendezvous round.
57    pub last_rendezvous_success_ago: Option<Duration>,
58    /// Most recent rendezvous error, if a later successful round has not cleared it.
59    pub last_rendezvous_error: Option<String>,
60    /// Whether an application-owned full service restart is advisable.
61    pub restart_recommended: bool,
62}