Expand description
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. 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).
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(())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.
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(())Modules§
- assemble
- Spawn assembly: pure functions that build
SpawnSpecfrom app config. - boot
- Daemon boot: the sequence, and a file for each step of it
- channel
- The shepherd channel’s message shapes, re-exported from shep-core.
- dogs
- The dogs subsystem: what a dog is, the handshake-refusal ladder, silent-dog detection, shep’s own narration into a dog’s log, and the local restart bookkeeping the daemon keeps for its plugin processes.
- limits
- Process-tree memory limits (spec §4).
- listen
- The TCP sockets the shepherd binds for a sheep’s
listentable. - notify
- Readiness reporting to an init system that supervises this process directly.
- privilege
- Privilege drop: resolving an app’s requested
user/groupto numeric ids. - probes
- The
Proberseam and the liveness probe loop (spec §7). - rpc
- Portable RPC dispatch: verb routing, typed errors, per-call deadlines
- runner
- Spawn seam between the daemon engine and the OS
- snapshot
- The muster roll: persisted flock state for restart-survival (
shep muster) - supervisor
- The supervisor actor: owns the flock’s lifecycle state machine.
- sys
- This crate’s only
unsafeon unix: adopting a descriptor into aFile - tokio_
runner - Real
ProcessRunnerover actual OS processes.
Structs§
- Bus
- The daemon’s event channel, plus whether anything is listening for log lines.
- Shared
Event - One published
BusEvent, plus the wire frame its subscribers share.
Functions§
- new_bus
- Creates the daemon’s process-wide event bus.