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