use core::fmt;
use std::path::{Path, PathBuf};
use shep_core::barks::{self, Bark};
use shep_core::config::{AppConfig, DaemonConfig, ResolvedApp, normalize};
use shep_core::paths::ShepPaths;
use shep_core::protocol::{BusEvent, DogSource, ProcessEventKind};
use tokio::sync::broadcast::{self, error::RecvError};
use crate::supervisor::SupervisorHandle;
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DogSpec {
pub name: String,
pub source: DogSource,
}
#[non_exhaustive]
#[derive(Debug)]
pub enum DogError {
NoBinary(std::io::Error),
UnsupportedSource(String),
Config(String),
Io(std::io::Error),
}
impl fmt::Display for DogError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::NoBinary(err) => write!(f, "this binary's own path is unreadable: {err}"),
Self::UnsupportedSource(source) => {
write!(f, "no way to spawn a dog from source {source}")
}
Self::Config(msg) => write!(f, "dog configuration is unusable: {msg}"),
Self::Io(err) => write!(f, "dog configuration could not be read: {err}"),
}
}
}
impl core::error::Error for DogError {
fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
match self {
Self::NoBinary(err) | Self::Io(err) => Some(err),
Self::UnsupportedSource(_) | Self::Config(_) => None,
}
}
}
pub fn dog_app(spec: &DogSpec, paths: &ShepPaths) -> Result<ResolvedApp, DogError> {
let (script, args) = match &spec.source {
DogSource::BuiltIn => (
std::env::current_exe()
.map_err(DogError::NoBinary)?
.display()
.to_string(),
vec!["dog".to_string(), spec.name.clone()],
),
DogSource::Adopted { path } => (path.clone(), Vec::new()),
source => return Err(DogError::UnsupportedSource(format!("{source:?}"))),
};
let mut config = AppConfig::minimal(&spec.name, &script);
config.args = args;
config
.env
.insert("SHEP_HOME".to_string(), paths.home.display().to_string());
normalize(config).map_err(|err| DogError::Config(err.to_string()))
}
pub async fn spawn_enabled_dogs(
specs: &[DogSpec],
paths: &ShepPaths,
supervisor: &SupervisorHandle,
) {
for spec in specs {
let app = match dog_app(spec, paths) {
Ok(app) => app,
Err(err) => {
tracing::warn!(dog = %spec.name, %err, "a dog did not start");
continue;
}
};
match supervisor.start_dog(app, spec.source.clone()).await {
Ok(info) if info.dog.is_none() => tracing::warn!(
dog = %spec.name,
"a sheep is already registered under this name; the dog did not start"
),
Ok(_) => {}
Err(err) => tracing::warn!(dog = %spec.name, %err, "a dog did not start"),
}
}
}
pub fn dog_section(path: &Path, name: &str) -> Result<String, DogError> {
let source = match std::fs::read_to_string(path) {
Ok(source) => source,
Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(String::new()),
Err(err) => return Err(DogError::Io(err)),
};
let config = DaemonConfig::load(Some(&source), &|_| None)
.map_err(|err| DogError::Config(err.to_string()))?;
match config.dog.get(name) {
None => Ok(String::new()),
Some(table) => toml::to_string(table).map_err(|err| DogError::Config(err.to_string())),
}
}
pub fn spawn_dog_watch(
mut events: broadcast::Receiver<BusEvent>,
barks: PathBuf,
) -> tokio::task::JoinHandle<()> {
tokio::spawn(async move {
loop {
match events.recv().await {
Ok(BusEvent::Process {
event: ProcessEventKind::Errored,
info,
..
}) if info.dog.is_some() => {
record_dog_errored(&barks, &info.name, info.restarts);
}
Ok(_) => {}
Err(RecvError::Lagged(count)) => {
tracing::warn!(
count,
"the shepherd's dog watch dropped bus events; a dog's exhausted restart budget may have gone unrecorded"
);
}
Err(RecvError::Closed) => break,
}
}
})
}
fn record_dog_errored(barks_path: &Path, name: &str, restarts: u32) {
let budget = AppConfig::default().max_restarts;
tracing::error!(dog = %name, restarts, budget, "a dog exhausted its restart budget");
let bark = Bark {
at_ms: crate::now_ms(),
rule: "daemon".to_string(),
subject: name.to_string(),
message: format!(
"dog {name} exhausted its restart budget: {restarts} restarts against a budget of {budget}"
),
sinks: Vec::new(),
};
if let Err(err) = barks::append(barks_path, &bark, barks::DEFAULT_MAX_BYTES) {
tracing::warn!(%err, dog = %name, "failed to record a dog's exhausted restart budget");
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::testing::test_paths;
use shep_core::protocol::ProcessInfo;
use shep_core::status::ProcStatus;
#[test]
fn a_dogs_child_environment_carries_shep_home_and_no_configuration() {
let dir = tempfile::tempdir().unwrap();
let paths = test_paths(&dir);
std::fs::write(
&paths.daemon_config,
"[dog.bark]\nwebhook = \"https://example.invalid/hook\"\n",
)
.unwrap();
let spec = DogSpec {
name: "bark".to_string(),
source: DogSource::BuiltIn,
};
let app = dog_app(&spec, &paths).unwrap();
let assembled = crate::assemble::assemble(&app, 0, &paths, None);
assert_eq!(
assembled.env.get("SHEP_HOME"),
Some(&paths.home.display().to_string())
);
assert!(
!assembled
.env
.values()
.any(|v| v.contains("example.invalid")),
"a dog's configuration never travels in its environment: {:?}",
assembled.env
);
}
#[test]
fn a_built_in_dog_runs_this_binary_and_an_adopted_one_runs_its_own() {
let dir = tempfile::tempdir().unwrap();
let paths = test_paths(&dir);
let built_in = dog_app(
&DogSpec {
name: "metrics".to_string(),
source: DogSource::BuiltIn,
},
&paths,
)
.unwrap();
assert_eq!(
built_in.config().script,
std::env::current_exe().unwrap().display().to_string()
);
assert_eq!(built_in.config().args, vec!["dog", "metrics"]);
let adopted = dog_app(
&DogSpec {
name: "otel".to_string(),
source: DogSource::Adopted {
path: "/usr/local/bin/shep-otel".to_string(),
},
},
&paths,
)
.unwrap();
assert_eq!(adopted.config().script, "/usr/local/bin/shep-otel");
assert!(adopted.config().args.is_empty());
assert_eq!(
adopted.config().name,
"otel",
"the NAME is the config key, never the filename"
);
}
#[test]
fn a_dogs_section_comes_back_as_its_own_table_and_nothing_else() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("shep.toml");
std::fs::write(
&path,
"[daemon]\nlog_json = true\n\n[dog.bark]\ndebounce = \"30s\"\n\n[dog.metrics]\nport = 9615\n",
)
.unwrap();
let bark = dog_section(&path, "bark").unwrap();
assert!(bark.contains("debounce"));
assert!(
!bark.contains("9615"),
"one dog never sees another's config"
);
assert!(!bark.contains("log_json"), "nor the daemon's own");
let parsed: toml::Table = toml::from_str(&bark).unwrap();
assert_eq!(parsed["debounce"].as_str(), Some("30s"));
assert_eq!(dog_section(&path, "absent").unwrap(), "");
assert_eq!(
dog_section(&dir.path().join("gone.toml"), "bark").unwrap(),
""
);
}
fn process_event(name: &str, kind: ProcessEventKind, dog: Option<DogSource>) -> BusEvent {
BusEvent::Process {
event: kind,
info: ProcessInfo::builder(1, name, ProcStatus::Errored)
.restarts(16)
.dog(dog)
.build(),
manually: false,
at_ms: 1_700_000_000_000,
}
}
fn errored_event(name: &str, dog: Option<DogSource>) -> BusEvent {
process_event(name, ProcessEventKind::Errored, dog)
}
async fn await_barks(path: &std::path::Path, n: usize) -> Vec<Bark> {
tokio::time::timeout(std::time::Duration::from_secs(2), async {
loop {
let found = barks::read(path).unwrap_or_default();
if found.len() >= n {
return found;
}
tokio::time::sleep(std::time::Duration::from_millis(10)).await;
}
})
.await
.expect("barks.jsonl never reached the expected record count")
}
#[tokio::test]
async fn the_shepherd_records_a_dog_that_gave_up_and_leaves_the_sheep_to_bark() {
let dir = tempfile::tempdir().unwrap();
let barks_path = dir.path().join("barks.jsonl");
let (events, rx) = broadcast::channel(16);
let watch = spawn_dog_watch(rx, barks_path.clone());
events.send(errored_event("web", None)).unwrap();
events
.send(errored_event("bark", Some(DogSource::BuiltIn)))
.unwrap();
let recorded = await_barks(&barks_path, 1).await;
assert_eq!(recorded.len(), 1, "one record, and it is the dog's");
assert_eq!(recorded[0].subject, "bark");
assert_eq!(recorded[0].rule, "daemon");
assert!(
recorded[0].sinks.is_empty(),
"the shepherd has no sinks and says so by carrying none"
);
watch.abort();
}
#[tokio::test]
async fn a_dog_that_merely_exited_is_not_recorded() {
let dir = tempfile::tempdir().unwrap();
let barks_path = dir.path().join("barks.jsonl");
let (events, rx) = broadcast::channel(16);
let watch = spawn_dog_watch(rx, barks_path.clone());
events
.send(process_event(
"bark",
ProcessEventKind::Exit,
Some(DogSource::BuiltIn),
))
.unwrap();
events
.send(errored_event("bark", Some(DogSource::BuiltIn)))
.unwrap();
let recorded = await_barks(&barks_path, 1).await;
assert_eq!(
recorded.len(),
1,
"the Exit left no record; only the Errored that followed it did"
);
watch.abort();
}
}