use super::assembly_errors::AssembleError;
use super::environment_inheritance::{INHERITED, InheritedEnv, inherited_env};
use super::log_path_resolution::anchor_log_path;
use crate::brain::is_sandboxed;
use crate::privilege::Credentials;
use crate::runner::SpawnSpec;
use core::convert::Infallible;
use shep_core::config::ResolvedApp;
use shep_core::config::template::{self};
use shep_core::paths::ShepPaths;
use shep_core::secrets::SecretView;
use std::path::PathBuf;
pub fn assemble(
app: &ResolvedApp,
instance: u32,
paths: &ShepPaths,
credentials: Option<Credentials>,
secrets: &SecretView,
) -> Result<SpawnSpec, AssembleError> {
let name = app.config().name.clone();
build(
app,
instance,
paths,
credentials,
secrets.environment(),
|value, field| {
template::render(value, &name, instance, Some(&paths.home), secrets).map_err(|source| {
AssembleError::Template {
field: field.to_string(),
source,
}
})
},
InheritedEnv {
keys: INHERITED,
reader: &|key: &str| std::env::var(key).ok(),
},
)
}
#[must_use]
pub(crate) fn describe(
app: &ResolvedApp,
instance: u32,
paths: &ShepPaths,
credentials: Option<Credentials>,
secrets: &SecretView,
) -> SpawnSpec {
let name = app.config().name.clone();
let built: Result<SpawnSpec, Infallible> = build(
app,
instance,
paths,
credentials,
secrets.environment(),
|value, _| {
Ok(
template::render(value, &name, instance, Some(&paths.home), secrets)
.unwrap_or_else(|_| {
template::render_positional(value, &name, instance, Some(&paths.home))
}),
)
},
InheritedEnv {
keys: INHERITED,
reader: &|key: &str| std::env::var(key).ok(),
},
);
match built {
Ok(spec) => spec,
Err(never) => match never {},
}
}
pub(super) fn build<E>(
app: &ResolvedApp,
instance: u32,
paths: &ShepPaths,
credentials: Option<Credentials>,
environment: &str,
mut render: impl FnMut(&str, &str) -> Result<String, E>,
inherited: InheritedEnv<'_>,
) -> Result<SpawnSpec, E> {
let config = app.config();
let name = config.name.clone();
let mut rendered_args = Vec::with_capacity(config.args.len());
for value in &config.args {
rendered_args.push(render(value, "args")?);
}
let (program, args) = match &config.interpreter {
None => (config.script.clone(), rendered_args),
Some(interp) if interp == "none" => (config.script.clone(), rendered_args),
Some(interp) => {
let mut interp_args = vec![config.script.clone()];
interp_args.extend(rendered_args);
(interp.clone(), interp_args)
}
};
let cwd = config.cwd.as_ref().map(PathBuf::from);
let mut env = inherited_env(inherited.keys, inherited.reader);
for (key, value) in &config.env {
let value = render(value, key)?;
env.insert(key.clone(), value);
}
env.insert("SHEP_INSTANCE".to_string(), instance.to_string());
env.insert("SHEP_NAME".to_string(), name.clone());
env.insert("SHEP_ENVIRONMENT".to_string(), environment.to_string());
if config.pty {
env.entry("TERM".to_string())
.or_insert_with(|| "xterm-256color".to_string());
}
let log_stem = if config.merge_logs {
format!("{}-", name)
} else {
format!("{}-{}-", name, instance)
};
let out_file = match &config.out_file {
Some(explicit) => anchor_log_path(render(explicit, "out_file")?, cwd.as_deref()),
None => paths.logs.join(format!("{}out.log", log_stem)),
};
let err_file = match &config.err_file {
Some(explicit) => anchor_log_path(render(explicit, "err_file")?, cwd.as_deref()),
None => paths.logs.join(format!("{}err.log", log_stem)),
};
let channel = config.channel || config.wait_ready || config.shutdown_with_message;
Ok(SpawnSpec {
name,
program,
args,
cwd,
env,
out_file,
err_file,
log_timestamps: config.log_timestamps,
channel,
stdin: config.stdin,
pty: config.pty,
credentials,
dog_link: false,
launch_link: None,
leader_only_stop: is_sandboxed(config),
listen: None,
cgroup: None,
memory_max: None,
cpu_quota: None,
pids_max: None,
})
}
#[cfg(test)]
mod tests {
use super::super::environment_inheritance::{INHERITED_WINDOWS, InheritedEnv};
use core::convert::Infallible;
use std::path::PathBuf;
use shep_core::secrets::SecretView;
use super::super::testing::*;
use super::*;
use shep_core::config::{AppConfig, normalize};
#[test]
fn every_child_learns_its_slot_and_its_name() {
let app = normalize(AppConfig {
name: "worker".to_string(),
script: "bin/worker".to_string(),
..Default::default()
})
.unwrap();
let spec = assemble(&app, 3, &test_paths(), None, &no_secrets()).unwrap();
assert_eq!(spec.env.get("SHEP_INSTANCE").map(String::as_str), Some("3"));
assert_eq!(
spec.env.get("SHEP_NAME").map(String::as_str),
Some("worker")
);
}
#[test]
fn interpreter_none_runs_script_directly() {
let app_config = AppConfig {
name: "app".to_string(),
script: "/opt/bin/server".to_string(),
args: vec!["--port".to_string(), "8080".to_string()],
interpreter: None,
..Default::default()
};
let app = normalize(app_config).unwrap();
let paths = test_paths();
let spec = assemble(&app, 0, &paths, None, &no_secrets()).unwrap();
assert_eq!(spec.program, "/opt/bin/server");
assert_eq!(spec.args, vec!["--port", "8080"]);
}
#[test]
fn interpreter_explicit_none_runs_script_directly() {
let app_config = AppConfig {
name: "app".to_string(),
script: "server.py".to_string(),
args: vec!["--verbose".to_string()],
interpreter: Some("none".to_string()),
..Default::default()
};
let app = normalize(app_config).unwrap();
let paths = test_paths();
let spec = assemble(&app, 0, &paths, None, &no_secrets()).unwrap();
assert_eq!(spec.program, "server.py");
assert_eq!(spec.args, vec!["--verbose"]);
}
#[test]
fn interpreter_path_prepends_script() {
let app_config = AppConfig {
name: "app".to_string(),
script: "app.js".to_string(),
args: vec!["--debug".to_string(), "true".to_string()],
interpreter: Some("node".to_string()),
..Default::default()
};
let app = normalize(app_config).unwrap();
let paths = test_paths();
let spec = assemble(&app, 0, &paths, None, &no_secrets()).unwrap();
assert_eq!(spec.program, "node");
assert_eq!(spec.args, vec!["app.js", "--debug", "true"]);
}
#[test]
fn merge_logs_false_uses_instance_suffix() {
let app_config = AppConfig {
name: "web".to_string(),
script: "app".to_string(),
args: vec![],
merge_logs: false,
..Default::default()
};
let app = normalize(app_config).unwrap();
let paths = test_paths();
let spec = assemble(&app, 2, &paths, None, &no_secrets()).unwrap();
assert_eq!(
spec.out_file,
PathBuf::from("/home/ada/.shep/logs/web-2-out.log")
);
assert_eq!(
spec.err_file,
PathBuf::from("/home/ada/.shep/logs/web-2-err.log")
);
}
#[test]
fn merge_logs_true_omits_instance_suffix() {
let app_config = AppConfig {
name: "api".to_string(),
script: "api".to_string(),
args: vec![],
merge_logs: true,
..Default::default()
};
let app = normalize(app_config).unwrap();
let paths = test_paths();
let spec = assemble(&app, 1, &paths, None, &no_secrets()).unwrap();
assert_eq!(
spec.out_file,
PathBuf::from("/home/ada/.shep/logs/api-out.log")
);
assert_eq!(
spec.err_file,
PathBuf::from("/home/ada/.shep/logs/api-err.log")
);
}
#[test]
fn the_spec_carries_whether_the_app_stamps_its_log_lines() {
let paths = test_paths();
let stamped = |log_timestamps| {
let app = normalize(AppConfig {
log_timestamps,
..AppConfig::minimal("web", "app")
})
.unwrap();
assemble(&app, 0, &paths, None, &no_secrets())
.unwrap()
.log_timestamps
};
assert!(stamped(true));
assert!(!stamped(false));
}
#[test]
fn explicit_out_file_wins() {
let app_config = AppConfig {
name: "app".to_string(),
script: "app".to_string(),
args: vec![],
merge_logs: false,
out_file: Some("/var/log/myapp.log".to_string()),
..Default::default()
};
let app = normalize(app_config).unwrap();
let paths = test_paths();
let spec = assemble(&app, 0, &paths, None, &no_secrets()).unwrap();
assert_eq!(spec.out_file, PathBuf::from("/var/log/myapp.log"));
assert_eq!(
spec.err_file,
PathBuf::from("/home/ada/.shep/logs/app-0-err.log")
);
}
#[test]
fn a_relative_log_path_is_anchored_at_the_app_cwd() {
let app_config = AppConfig {
name: "app".to_string(),
script: "app".to_string(),
args: vec![],
cwd: Some("/srv/app".to_string()),
out_file: Some("logs/out.log".to_string()),
err_file: Some("logs/{{name}}-err.log".to_string()),
..Default::default()
};
let app = normalize(app_config).unwrap();
let paths = test_paths();
let spec = assemble(&app, 0, &paths, None, &no_secrets()).unwrap();
assert_eq!(spec.out_file, PathBuf::from("/srv/app/logs/out.log"));
assert_eq!(spec.err_file, PathBuf::from("/srv/app/logs/app-err.log"));
}
#[test]
fn an_absolute_log_path_ignores_the_app_cwd() {
let absolute = if cfg!(windows) {
r"C:\var\log\myapp.log"
} else {
"/var/log/myapp.log"
};
let app_config = AppConfig {
name: "app".to_string(),
script: "app".to_string(),
args: vec![],
cwd: Some("/srv/app".to_string()),
out_file: Some(absolute.to_string()),
..Default::default()
};
let app = normalize(app_config).unwrap();
let paths = test_paths();
let spec = assemble(&app, 0, &paths, None, &no_secrets()).unwrap();
assert_eq!(spec.out_file, PathBuf::from(absolute));
}
#[test]
fn a_relative_log_path_without_a_cwd_is_left_alone() {
let app_config = AppConfig {
name: "app".to_string(),
script: "app".to_string(),
args: vec![],
cwd: None,
out_file: Some("logs/out.log".to_string()),
..Default::default()
};
let app = normalize(app_config).unwrap();
let paths = test_paths();
let spec = assemble(&app, 0, &paths, None, &no_secrets()).unwrap();
assert_eq!(spec.out_file, PathBuf::from("logs/out.log"));
}
#[test]
fn a_defaulted_log_path_ignores_the_app_cwd() {
let app_config = AppConfig {
name: "app".to_string(),
script: "app".to_string(),
args: vec![],
cwd: Some("/srv/app".to_string()),
..Default::default()
};
let app = normalize(app_config).unwrap();
let paths = test_paths();
let spec = assemble(&app, 0, &paths, None, &no_secrets()).unwrap();
assert_eq!(
spec.out_file,
PathBuf::from("/home/ada/.shep/logs/app-0-out.log")
);
}
#[test]
fn a_shep_home_log_path_is_not_anchored_at_the_app_cwd() {
let home = if cfg!(windows) {
r"C:\shep"
} else {
"/home/ada/.shep"
};
let mut paths = test_paths();
paths.home = PathBuf::from(home);
let app_config = AppConfig {
name: "app".to_string(),
script: "app".to_string(),
args: vec![],
cwd: Some("/srv/app".to_string()),
out_file: Some("{{SHEP_HOME}}/logs/{{name}}-out.log".to_string()),
err_file: Some("{{SHEP_HOME}}/logs/{{name}}-err.log".to_string()),
..Default::default()
};
let app = normalize(app_config).unwrap();
let spec = assemble(&app, 0, &paths, None, &no_secrets()).unwrap();
let logs = PathBuf::from(home).join("logs");
assert_eq!(spec.out_file, logs.join("app-out.log"));
assert_eq!(spec.err_file, logs.join("app-err.log"));
}
#[test]
fn a_shep_home_log_path_follows_the_shepherd_it_is_assembled_for() {
let app_config = AppConfig {
name: "app".to_string(),
script: "app".to_string(),
args: vec![],
out_file: Some("{{SHEP_HOME}}/logs/out.log".to_string()),
..Default::default()
};
let app = normalize(app_config).unwrap();
let mut elsewhere = test_paths();
elsewhere.home = PathBuf::from(if cfg!(windows) {
r"C:\srv\shep"
} else {
"/srv/shep"
});
let here_paths = test_paths();
let here = assemble(&app, 0, &here_paths, None, &no_secrets()).unwrap();
let there = assemble(&app, 0, &elsewhere, None, &no_secrets()).unwrap();
assert_eq!(here.out_file, here_paths.home.join("logs").join("out.log"));
assert_eq!(there.out_file, elsewhere.home.join("logs").join("out.log"));
assert_ne!(
here.out_file, there.out_file,
"one config, two shepherds, two files"
);
}
#[test]
fn channel_enabled_by_its_own_field() {
let app_config = AppConfig {
name: "app".to_string(),
script: "app".to_string(),
args: vec![],
channel: true,
wait_ready: false,
shutdown_with_message: false,
..Default::default()
};
let app = normalize(app_config).unwrap();
let paths = test_paths();
let spec = assemble(&app, 0, &paths, None, &no_secrets()).unwrap();
assert!(spec.channel);
}
#[test]
fn channel_enabled_by_wait_ready() {
let app_config = AppConfig {
name: "app".to_string(),
script: "app".to_string(),
args: vec![],
channel: false,
wait_ready: true,
shutdown_with_message: false,
..Default::default()
};
let app = normalize(app_config).unwrap();
let paths = test_paths();
let spec = assemble(&app, 0, &paths, None, &no_secrets()).unwrap();
assert!(spec.channel);
}
#[test]
fn channel_enabled_by_shutdown_with_message() {
let app_config = AppConfig {
name: "app".to_string(),
script: "app".to_string(),
args: vec![],
channel: false,
wait_ready: false,
shutdown_with_message: true,
..Default::default()
};
let app = normalize(app_config).unwrap();
let paths = test_paths();
let spec = assemble(&app, 0, &paths, None, &no_secrets()).unwrap();
assert!(spec.channel);
}
#[test]
fn channel_disabled_when_all_three_flags_are_false() {
let app_config = AppConfig {
name: "app".to_string(),
script: "app".to_string(),
args: vec![],
channel: false,
wait_ready: false,
shutdown_with_message: false,
..Default::default()
};
let app = normalize(app_config).unwrap();
let paths = test_paths();
let spec = assemble(&app, 0, &paths, None, &no_secrets()).unwrap();
assert!(!spec.channel);
}
#[test]
fn assembled_env_always_carries_a_path() {
let app_config = AppConfig {
name: "web".to_string(),
script: "app.js".to_string(),
args: vec![],
interpreter: Some("node".to_string()),
..Default::default()
};
let app = normalize(app_config).unwrap();
let spec = assemble(&app, 0, &test_paths(), None, &no_secrets()).unwrap();
let path = spec
.env
.get("PATH")
.expect("PATH must survive env_clear()+envs(&spec.env)");
assert!(
!path.is_empty(),
"an empty PATH is exactly the ENOENT failure mode"
);
}
#[test]
fn windows_stdio_encoding_vars_reach_spec_env() {
let app_config = AppConfig {
name: "web".to_string(),
script: "app.js".to_string(),
interpreter: Some("none".to_string()),
..Default::default()
};
let app = normalize(app_config).unwrap();
let fake_env = |key: &str| match key {
"PYTHONUTF8" => Some("1".to_string()),
"PYTHONIOENCODING" => Some("utf-8".to_string()),
_ => None,
};
let spec = build::<Infallible>(
&app,
0,
&test_paths(),
None,
"production",
|value, _field| Ok(value.to_string()),
InheritedEnv {
keys: INHERITED_WINDOWS,
reader: &fake_env,
},
)
.expect("no template in this app can fail to render");
assert_eq!(spec.env.get("PYTHONUTF8").map(String::as_str), Some("1"));
assert_eq!(
spec.env.get("PYTHONIOENCODING").map(String::as_str),
Some("utf-8")
);
}
#[test]
fn an_explicit_app_path_overrides_the_seeded_default() {
let mut app_config = AppConfig {
name: "web".to_string(),
script: "app.js".to_string(),
args: vec![],
interpreter: Some("node".to_string()),
..Default::default()
};
app_config
.env
.insert("PATH".to_string(), "/opt/custom/bin".to_string());
let app = normalize(app_config).unwrap();
let spec = assemble(&app, 0, &test_paths(), None, &no_secrets()).unwrap();
assert_eq!(
spec.env.get("PATH").map(String::as_str),
Some("/opt/custom/bin")
);
}
#[test]
fn the_stdin_flag_reaches_the_spawn_spec() {
let mut app = AppConfig::minimal("repl", "./repl");
app.stdin = true;
let spec = assemble(
&normalize(app).unwrap(),
0,
&test_paths(),
None,
&no_secrets(),
)
.unwrap();
assert!(spec.stdin);
}
#[test]
#[cfg(unix)]
fn the_pty_flag_reaches_the_spawn_spec() {
let mut app = AppConfig::minimal("repl", "./repl");
app.pty = true;
let spec = assemble(
&normalize(app).unwrap(),
0,
&test_paths(),
None,
&no_secrets(),
)
.unwrap();
assert!(spec.pty);
assert_eq!(
spec.env.get("TERM").map(String::as_str),
Some("xterm-256color")
);
}
#[test]
#[cfg(unix)]
fn an_env_term_wins_over_the_default() {
let mut app = AppConfig::minimal("repl", "./repl");
app.pty = true;
app.env.insert("TERM".to_string(), "vt100".to_string());
let spec = assemble(
&normalize(app).unwrap(),
0,
&test_paths(),
None,
&no_secrets(),
)
.unwrap();
assert_eq!(spec.env.get("TERM").map(String::as_str), Some("vt100"));
}
#[test]
fn a_sheep_without_a_pty_gets_no_term() {
let spec = assemble(
&normalize(AppConfig::minimal("web", "./web")).unwrap(),
0,
&test_paths(),
None,
&no_secrets(),
)
.unwrap();
assert!(!spec.pty);
assert!(!spec.env.contains_key("TERM"));
}
#[test]
fn templates_render_per_instance_in_env_and_args() {
let mut config = AppConfig {
name: "z-worker".to_string(),
script: "bin/worker".to_string(),
instances: 4,
args: vec!["--metrics-port".to_string(), "91{{instance}}".to_string()],
..Default::default()
};
config
.env
.insert("Z_WORKER_ID".to_string(), "z-{{instance}}".to_string());
config.env.insert(
"Z_DEVICE_ID".to_string(),
"{{name}}-{{instance}}d".to_string(),
);
let app = normalize(config).unwrap();
let spec = assemble(&app, 2, &test_paths(), None, &no_secrets()).unwrap();
assert_eq!(spec.env.get("Z_WORKER_ID").map(String::as_str), Some("z-2"));
assert_eq!(
spec.env.get("Z_DEVICE_ID").map(String::as_str),
Some("z-worker-2d")
);
assert!(spec.args.contains(&"912".to_string()), "{:?}", spec.args);
}
#[test]
fn a_templated_log_path_renders_per_instance() {
let app = normalize(AppConfig {
name: "web".to_string(),
script: "./srv".to_string(),
instances: 3,
out_file: Some("/var/log/web-{{instance}}.log".to_string()),
..Default::default()
})
.unwrap();
let spec = assemble(&app, 2, &test_paths(), None, &no_secrets()).unwrap();
assert_eq!(spec.out_file, PathBuf::from("/var/log/web-2.log"));
}
#[test]
fn nothing_else_turns_stdin_on() {
let mut app = AppConfig::minimal("web", "./srv");
app.channel = true;
app.wait_ready = true;
app.shutdown_with_message = true;
let spec = assemble(
&normalize(app).unwrap(),
0,
&test_paths(),
None,
&no_secrets(),
)
.unwrap();
assert!(spec.channel, "the fixture should still open a channel");
assert!(!spec.stdin);
}
#[test]
fn a_resolved_secret_reaches_the_child_env() {
let mut config = AppConfig::minimal("web", "./srv");
config
.env
.insert("PW".into(), "{{secret:DB_PASSWORD}}".into());
let app = normalize(config).unwrap();
let spec = assemble(
&app,
0,
&test_paths(),
None,
&view_with("production", "DB_PASSWORD", "hunter2"),
)
.unwrap();
assert_eq!(spec.env.get("PW").map(String::as_str), Some("hunter2"));
}
#[test]
fn shep_environment_is_injected_and_matches_the_view() {
let app = normalize(AppConfig::minimal("web", "./srv")).unwrap();
let spec = assemble(
&app,
0,
&test_paths(),
None,
&SecretView::empty("staging".into()),
)
.unwrap();
assert_eq!(
spec.env.get("SHEP_ENVIRONMENT").map(String::as_str),
Some("staging")
);
}
#[test]
fn an_unready_namespace_refuses_retriably() {
let mut config = AppConfig::minimal("web", "./srv");
config.env.insert("PW".into(), "{{secret:vault/K}}".into());
let app = normalize(config).unwrap();
let err = assemble(
&app,
0,
&test_paths(),
None,
&SecretView::empty("production".into()),
)
.unwrap_err();
assert!(err.is_retriable());
}
#[test]
fn a_secret_resolves_in_args() {
let mut config = AppConfig::minimal("web", "./srv");
config.args = vec!["--token={{secret:K}}".into()];
let app = normalize(config).unwrap();
let spec = assemble(
&app,
0,
&test_paths(),
None,
&view_with("production", "K", "v"),
)
.unwrap();
assert_eq!(spec.args, vec!["--token=v".to_string()]);
}
#[test]
fn an_app_cannot_set_shep_environment_by_hand() {
let mut config = AppConfig::minimal("web", "./srv");
config
.env
.insert("SHEP_ENVIRONMENT".into(), "sneaky".into());
assert!(normalize(config).is_err());
}
#[test]
fn the_two_refusal_shapes_stay_apart() {
let mut absent = AppConfig::minimal("a", "./srv");
absent.env.insert("K".into(), "{{secret:NOPE}}".into());
let mut unready = AppConfig::minimal("b", "./srv");
unready.env.insert("K".into(), "{{secret:ns/NOPE}}".into());
let view = SecretView::empty("production".to_string());
let of = |config| {
assemble(&normalize(config).unwrap(), 0, &test_paths(), None, &view)
.unwrap_err()
.is_retriable()
};
assert!(!of(absent), "a key nobody set waits on a person");
assert!(of(unready), "a namespace no dog pushed to clears itself");
}
#[test]
fn describe_keeps_an_unresolvable_reference_rather_than_refusing() {
let mut config = AppConfig::minimal("web", "./srv");
config.env.insert("PW".into(), "{{secret:ABSENT}}".into());
config.out_file = Some("/tmp/{{name}}.log".into());
config.merge_logs = true;
let app = normalize(config).unwrap();
let spec = describe(
&app,
0,
&test_paths(),
None,
&SecretView::empty("staging".into()),
);
assert_eq!(
spec.env.get("PW").map(String::as_str),
Some("{{secret:ABSENT}}")
);
assert_eq!(spec.out_file, PathBuf::from("/tmp/web.log"));
assert_eq!(
spec.env.get("SHEP_ENVIRONMENT").map(String::as_str),
Some("staging"),
"a described spec still names its environment"
);
}
#[test]
fn describe_matches_assemble_when_every_reference_resolves() {
let mut config = AppConfig::minimal("web", "./srv");
config.env.insert("PW".into(), "{{secret:K}}".into());
let app = normalize(config).unwrap();
let view = view_with("production", "K", "v");
let assembled = assemble(&app, 2, &test_paths(), None, &view).unwrap();
let described = describe(&app, 2, &test_paths(), None, &view);
assert_eq!(assembled.env, described.env);
assert_eq!(assembled.out_file, described.out_file);
assert_eq!(assembled.args, described.args);
}
}