Skip to main content

shep_client/reconnect/
link_state.rs

1use core::fmt;
2use std::time::Duration;
3
4/// What a [`ReconnectingClient`](crate::reconnect::ReconnectingClient)'s supervisor is currently doing.
5///
6/// Non-exhaustive: expect more variants.
7#[derive(Debug, Clone, PartialEq, Eq)]
8#[non_exhaustive]
9pub enum LinkState {
10    /// Connected. Requests go out on this generation of the connection.
11    Connected,
12    /// The connection dropped and the supervisor is re-establishing it.
13    /// Requests issued now fail with [`RequestError::Closed`](crate::client::RequestError::Closed); they are not
14    /// queued and not retried.
15    Reconnecting,
16    /// A successor refused the handshake on protocol-version skew. The
17    /// supervisor has stopped, and every later request fails with
18    /// [`RequestError::Closed`](crate::client::RequestError::Closed): the daemon that refused is the party
19    /// that can fix it, not a retry.
20    Refused {
21        /// The daemon's own crate version, when it named one. `None` from a
22        /// daemon built before the refusal carried it.
23        daemon_version: Option<String>,
24        /// The daemon's refusal message, verbatim.
25        message: String,
26    },
27}
28
29/// Why a bounded wait on the link ended with the link still down.
30///
31/// Non-exhaustive: expect more variants.
32#[derive(Debug, Clone, PartialEq, Eq)]
33#[must_use = "which of the two it was decides whether a dog exits unreachable or refused"]
34#[non_exhaustive]
35pub enum LinkLost {
36    /// The wait ran out with the supervisor still dialling.
37    Budget {
38        /// How long the caller waited before giving up.
39        waited: Duration,
40    },
41    /// A successor refused the handshake on protocol-version skew, so the
42    /// supervisor has stopped and no further wait could succeed.
43    Refused {
44        /// The daemon's own crate version, when it named one. `None` from a
45        /// daemon built before the refusal carried it.
46        daemon_version: Option<String>,
47        /// The daemon's refusal message, verbatim.
48        message: String,
49    },
50}
51
52impl LinkLost {
53    /// The [`shep_core::exit`] code a dog giving up on its shepherd uses.
54    ///
55    /// Not success: a dog nothing answered has not finished its work.
56    #[must_use]
57    pub const fn exit_code(&self) -> u8 {
58        use shep_core::exit;
59        match self {
60            Self::Refused { .. } => exit::PROTOCOL_MISMATCH,
61            Self::Budget { .. } => exit::DAEMON_UNREACHABLE,
62        }
63    }
64}
65
66impl fmt::Display for LinkLost {
67    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
68        match self {
69            Self::Budget { waited } => write!(f, "no shepherd answered within {waited:?}"),
70            Self::Refused { message, .. } => {
71                write!(f, "the shepherd refused this connection: {message}")
72            }
73        }
74    }
75}
76
77impl core::error::Error for LinkLost {}
78
79// Exhaustive on purpose, unlike `LinkState`: the question is binary, and a
80// caller branching on it is better served by a match a third variant would
81// break than by a wildcard arm that goes on compiling.
82/// Whether a [`Client::reconnect`](crate::client::Client::reconnect) reached the daemon it was talking to
83/// before, or a different one.
84///
85/// See this module's own docs for how the two are told apart.
86#[derive(Debug, Clone, Copy, PartialEq, Eq)]
87#[must_use = "the verdict says whether ids held from before the reconnect still mean anything"]
88pub enum Reconnected {
89    /// The daemon now answering is the one that answered before, so an id
90    /// minted before the connection dropped still names the same sheep.
91    ///
92    /// It says nothing about the connection. The old generation and the
93    /// subscription on it died under either verdict, so a caller wanting
94    /// events subscribes again whichever one it gets.
95    SameDaemon,
96    /// A different daemon is answering, minting ids from its own fresh
97    /// space. Every id the caller still holds names nothing here.
98    NewDaemon,
99}
100
101#[cfg(test)]
102mod tests {
103
104    use std::time::Duration;
105
106    use super::*;
107
108    /// fails if a refusal reaches an operator as a timeout, which would
109    /// send them looking for a shepherd that is running and answering.
110    #[test]
111    fn a_lost_link_says_which_of_the_two_it_was() {
112        let budget = LinkLost::Budget {
113            waited: Duration::from_secs(5),
114        };
115        assert_eq!(budget.to_string(), "no shepherd answered within 5s");
116
117        let refused = LinkLost::Refused {
118            daemon_version: Some("0.9.9".into()),
119            message: "daemon speaks protocol 3, client speaks 2".into(),
120        };
121        assert_eq!(
122            refused.to_string(),
123            "the shepherd refused this connection: daemon speaks protocol 3, client speaks 2"
124        );
125    }
126
127    /// fails if `Reconnected` starts printing anything but its verdict. It
128    /// carries no payload, and a caller logging one must never begin
129    /// emitting a daemon's own details alongside it.
130    #[test]
131    fn reconnected_debug_is_the_verdict_and_nothing_else() {
132        assert_eq!(format!("{:?}", Reconnected::SameDaemon), "SameDaemon");
133        assert_eq!(format!("{:?}", Reconnected::NewDaemon), "NewDaemon");
134    }
135
136    #[test]
137    fn a_refused_link_exits_protocol_mismatch_and_a_spent_budget_unreachable() {
138        let refused = LinkLost::Refused {
139            daemon_version: None,
140            message: "too old".to_owned(),
141        };
142        let spent = LinkLost::Budget {
143            waited: Duration::from_secs(5),
144        };
145        assert_eq!(refused.exit_code(), shep_core::exit::PROTOCOL_MISMATCH);
146        assert_eq!(spent.exit_code(), shep_core::exit::DAEMON_UNREACHABLE);
147    }
148}