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}