Skip to main content

Crate shep_daemon

Crate shep_daemon 

Source
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 SpawnSpec from 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 listen table.
notify
Readiness reporting to an init system that supervises this process directly.
privilege
Privilege drop: resolving an app’s requested user/group to numeric ids.
probes
The Prober seam 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 unsafe on unix: adopting a descriptor into a File
tokio_runner
Real ProcessRunner over actual OS processes.

Structs§

Bus
The daemon’s event channel, plus whether anything is listening for log lines.
SharedEvent
One published BusEvent, plus the wire frame its subscribers share.

Functions§

new_bus
Creates the daemon’s process-wide event bus.