shep-daemon 0.25.2

The supervision engine behind shep: process spawning, restart policy, the log plane, watch and cron restarts, and the RPC server
Documentation
//! Starting the actor task.
//!
//! [`spawn_supervisor`] is the ordinary entry point and starts with no dog
//! defaults: `boot` reads them.
//! `SupervisorBuilder` is the long form the daemon's boot path uses when it
//! has to override the clock, the runner or the paths, as the tests do.

use super::*;

/// Builds a supervisor actor.
#[derive(Debug)]
pub(crate) struct SupervisorBuilder<R: ProcessRunner> {
    pub(super) runner: R,
    pub(super) paths: ShepPaths,
    pub(super) events: Bus,
    pub(super) extras: Option<Extras>,
    pub(super) environment: String,
    pub(super) provider_secrets: Option<Arc<ProviderSecrets>>,
    /// The `listen` sockets a predecessor carried, one set per sheep.
    #[cfg(unix)]
    pub(super) adopted_listeners: Vec<AdoptedListeners>,
    pub(super) dog_binaries: BTreeMap<String, String>,
    pub(super) cgroup_base: Option<PathBuf>,
    pub(super) cgroup_unavailable: Option<String>,
}

impl<R: ProcessRunner> SupervisorBuilder<R> {
    /// A builder with no lifecycle extras: the engine spawns, restarts and
    /// kills, and nothing watches, schedules or probes. `events` receives
    /// [`BusEvent::Process`] plus logs forwarded from each sheep.
    pub(crate) fn new(runner: R, paths: ShepPaths, events: Bus) -> Self {
        Self {
            runner,
            paths,
            events,
            extras: None,
            environment: DEFAULT_ENVIRONMENT.to_string(),
            provider_secrets: None,
            #[cfg(unix)]
            adopted_listeners: Vec::new(),
            dog_binaries: BTreeMap::new(),
            cgroup_base: None,
            cgroup_unavailable: None,
        }
    }

    /// Gives each sheep its own cgroup under `cgroups`' base when it holds
    /// one. [`crate::cgroup::Cgroups::Unavailable`] leaves every sheep spawning
    /// without, and refuses one with `memory_enforce = "kernel"`, naming why.
    #[cfg(target_os = "linux")]
    #[must_use]
    pub(crate) fn cgroups(mut self, cgroups: crate::cgroup::Cgroups) -> Self {
        match cgroups {
            crate::cgroup::Cgroups::Available { base } => {
                self.cgroup_base = Some(base);
                self.cgroup_unavailable = None;
            }
            crate::cgroup::Cgroups::Unavailable(reason) => {
                self.cgroup_base = None;
                self.cgroup_unavailable = Some(reason.to_string());
            }
        }
        self
    }

    /// Wires in the lifecycle extras.
    #[must_use]
    pub(crate) fn extras(mut self, extras: Extras) -> Self {
        self.extras = Some(extras);
        self
    }

    /// The environment a sheep that names none of its own resolves its
    /// secrets in, from `[daemon] environment`.
    ///
    /// Left at [`DEFAULT_ENVIRONMENT`] when unset, which is what
    /// `DaemonSection` itself defaults to, so a builder nobody told and a
    /// file that says nothing agree.
    #[must_use]
    pub(crate) fn environment(mut self, environment: String) -> Self {
        self.environment = environment;
        self
    }

    /// The registry a provider dog pushes into, shared with the connection
    /// tasks that serve `Request::PutSecrets`.
    ///
    /// Left unset, the actor loads one of its own from
    /// [`ShepPaths::secrets_cache`], which is what a cold boot with no dog
    /// yet running resolves against anyway. `boot` passes the shared one
    /// so a push reaches the next spawn.
    #[must_use]
    pub(crate) fn provider_secrets(mut self, secrets: Arc<ProviderSecrets>) -> Self {
        self.provider_secrets = Some(secrets);
        self
    }

    /// The `listen` sockets a predecessor handed over, which the next spawn or
    /// reload of each sheep passes on instead of binding.
    ///
    /// Left empty, every sheep binds on its next start.
    #[cfg(unix)]
    #[must_use]
    pub(crate) fn adopted_listeners(mut self, listeners: Vec<AdoptedListeners>) -> Self {
        self.adopted_listeners = listeners;
        self
    }

    /// Where each adopted dog's binary lives, by dog name.
    ///
    /// A sheep with a `dogs.sandbox` table spawns through the `sandbox` entry
    /// and is refused without one. Left empty, the actor knows no dog until a
    /// `StartDog` hands it an adopted source. `boot` fills it from the dogs
    /// `shep.toml` records, since the daemon never reads that file itself.
    #[must_use]
    pub(crate) fn dog_binaries(mut self, binaries: BTreeMap<String, String>) -> Self {
        self.dog_binaries = binaries;
        self
    }

    /// Spawns the actor.
    ///
    /// Must be called from within a Tokio runtime context.
    pub(crate) fn spawn(self) -> SupervisorHandle {
        let (tx, rx) = mpsc::channel(MAILBOX_CAPACITY);
        let actor = self.build(tx.clone());
        tokio::spawn(actor.run(rx));
        SupervisorHandle { tx }
    }

    /// Spawns the actor around a flock this image inherited, restoring
    /// `counters` before any slot is installed. Every sheep in `flock` goes in
    /// under the id, epoch, status and history the blob carried, around the
    /// descriptors that crossed the `execve`. Nothing here spawns, signals or
    /// reopens anything. `reloads` is the apps that were mid-swap, restored
    /// once the flock is in. Must be called from within a Tokio runtime
    /// context.
    ///
    /// # Errors
    ///
    /// - [`AdoptError::Spec`]: a carried config does not normalize.
    /// - [`AdoptError::Runner`]: the runner refused the inherited handles.
    #[cfg(unix)]
    pub(crate) fn spawn_adopted(
        self,
        flock: Vec<AdoptedSheep>,
        counters: Counters,
        reloads: Vec<CarriedReload>,
    ) -> Result<SupervisorHandle, AdoptError> {
        let (tx, rx) = mpsc::channel(MAILBOX_CAPACITY);
        let mut actor = self.build(tx.clone());
        // Counters before slots: a fresh sheep must not be handed an id a
        // caller is still holding.
        actor.next_id = counters.next_id;
        actor.next_deadline = counters.next_deadline;
        actor.next_action_stamp = counters.next_action_stamp;
        // One reaper for the whole adopted flock: a status can be collected
        // once, so two reapers racing on one pid would have one take the exit
        // and the other meet `ECHILD`.
        let reaper = Arc::new(AdoptedReaper::new());
        for sheep in flock {
            actor.install_adopted(sheep, &reaper)?;
        }
        // After the loop and before the actor runs: a job names two entries,
        // so it has nowhere to go until every sheep is in, and the readiness
        // waits `install_adopted` armed report into a mailbox nothing drains.
        actor.install_carried_reloads(reloads);
        tokio::spawn(actor.run(rx));
        Ok(SupervisorHandle { tx })
    }

    /// The actor both spawn paths start from: no sheep, counters at zero.
    fn build(self, tx: mpsc::Sender<Msg>) -> Actor<R> {
        let provider_secrets = self
            .provider_secrets
            .unwrap_or_else(|| Arc::new(ProviderSecrets::load(&self.paths.secrets_cache)));
        #[cfg(unix)]
        let listeners = self
            .adopted_listeners
            .into_iter()
            .map(|adopted| (adopted.sheep, Arc::new(adopted.sockets)))
            .collect();
        #[cfg(not(unix))]
        let listeners = BTreeMap::new();
        Actor {
            runner: self.runner,
            paths: self.paths,
            events: self.events,
            host_environment: self.environment,
            dog_binaries: self.dog_binaries,
            provider_secrets,
            tx,
            sheep: HashMap::new(),
            next_id: 0,
            next_deadline: 0,
            next_action_stamp: 0,
            pending: Vec::new(),
            shutting_down: false,
            extras: self.extras,
            registry: ExtrasRegistry::default(),
            reloads: HashMap::new(),
            smits: Smits::new(),
            disabled: BTreeSet::new(),
            listeners,
            listeners_before: BTreeMap::new(),
            cgroup_base: self.cgroup_base,
            cgroup_unavailable: self.cgroup_unavailable,
            oom_baselines: HashMap::new(),
        }
    }
}

/// Spawns the actor with no lifecycle extras and no dog defaults, which `boot`
/// reads: shorthand for `SupervisorBuilder::new(runner, paths, events).spawn()`.
///
/// Must be called from within a Tokio runtime context: it spawns the actor
/// task immediately.
pub fn spawn_supervisor<R: ProcessRunner>(
    runner: R,
    paths: ShepPaths,
    events: Bus,
) -> SupervisorHandle {
    SupervisorBuilder::new(runner, paths, events).spawn()
}