diff --git a/README.md b/README.md index 503409e..225c5d8 100644 --- a/README.md +++ b/README.md @@ -150,6 +150,31 @@ omits one. Unknown fields are rejected on both sides. A repository that gets compromised can therefore change what is built, but not what it is allowed to touch on the host. +An upstream daemon that does not speak Idunn's runtime contract is deployed +with `idunn-launch` as its executable artifact and the upstream tree as a +required adjacent artifact; the launcher finds the child inside the release that +holds it. The launcher is the unit's process: it binds the +candidate endpoint, answers Idunn's challenge, renders the child's config, +starts a stateful child only once it holds the write lease, and signs presence. + +```toml +# recipe fragment — the upstream tree is built or fetched as an artifact +[service] +executable_artifact = "idunn-launch" +arguments = [ + { kind = "literal", value = "--child" }, + { kind = "literal", value = "upstream/bin/daemon" }, + { kind = "literal", value = "--template" }, + { kind = "literal", value = "config.tmpl" }, + { kind = "literal", value = "--listener" }, + { kind = "literal", value = "unix" }, + { kind = "literal", value = "--health-path" }, + { kind = "literal", value = "/health" }, + { kind = "literal", value = "--health-contract" }, + { kind = "literal", value = "example.presence-launcher.v1" }, +] +``` + ## Contracts Idunn's typed contracts are published by diff --git a/docs/authority-map.md b/docs/authority-map.md index 270d592..b61a8f2 100644 --- a/docs/authority-map.md +++ b/docs/authority-map.md @@ -70,6 +70,42 @@ recipe fields. Stateless services declare no state block. Their operator binding therefore has no state root, state-transition policy, or process write-lease record. +## Foreign workloads: idunn-launch + +An upstream daemon that cannot speak Idunn's runtime contract (Synapse, MAS) +runs under `idunn-launch`, the unit's own process. Idunn's two-witness rule is +unchanged: Idunn observes the unit, and the launcher, inside the unit and +supervising the child, signs presence with the provider identity and the +activation key. + +- **Owner:** the launcher owns presence, config rendering and the child's + lifetime inside the unit, and the route answers it signs for that child. + Idunn owns admission, lease, route and continuity, as before. +- **Inputs:** the runtime bundle, the activation credential and provider + identity descriptors, the process write lease, the systemd credentials the + binding names, and the child's health over its private listener. +- **Outputs:** signed `gamecult.runtime_presence_health.v2` (Warming, Active + and failed to Odin; route observations on the candidate endpoint), one child + process, and a rendered config in the unit's private tmp that is never read + back. +- **Route:** the launcher, not the child, binds the candidate endpoint. A first + byte of 0x00 is an Idunn challenge frame and is answered by the launcher; + every other byte is copied untouched to the child's private listener. +- **Lease:** with `write_lease_required` the launcher starts the child only + after it holds the lease (bound to this Expected, this activation and one of + its own Warming proofs) and keeps the lease store share-locked while the + child lives. Losing the lease stops the child. +- **Config:** one template from the release is rendered with the closed + placeholder set `{{child.listen}}`, `{{credential:NAME}}`, + `{{credential_path:NAME}}` and `{{state_root}}`. Any other placeholder + refuses to start. +- **Forbidden:** the child binding the candidate endpoint; a child of a + lease-requiring target running without a held lease; any presence not signed + by both keys. +- **State kind `external-directory`:** a process-owned directory imposed by an + external runtime contract. Same writer, recovery and startup rules as + `external-file`: it is lease-gated, preserved and fenced, never interpreted. + ## Operator binding The root-admitted operator binding supplies the physical policy a repository diff --git a/src/bin/idunn-launch.rs b/src/bin/idunn-launch.rs index 32c6291..b743f06 100644 --- a/src/bin/idunn-launch.rs +++ b/src/bin/idunn-launch.rs @@ -17,7 +17,11 @@ fn main() -> std::process::ExitCode { } fn launch() -> anyhow::Result { - let contract = LaunchContract::parse(std::env::args().skip(1))?; + let release_root = std::env::current_exe()? + .parent() + .context("the launcher is not inside a release")? + .to_owned(); + let contract = LaunchContract::parse(release_root, std::env::args().skip(1))?; let bundle = std::env::var_os(IDUNN_RUNTIME_BUNDLE_ENVIRONMENT) .context("the Idunn runtime bundle is not set")?; let bind = std::env::var(IDUNN_RUNTIME_CANDIDATE_BIND_ENVIRONMENT) @@ -52,8 +56,8 @@ fn main() -> std::process::ExitCode { }; // SAFETY: the handler only stores to an atomic. unsafe { - libc::signal(libc::SIGTERM, on_signal as libc::sighandler_t); - libc::signal(libc::SIGINT, on_signal as libc::sighandler_t); + libc::signal(libc::SIGTERM, on_signal as *const () as libc::sighandler_t); + libc::signal(libc::SIGINT, on_signal as *const () as libc::sighandler_t); } Ok(launcher::run( &contract, diff --git a/src/launcher.rs b/src/launcher.rs index 25e38db..7748177 100644 --- a/src/launcher.rs +++ b/src/launcher.rs @@ -66,7 +66,8 @@ pub enum ChildListener { } /// Everything the recipe declares about the child, parsed from the launcher's -/// argv (`--flag value` pairs; `--child-arg` repeats). +/// argv (`--flag value` pairs; `--child-arg` repeats). The release root is the +/// sealed release directory that holds the launcher itself. #[derive(Clone, Debug, PartialEq, Eq)] pub struct LaunchContract { pub release_root: PathBuf, @@ -86,8 +87,8 @@ pub struct LaunchContract { } impl LaunchContract { - pub fn parse(args: impl IntoIterator) -> Result { - let mut release_root = None; + pub fn parse(release_root: PathBuf, args: impl IntoIterator) -> Result { + ensure!(release_root.is_absolute(), "the release root is not absolute"); let mut child = None; let mut child_args = Vec::new(); let mut config_flag = None; @@ -108,7 +109,6 @@ impl LaunchContract { .with_context(|| format!("launcher argument {field} is not a positive integer")) }; match flag.as_str() { - "--release-root" => release_root = Some(PathBuf::from(value)), "--child" => child = Some(release_relative(&value, "--child")?), "--child-arg" => child_args.push(value), "--config-flag" => config_flag = Some(value), @@ -135,11 +135,6 @@ impl LaunchContract { _ => bail!("unknown launcher argument"), } } - let release_root = release_root.context("launcher argument --release-root is required")?; - ensure!( - release_root.is_absolute(), - "launcher argument --release-root is not absolute" - ); Ok(Self { release_root, child: child.context("launcher argument --child is required")?, @@ -1157,7 +1152,7 @@ fn lifecycle( // 1. Warming reaches Odin before any child exists. let mut proofs: VecDeque = VecDeque::new(); - let mut remember = |sha: Option, proofs: &mut VecDeque| { + let remember = |sha: Option, proofs: &mut VecDeque| { if let Some(sha) = sha { proofs.push_back(sha); while proofs.len() > MAX_RECENT_WARMING_PROOFS { @@ -1938,8 +1933,6 @@ mod tests { fn contract_parsing_refuses_escapes_and_echoes_nothing() { let base = |extra: &[&str]| -> Result { let mut args: Vec = [ - "--release-root", - "/r", "--child", "bin/c", "--template", @@ -1954,7 +1947,7 @@ mod tests { .map(String::from) .to_vec(); args.extend(extra.iter().map(|value| value.to_string())); - LaunchContract::parse(args) + LaunchContract::parse(PathBuf::from("/r"), args) }; assert!(base(&["--child-arg", "--flag-looking-value"]).is_ok()); assert!(base(&["--child", "../escape"]).is_err()); @@ -1987,4 +1980,59 @@ mod tests { drop(hold); idunn.revoke_exact(Some(&lease)).unwrap(); } + + #[test] + fn authority_binds_the_candidate_and_signs_strictly_increasing_sequences() { + let fx = fixture(false); + let mut authority = fx.authority(); + assert!(authority.require_candidate_bind("127.0.0.1:18835").is_ok()); + assert!(authority.require_candidate_bind("127.0.0.1:18836").is_err()); + let first = authority.sign("warming", "a", None, 5_000).unwrap(); + let second = authority.sign("warming", "b", None, 5_000).unwrap(); + assert_eq!(first.publisher_sequence, 5_000); + assert_eq!(second.publisher_sequence, 5_001); + assert_eq!( + first.bound_endpoint.as_deref(), + Some("tcp://127.0.0.1:18835") + ); + } + + #[test] + fn health_probe_is_healthy_only_on_a_200_from_the_child() { + let dir = tempfile::tempdir().unwrap(); + let socket = dir.path().join("child.sock"); + let probe = HttpHealthProbe { + endpoint: ChildEndpoint::Unix(socket.clone()), + path: "/health".into(), + }; + assert!(!probe.healthy(), "no listener is not healthy"); + let listener = std::os::unix::net::UnixListener::bind(&socket).unwrap(); + let server = thread::spawn(move || { + for status in ["200 OK", "503 Service Unavailable"] { + let (mut stream, _) = listener.accept().unwrap(); + let mut request = [0_u8; 64]; + let read = stream.read(&mut request).unwrap(); + assert!(request[..read].starts_with(b"GET /health HTTP/1.1\r\n")); + write!(stream, "HTTP/1.1 {status}\r\nContent-Length: 2\r\n\r\nOK").unwrap(); + } + }); + assert!(probe.healthy()); + assert!(!probe.healthy()); + server.join().unwrap(); + } + + #[test] + fn process_spawner_reports_exit_codes_and_terminates_a_running_child() { + let mut gone = ProcessSpawner + .spawn(Path::new("/bin/sh"), &["-c".into(), "exit 3".into()]) + .unwrap(); + wait_until("child exit", || gone.exited().is_some()); + assert_eq!(gone.exited(), Some(3)); + let mut running = ProcessSpawner + .spawn(Path::new("/bin/sh"), &["-c".into(), "sleep 30".into()]) + .unwrap(); + assert_eq!(running.exited(), None); + running.terminate(Duration::from_secs(5)); + assert!(running.exited().is_some()); + } }