Skip to main content

shep_daemon/
lib.rs

1//! The daemon: a process-supervision engine plus the control plane that
2//! exposes it over a unix socket
3//!
4//! Every command that reaches the flock goes through one
5//! [`SupervisorHandle`](supervisor::SupervisorHandle). Pure decision logic
6//! (brain, backoff, entry assembly) is IO-free, so it tests under a paused
7//! tokio clock. [`boot`] assembles the engine and the `RpcServer` into one
8//! daemon. Three tiers, top down: the engine and its actor, the control
9//! plane a CLI client talks to, and the platform glue under both.
10//!
11//! # Examples
12//!
13//! Builds a supervisor engine with a scripted fake runner, registers one app,
14//! and lists the live processes. Needs `--all-features` (`test-fakes`).
15//! ```no_run
16//! # #[cfg(feature = "test-fakes")]
17//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
18//! use shep_daemon::fake::{ProcScript, ScriptedRunner};
19//! use shep_daemon::supervisor::spawn_supervisor;
20//! use shep_core::config::AppConfig;
21//! use shep_core::config::normalize;
22//! use shep_core::paths::ShepPaths;
23//! use std::path::Path;
24//!
25//! // Create a fake runner that spawns one process never exiting
26//! let runner = ScriptedRunner::new(vec![ProcScript::never_exits()]);
27//!
28//! // Set up temporary paths for this example
29//! let paths = ShepPaths::resolve(&|_| None, Path::new("/tmp/shep-example"));
30//!
31//! // Create the event bus every subscriber reads
32//! let events = shep_daemon::new_bus();
33//!
34//! // Spawn the supervisor actor
35//! let handle = spawn_supervisor(runner, paths, events);
36//!
37//! // Build one app config and normalize it
38//! let app = AppConfig::minimal("web", "./server");
39//! let resolved = normalize(app)?;
40//!
41//! // Start the app (creates one instance)
42//! let infos = handle.start(vec![resolved]).await?;
43//! println!("Started: {} instance(s)", infos.len());
44//!
45//! // List all registered processes
46//! let list = handle.list().await;
47//! for info in &list {
48//!     println!("  ID {} ({}): {:?}", info.id, info.name, info.status);
49//! }
50//!
51//! // Gracefully shut down all processes
52//! handle.shutdown().await;
53//!
54//! Ok(())
55//! # }
56//! # #[tokio::main]
57//! # async fn main() {
58//! #     #[cfg(feature = "test-fakes")]
59//! #     example().await.ok();
60//! # }
61//! ```
62//!
63//! Boots a full daemon through [`boot`] on a temporary `$SHEP_HOME` with the
64//! same scripted fake runner, then round-trips one `Ping` over the wire codec
65//! `server` speaks. Needs `--all-features` on a unix target.
66//! ```no_run
67//! # #[cfg(all(unix, feature = "test-fakes"))]
68//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
69//! use shep_daemon::boot::{BootOptions, boot};
70//! use shep_daemon::fake::ScriptedRunner;
71//! use shep_core::paths::ShepPaths;
72//! use shep_core::protocol::{
73//!     Envelope, Hello, HelloReply, PROTOCOL_VERSION, Request, ServerFrame, codec, decode_frame,
74//!     encode_frame,
75//! };
76//! use tokio::net::UnixStream;
77//! use tokio_util::codec::Framed;
78//! use futures_util::{SinkExt, StreamExt};
79//!
80//! // A throwaway $SHEP_HOME: `boot` creates its 0700 layout inside it.
81//! let paths = ShepPaths::resolve(&|_| None, std::path::Path::new("/tmp/shep-daemon-example"));
82//!
83//! // Boot with the scripted fake runner — no real children, just the plane.
84//! let daemon = boot(ScriptedRunner::new(vec![]), paths, BootOptions::default()).await?;
85//! let socket = daemon.socket().to_path_buf();
86//! tokio::spawn(daemon.run());
87//!
88//! // Connect and speak the wire protocol directly: Hello, then Ping.
89//! let stream = UnixStream::connect(&socket).await?;
90//! let mut frames = Framed::new(stream, codec());
91//! frames
92//!     .send(encode_frame(&Hello {
93//!         client_version: "0.1.0".to_string(),
94//!         protocol: PROTOCOL_VERSION,
95//!         // Only a dog names one; see `Hello::dog_name`.
96//!         dog_name: None,
97//!     })?)
98//!     .await?;
99//! let ack: HelloReply = decode_frame(&frames.next().await.unwrap()?)?;
100//! let ack = ack.expect("the daemon must ack our protocol");
101//! println!("daemon pid: {}", ack.pid);
102//!
103//! frames
104//!     .send(encode_frame(&Envelope {
105//!         id: 1,
106//!         deadline_ms: Some(1_000),
107//!         body: Request::Ping,
108//!     })?)
109//!     .await?;
110//! let frame: ServerFrame = decode_frame(&frames.next().await.unwrap()?)?;
111//! println!("reply: {frame:?}");
112//!
113//! Ok(())
114//! # }
115//! # #[tokio::main]
116//! # async fn main() {
117//! #     #[cfg(all(unix, feature = "test-fakes"))]
118//! #     example().await.ok();
119//! # }
120//! ```
121
122#![doc(test(attr(deny(warnings))))]
123#![deny(unsafe_code)]
124
125// Internal tier: nothing outside this crate's own `src` names these. A dog is
126// a separate process speaking the protocol rather than linking this crate, so
127// a dog author builds against `shep-core`. Widening one back to `pub` is an
128// API decision.
129pub(crate) mod backoff;
130pub(crate) mod boot_order;
131pub(crate) mod brain;
132pub(crate) mod bus;
133// The bus surface a caller of `supervisor::spawn_supervisor` needs, and no
134// more: the module stays crate-private so its forwarders and topic
135// bookkeeping never become API.
136pub use bus::{Bus, SharedEvent, new_bus};
137// Linux only: cgroups are a Linux kernel interface. macOS and Windows have no
138// counterpart for this module to compile against.
139#[cfg(target_os = "linux")]
140pub(crate) mod cgroup;
141pub(crate) mod cron;
142pub(crate) mod entry;
143pub(crate) mod extras;
144pub(crate) mod host;
145// Unix only: `fcntl`, `execve` and raw descriptor numbers have no Windows
146// equivalent, and `Arm::for_daemon` already returns the stop arm there.
147#[cfg(unix)]
148pub(crate) mod handover;
149pub(crate) mod kill;
150// Its reads are unix only, like both callers: a handover's adopted start
151// times and the lamb sweep's liveness check. Its clock is everywhere.
152pub(crate) mod proc_table;
153// The provider values a dog has pushed, and the cache file they survive a
154// restart in. Crate-private: a dog writes here over the socket, never by
155// linking this crate.
156pub(crate) mod secrets;
157// Polls the operator's store for a value a running dog names.
158pub(crate) mod secrets_watch;
159pub(crate) mod sweep;
160pub(crate) mod watch;
161
162// Reachable tier: each of these is named from outside this crate's `src`, by
163// `shep-cli`, an integration test, the bench crate, or a doc example. Every
164// module here carries a note in its own header saying which consumer holds it
165// open.
166pub mod assemble;
167pub mod channel;
168// A `dogs::DogSpec` says which dogs to run and where their binaries come
169// from, an answer only `shep.toml` holds, and every `shep.toml` read in this
170// project happens in `shep-cli`. So the assembling caller is out of crate by
171// construction.
172pub mod dogs;
173pub mod limits;
174// A `SpawnSpec` carries one, so `tests/real_runner` binds the sockets it hands a
175// child and names the type.
176pub mod listen;
177pub mod privilege;
178pub mod probes;
179pub mod rpc;
180pub mod runner;
181pub mod snapshot;
182pub mod supervisor;
183// Reads a sheep's checkout for `Describe`; behind a feature because it opens
184// files in a directory the operator controls.
185#[cfg(feature = "vcs")]
186pub mod vcs;
187
188use std::time::SystemTime;
189
190/// The one real-time read shared across this crate: wall-clock milliseconds
191/// since the Unix epoch, for [`BusEvent::Process::at_ms`](shep_core::protocol::BusEvent::Process)
192/// and [`FlockSnapshot::saved_at_ms`](snapshot::FlockSnapshot::saved_at_ms).
193/// Everything else in the engine uses the paused-clock-aware
194/// `tokio::time::Instant`.
195pub(crate) fn now_ms() -> u64 {
196    SystemTime::now()
197        .duration_since(SystemTime::UNIX_EPOCH)
198        .map(|elapsed| elapsed.as_millis() as u64)
199        .unwrap_or(0)
200}
201
202#[cfg(test)]
203pub(crate) mod testing;
204#[cfg(test)]
205pub(crate) mod testing_http;
206
207// Reachable tier: `shep-cli`'s hidden `daemon` subcommand calls `boot` and
208// `RunningDaemon::run`, and `launch.rs` reads `DIR_MODE`. Portable on both
209// platforms; `DIR_MODE` alone is gated unix-only. Doc lives inside boot.rs's
210// own `//!` header, for the reason `server`'s note below gives.
211pub mod boot;
212
213// Unix only: `FromRawFd`/`RawFd` and this crate's whole unsafe surface there.
214// `pub` for a consumer not written yet: `boot` does not call `adopt_fd`, so
215// the ordering precondition needs a caller running before any runtime exists,
216// `shep-cli`'s `main`. Doc lives inside sys.rs's own `//!` header.
217#[cfg(unix)]
218pub mod sys;
219
220// The Windows counterpart to `sys`, and this crate's only unsafe surface
221// there: the std-handle seal and the shepherd's pipe descriptor. `pub`
222// because `seal_std_handles`' caller lives in shep-cli. A sheep's job object
223// is `shep-tree`'s.
224#[cfg(windows)]
225pub mod sys_windows;
226
227// Unix only: `UnixDatagram`, plus Linux's abstract-namespace address. Doc
228// lives inside notify.rs's own `//!` header. `shep-cli`'s hidden `daemon`
229// subcommand names `NOTIFY_SOCKET_ENV`, since every environment read happens
230// there; this crate receives the resolved address instead.
231#[cfg(unix)]
232pub mod notify;
233
234/// Real [`ProcessRunner`](runner::ProcessRunner) over actual OS processes.
235///
236/// Unix only: built on `nix` process-group signals and `command-fds` fd-3
237/// passing, both `#[cfg(unix)]` deps. Public because `shep-cli` hands
238/// [`TokioRunner`](tokio_runner::TokioRunner) to [`boot`], and
239/// `tests/real_runner/` drives it against real children.
240pub mod tokio_runner;
241
242// Portable: it names `shep_core::transport`, so one accept loop and
243// connection state machine serve both platforms; the same-uid `peer_cred`
244// check is `#[cfg(unix)]` inside. Doc lives inside server.rs's own `//!`
245// header: an outer `///` here would merge with it and misresolve its links.
246pub(crate) mod server;
247
248/// Deterministic scripted [`ProcessRunner`](runner::ProcessRunner), reused by
249/// this crate's own tests and, behind `test-fakes`, by any other crate's.
250///
251/// Public because both doc examples above build one, and rustdoc compiles a
252/// doc example as its own crate.
253#[cfg(any(test, feature = "test-fakes"))]
254pub mod fake;