use core::fmt;
use std::collections::BTreeMap;
use std::collections::BTreeSet;
use std::path::PathBuf;
use shep_core::config::template::RenderError;
use shep_core::config::{AppConfig, ResolvedApp, normalize};
use shep_core::paths::ShepPaths;
use shep_core::protocol::DogSource;
use shep_core::protocol::ProcessInfo;
use shep_core::status::ProcStatus;
use crate::bus::Bus;
use crate::supervisor::SupervisorHandle;
use super::narrate::narrate;
use super::secrets::StoreFault;
#[derive(Clone, PartialEq, Eq)]
pub struct DogSpec {
pub name: String,
pub source: DogSource,
pub env: BTreeMap<String, String>,
}
impl fmt::Debug for DogSpec {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
f,
"DogSpec {{ name: {:?}, source: {:?}, env: <{} keys> }}",
self.name,
self.source,
self.env.len()
)
}
}
#[must_use]
pub fn built_in_dog_refusal(name: &str) -> String {
format!("{name} is built in: `shep disable {name}`")
}
#[non_exhaustive]
#[derive(Debug)]
pub enum DogError {
NoBinary(std::io::Error),
UnsupportedSource(String),
Config(String),
Io(std::io::Error),
Reference {
key_path: String,
source: RenderError,
},
SecretStore {
key_path: String,
fault: StoreFault,
},
}
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 unresolvable: {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}"),
Self::Reference { key_path, source } => write!(f, "`{key_path}`: {source}"),
Self::SecretStore { key_path, fault } => write!(
f,
"`{key_path}`: the secret store could not be read ({fault})"
),
}
}
}
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::Reference { source, .. } => Some(source),
Self::UnsupportedSource(_) | Self::Config(_) | Self::SecretStore { .. } => None,
}
}
}
#[cfg(unix)]
fn builtin_program() -> Result<PathBuf, DogError> {
crate::handover::exec_target().map_err(DogError::NoBinary)
}
#[cfg(windows)]
fn builtin_program() -> Result<PathBuf, DogError> {
std::env::current_exe().map_err(DogError::NoBinary)
}
pub fn dog_app(spec: &DogSpec, paths: &ShepPaths) -> Result<ResolvedApp, DogError> {
let (script, args, channel) = match &spec.source {
DogSource::BuiltIn { .. } => (
builtin_program()?.display().to_string(),
vec!["dog".to_string(), spec.name.clone()],
false,
),
DogSource::Adopted { path, channel, .. } => (path.clone(), Vec::new(), *channel),
source => return Err(DogError::UnsupportedSource(format!("{source:?}"))),
};
let mut config = AppConfig::minimal(&spec.name, &script);
config.args = args;
config.channel = channel;
config.shutdown_with_message = channel;
config.env.extend(spec.env.clone());
config
.env
.insert("SHEP_HOME".to_string(), paths.home.display().to_string());
config
.env
.insert(shep_core::dogs::DOG_NAME_VAR.to_string(), spec.name.clone());
normalize(config).map_err(|err| DogError::Config(err.to_string()))
}
pub async fn register_dogs_at_rest(
known: &[DogSpec],
enabled: &[DogSpec],
paths: &ShepPaths,
supervisor: &SupervisorHandle,
) {
let mut seen = BTreeSet::new();
let mut dogs = Vec::new();
for spec in enabled.iter().chain(known) {
if !seen.insert(spec.name.as_str()) {
continue;
}
match dog_app(spec, paths) {
Ok(app) => dogs.push((app, spec.source.clone())),
Err(err) => tracing::warn!(dog = %spec.name, %err, "a dog was not listed"),
}
}
let disabled: BTreeSet<String> = known
.iter()
.map(|spec| spec.name.clone())
.filter(|name| !enabled.iter().any(|spec| spec.name == *name))
.collect();
if let Err(err) = supervisor.register_dogs_at_rest(dogs, disabled).await {
tracing::warn!(%err, "the dogs were not listed");
return;
}
let flock = match supervisor.list_checked().await {
Ok(flock) => flock,
Err(err) => {
tracing::warn!(%err, "the flock could not be read to check its dogs against");
return;
}
};
stop_unenabled_dogs(&flock, enabled, supervisor).await;
}
async fn stop_unenabled_dogs(
flock: &[ProcessInfo],
enabled: &[DogSpec],
supervisor: &SupervisorHandle,
) {
for info in flock {
let named = enabled.iter().any(|spec| spec.name == info.name);
let parked = info.disabled == Some(true) && info.status == ProcStatus::Stopped;
if info.dog.is_none() || named || parked {
continue;
}
if let Err(err) = supervisor.disable_dog(info.name.clone()).await {
tracing::warn!(
dog = %info.name,
%err,
"a dog this shepherd's config does not enable was left running"
);
}
}
}
pub async fn spawn_enabled_dogs(
specs: &[DogSpec],
paths: &ShepPaths,
supervisor: &SupervisorHandle,
events: &Bus,
) {
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;
}
};
let script = app.config().script.clone();
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(info) => {
narrate(
events,
&info,
&format!("shep has this dog enabled, running the binary at {script}"),
)
.await;
}
Err(err) => tracing::warn!(dog = %spec.name, %err, "a dog did not start"),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::runner::SpawnSpec;
use crate::testing::test_paths;
use shep_core::secrets::SecretView;
#[cfg(unix)]
#[test]
fn a_built_in_dogs_program_is_the_resolved_exec_target_and_never_a_deleted_inode() {
let program = builtin_program().expect("the test binary resolves");
assert_eq!(program, crate::handover::exec_target().unwrap());
assert!(program.is_file(), "{}", program.display());
assert!(
!program.to_string_lossy().ends_with(" (deleted)"),
"{}",
program.display()
);
}
#[test]
fn an_unresolvable_binary_says_so_and_keeps_the_refusal_as_its_source() {
use core::error::Error as _;
let refusal = std::io::Error::new(std::io::ErrorKind::NotFound, "no binary to exec");
let err = DogError::NoBinary(refusal);
assert_eq!(
err.to_string(),
"this binary's own path is unresolvable: no binary to exec"
);
assert_eq!(err.source().unwrap().to_string(), "no binary to exec");
}
#[test]
fn a_dogs_child_environment_carries_shep_home_and_its_name_and_no_section() {
let dir = tempfile::tempdir().unwrap();
let paths = test_paths(&dir);
std::fs::write(
&paths.dogs_config,
"[bark]\nwebhook = \"https://example.invalid/hook\"\n",
)
.unwrap();
let spec = DogSpec {
name: "bark".to_string(),
source: DogSource::BuiltIn {
grants: None,
events: Vec::new(),
},
env: BTreeMap::new(),
};
let app = dog_app(&spec, &paths).unwrap();
let assembled = crate::assemble::assemble(
&app,
0,
&paths,
None,
&shep_core::secrets::SecretView::empty("production".to_string()),
)
.expect("a dog's own config carries no template to refuse");
assert_eq!(
assembled.env.get("SHEP_HOME"),
Some(&paths.home.display().to_string())
);
assert_eq!(
assembled.env.get("SHEP_DOG_NAME"),
Some(&"bark".to_string()),
"a dog is told the name its own section lives under"
);
assert!(
!assembled
.env
.values()
.any(|v| v.contains("example.invalid")),
"a dog's configuration never travels in its environment: {:?}",
assembled.env
);
}
#[test]
fn an_adopted_dogs_env_reaches_its_child_environment() {
let dir = tempfile::tempdir().unwrap();
let paths = test_paths(&dir);
let spec = adopted(
"kelpie",
BTreeMap::from([
("PADDOCK_KEY".to_string(), "lease-key".to_string()),
("RUST_LOG".to_string(), "warn".to_string()),
]),
);
let assembled = spawn_env(&spec, &paths, &SecretView::empty("production".to_string()));
assert_eq!(
assembled.env.get("PADDOCK_KEY"),
Some(&"lease-key".to_string()),
"the operator's key reaches the dog that asked for one"
);
assert_eq!(assembled.env.get("RUST_LOG"), Some(&"warn".to_string()));
assert_eq!(
assembled.env.get("SHEP_HOME"),
Some(&paths.home.display().to_string())
);
assert_eq!(
assembled.env.get("SHEP_DOG_NAME"),
Some(&"kelpie".to_string())
);
}
#[test]
fn an_adopted_dogs_env_secret_arrives_resolved() {
let dir = tempfile::tempdir().unwrap();
let paths = test_paths(&dir);
let spec = adopted(
"kelpie",
BTreeMap::from([(
"PADDOCK_KEY".to_string(),
"{{secret:PADDOCK_KEY}}".to_string(),
)]),
);
let view = SecretView::new(
"production".to_string(),
BTreeMap::from([(
"PADDOCK_KEY".to_string(),
BTreeMap::from([("production".to_string(), "gateway-key".to_string())]),
)]),
shep_core::secrets::ProviderCache::default(),
);
let assembled = spawn_env(&spec, &paths, &view);
assert_eq!(
assembled.env.get("PADDOCK_KEY"),
Some(&"gateway-key".to_string())
);
assert!(
!assembled.env.values().any(|v| v.contains("{{secret:")),
"no reference reaches the child once the store has answered: {:?}",
assembled.env
);
}
#[test]
fn an_adopted_dogs_env_secret_the_store_cannot_answer_refuses_the_spawn() {
let dir = tempfile::tempdir().unwrap();
let paths = test_paths(&dir);
let spec = adopted(
"kelpie",
BTreeMap::from([("PADDOCK_KEY".to_string(), "{{secret:ABSENT}}".to_string())]),
);
let app = dog_app(&spec, &paths).expect("the reference grammar is valid");
let err = crate::assemble::assemble(
&app,
0,
&paths,
None,
&SecretView::empty("production".to_string()),
)
.expect_err("no value for ABSENT");
assert!(
matches!(
err,
crate::assemble::AssembleError::Template { ref field, .. } if field == "PADDOCK_KEY"
),
"{err:?}"
);
}
#[test]
fn a_dogs_env_cannot_replace_shep_home_or_the_name_it_was_registered_under() {
let dir = tempfile::tempdir().unwrap();
let paths = test_paths(&dir);
let spec = adopted(
"kelpie",
BTreeMap::from([
("SHEP_HOME".to_string(), "/home/ada/elsewhere".to_string()),
("SHEP_DOG_NAME".to_string(), "someone-else".to_string()),
]),
);
let assembled = spawn_env(&spec, &paths, &SecretView::empty("production".to_string()));
assert_eq!(
assembled.env.get("SHEP_HOME"),
Some(&paths.home.display().to_string()),
"the shepherd's own home is not the operator's to rename"
);
assert_eq!(
assembled.env.get("SHEP_DOG_NAME"),
Some(&"kelpie".to_string())
);
}
#[test]
fn a_dogs_env_cannot_claim_a_name_the_shepherd_injects_into_every_child() {
let dir = tempfile::tempdir().unwrap();
let paths = test_paths(&dir);
let spec = adopted(
"kelpie",
BTreeMap::from([("SHEP_NAME".to_string(), "x".to_string())]),
);
let err = dog_app(&spec, &paths).expect_err("SHEP_NAME is reserved");
assert!(matches!(err, DogError::Config(_)), "{err:?}");
assert!(err.to_string().contains("SHEP_NAME"), "{err}");
}
#[test]
fn a_dogs_spec_debug_prints_its_name_and_source_and_no_env_value() {
let spec = adopted(
"kelpie",
BTreeMap::from([("PADDOCK_KEY".to_string(), "gateway-key".to_string())]),
);
assert_eq!(
format!("{spec:?}"),
"DogSpec { name: \"kelpie\", source: Adopted { path: \"/usr/local/bin/shep-kelpie\", \
channel: false, grants: None, events: [] }, env: <1 keys> }"
);
}
fn adopted(name: &str, env: BTreeMap<String, String>) -> DogSpec {
DogSpec {
name: name.to_string(),
source: DogSource::Adopted {
grants: None,
path: "/usr/local/bin/shep-kelpie".to_string(),
channel: false,
events: Vec::new(),
},
env,
}
}
fn spawn_env(spec: &DogSpec, paths: &ShepPaths, secrets: &SecretView) -> SpawnSpec {
let app = dog_app(spec, paths).expect("the fixture's config assembles");
crate::assemble::assemble(&app, 0, paths, None, secrets)
.expect("the fixture's spawn assembles")
}
#[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 {
grants: None,
events: Vec::new(),
},
env: BTreeMap::new(),
},
&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 {
grants: None,
path: "/usr/local/bin/shep-otel".to_string(),
channel: false,
events: Vec::new(),
},
env: BTreeMap::new(),
},
&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_own_log_lines_are_stamped() {
let dir = tempfile::tempdir().unwrap();
let spec = DogSpec {
name: "metrics".to_string(),
source: DogSource::BuiltIn {
grants: None,
events: Vec::new(),
},
env: BTreeMap::new(),
};
assert!(
dog_app(&spec, &test_paths(&dir))
.unwrap()
.config()
.log_timestamps
);
}
#[test]
fn only_an_adopted_dog_that_asked_gets_the_channel_and_a_stop_by_message() {
let dir = tempfile::tempdir().unwrap();
let paths = test_paths(&dir);
let adopted = |channel| DogSource::Adopted {
grants: None,
path: "/usr/local/bin/shep-otel".to_string(),
channel,
events: Vec::new(),
};
for (source, expected) in [
(adopted(true), true),
(adopted(false), false),
(
DogSource::BuiltIn {
grants: None,
events: Vec::new(),
},
false,
),
] {
let spec = DogSpec {
name: "otel".to_string(),
source: source.clone(),
env: BTreeMap::new(),
};
let app = dog_app(&spec, &paths).unwrap();
let config = app.config();
assert_eq!(config.channel, expected, "{source:?}");
assert_eq!(config.shutdown_with_message, expected, "{source:?}");
}
}
#[test]
fn an_adopted_dog_is_told_the_name_it_was_registered_under() {
let dir = tempfile::tempdir().unwrap();
let paths = test_paths(&dir);
let adopted = dog_app(
&DogSpec {
name: "telemetry".to_string(),
source: DogSource::Adopted {
grants: None,
path: "/usr/local/bin/shep-otel".to_string(),
channel: false,
events: Vec::new(),
},
env: BTreeMap::new(),
},
&paths,
)
.unwrap();
assert!(
adopted.config().args.is_empty(),
"the name arrives without shep inventing an argv for a foreign binary"
);
assert_eq!(
adopted.config().env.get("SHEP_DOG_NAME"),
Some(&"telemetry".to_string())
);
}
}