use super::{Contact, PeerContacts};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(super) enum Silence {
Unreachable {
pid: u32,
},
Anonymous {
pid: u32,
},
Unattributed,
}
impl Silence {
pub(super) fn of(pid: Option<u32>, contacts: &PeerContacts) -> Self {
match (pid, contacts.from_pid(pid)) {
(Some(pid), Contact::None) => Self::Unreachable { pid },
(Some(pid), Contact::Anonymous) => Self::Anonymous { pid },
_ => Self::Unattributed,
}
}
}
pub(super) fn first_rung_evidence(evidence: Silence) -> String {
match evidence {
Silence::Unreachable { pid } => {
format!("nothing has connected to this shepherd from pid {pid}")
}
Silence::Anonymous { pid } => format!(
"pid {pid} has connected to this shepherd without naming a dog, so the restart is unlikely to help"
),
Silence::Unattributed => {
"this shepherd cannot tell which process opened a connection".to_string()
}
}
}
pub(super) fn stale_verdict(name: &str, evidence: Silence) -> String {
let seen = "a dog restarted for never answering this shepherd has still not answered it";
match evidence {
Silence::Unreachable { pid } => format!(
"{seen}, and nothing has ever connected to this shepherd's socket from its process (pid {pid}): \
the binary on disk cannot reach this shep either, so this dog is stale and will not be \
restarted again. Read its own log with `shep bleats {name}` for what it says about \
connecting, then rebuild or reinstall it and run `shep restart {name}`. A dog \
installed with cargo wants `cargo install <crate> --force`: its own version does \
not change when the shep it was built against does, so a plain `cargo install` \
reports the package already installed, builds nothing, and exits 0"
),
Silence::Anonymous { pid } => format!(
"{seen}, but its process (pid {pid}) HAS connected to this shepherd — every time without \
naming a dog in its handshake, which is the only thing this shepherd waits for. The dog \
is reaching shep and may be serving every request it is asked; reinstalling the same \
build will NOT change that. It is built against shep-client older than 0.1.23, or it \
connects with `Client::connect` instead of `ReconnectingClient::connect_as_dog`. Rebuild \
it against shep-client 0.1.23 or newer, then run `shep restart {name}`. With cargo \
that means `cargo install <crate> --force`: the dog's own version does not change \
when its shep-client does, so a plain `cargo install` builds nothing and exits 0. \
It will not be restarted again in the meantime, and it goes on running"
),
Silence::Unattributed => format!(
"{seen}, and this shepherd could not tell which process opened its connections, so it \
cannot say which of two things is wrong. Either the dog is not reaching the socket at \
all — rebuild or reinstall it — or it is reaching it and never names itself in the \
handshake, which means a build against shep-client older than 0.1.23 and which \
reinstalling the same build will not fix. Run `shep bleats {name}` to tell them apart: \
a dog that cannot reach the socket says so in its own log, and one that is connected \
and merely anonymous does not. It will not be restarted again"
),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_stale_verdict_claims_only_what_this_shepherd_watched() {
let unreachable = stale_verdict("metrics", Silence::Unreachable { pid: 900 });
assert!(
unreachable.contains("nothing has ever connected"),
"the reinstall advice has to be earned by an observation: {unreachable}"
);
assert!(unreachable.contains("pid 900"), "{unreachable}");
assert!(
unreachable.contains("rebuild or reinstall it"),
"a dog that never reached the socket is the case reinstalling does fix: {unreachable}"
);
let anonymous = stale_verdict("log-rotate", Silence::Anonymous { pid: 901 });
assert!(
!anonymous.contains("cannot reach this shep"),
"this dog reached shep; claiming otherwise is the whole defect: {anonymous}"
);
assert!(
anonymous.contains("reinstalling the same build will NOT"),
"the two days were spent on advice this line has to refuse: {anonymous}"
);
assert!(
anonymous.contains("0.1.23"),
"the fix is a newer shep-client, and the message has to name it: {anonymous}"
);
assert!(
anonymous.contains("`shep restart log-rotate`"),
"every verdict ends in something the reader can run: {anonymous}"
);
let unattributed = stale_verdict("metrics", Silence::Unattributed);
for verdict in [&unreachable, &anonymous] {
assert!(
verdict.contains("`cargo install <crate> --force`"),
"an actionable verdict must carry the whole forced reinstall command: {verdict}"
);
}
assert!(
unattributed.contains("could not tell which process"),
"not knowing has to be said rather than papered over: {unattributed}"
);
assert!(
unattributed.contains("`shep bleats metrics`"),
"the one command that separates the two candidates: {unattributed}"
);
for verdict in [&unreachable, &anonymous, &unattributed] {
assert!(
!verdict.contains("the binary on disk cannot talk to this shep either"),
"the sentence that was asserted on every path is gone: {verdict}"
);
}
}
#[tokio::test(start_paused = true)]
async fn evidence_is_read_off_the_record_and_never_guessed() {
let contacts = PeerContacts::new();
tokio::time::advance(super::super::contacts::PEER_CONTACT_WARMUP * 2).await;
contacts.connected(11);
contacts.named_a_dog(12);
assert_eq!(
Silence::of(Some(10), &contacts),
Silence::Unreachable { pid: 10 }
);
assert_eq!(
Silence::of(Some(11), &contacts),
Silence::Anonymous { pid: 11 }
);
assert_eq!(
Silence::of(Some(12), &contacts),
Silence::Unattributed,
"a pid that named a dog and is silent anyway is a contradiction, not a diagnosis"
);
assert_eq!(
Silence::of(None, &contacts),
Silence::Unattributed,
"no pid is no attribution, which is a different answer from no contact"
);
}
}