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}