Enum Request 

#[non_exhaustive]
pub enum Request {
    Ping,
    ListFlock,
    Describe {
        selector: SelectorSpec,
    },
    Start {
        apps: Vec<AppConfig>,
    },
    Add {
        apps: Vec<AppConfig>,
    },
    ConfigDrift {
        apps: Vec<AppConfig>,
    },
    ApplyConfig {
        apps: Vec<DeclaredApp>,
        reset: ResetDepth,
    },
    SheepConfig {
        name: String,
    },
    SetSheepEnv {
        name: String,
        key: String,
        value: Option<EnvValue>,
    },
    SetSheepField {
        name: String,
        key: String,
        value: Value,
    },
    SetDogConfig {
        name: String,
        toml: DogSectionToml,
    },
    Stop {
        selector: SelectorSpec,
    },
    Restart {
        selector: SelectorSpec,
    },
    Reload {
        selector: SelectorSpec,
    },
    Delete {
        selector: SelectorSpec,
    },
    Scale {
        name: String,
        count: u32,
    },
    SetSmit {
        sheep: String,
        smit: Option<Smit>,
    },
    Reopen {
        selector: SelectorSpec,
    },
    Flush {
        selector: SelectorSpec,
    },
    Trigger {
        selector: SelectorSpec,
        action: String,
        params: Option<String>,
    },
    Signal {
        selector: SelectorSpec,
        signal: String,
    },
    SendLine {
        selector: SelectorSpec,
        line: String,
    },
    SaveRoll,
    Muster,
    DogConfig {
        name: String,
    },
    EnableDog {
        name: String,
        source: DogSource,
    },
    DisableDog {
        name: String,
    },
    DogStaleness,
    HandoverFitness,
    KillDaemon,
    Subscribe {
        topics: Vec<String>,
    },
    Unrecognized,
}

One RPC request

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Ping

Liveness check

ListFlock

Full flock listing

Describe

Detailed info for matching sheep

Fields

selector: SelectorSpec

Which sheep

Start

Register + start apps

Fields

apps: Vec<AppConfig>

App configs. The daemon must re-normalize them, since peer input is untrusted; failures return RpcErrorCode::InvalidConfig

Add

Register apps as flock members without starting any of them

Each app lands Stopped and holds no pid; shep add is the verb.

Idempotent by name: an app the flock already has is answered as it stands, running or not, and nothing about it changes. Self::ApplyConfig merges a template into one the flock already has, and shep add sends both.

Answers Response::Added.

Fields

apps: Vec<AppConfig>

App configs, carried exactly as Self::Start carries them. The daemon must re-normalize them, since peer input is untrusted; failures return RpcErrorCode::InvalidConfig

ConfigDrift

Ask which of apps name a sheep the flock already has under a different config

Read-only. Self::Start on an already-registered name adds instances rather than reconciling config.

Answers Response::Drifted with one SheepDrift per app that is both registered and different. An app the flock does not have is absent from the answer, not reported as unchanged.

Fields

apps: Vec<AppConfig>

The configs to compare against, exactly as Self::Start would carry them. The daemon must re-normalize them: peer input is untrusted, and an unnormalized config would report every default it has not spelled out as a difference. Failures return RpcErrorCode::InvalidConfig.

ApplyConfig

Merge each declared app into the sheep of the same name, applying what can be applied and parking the rest for that sheep’s next spawn

Nothing is registered, nothing is pruned and nothing running is killed: an app the flock does not have is refused by name, and a field the running child was spawned from waits for a shep reload. Additive by default; reset widens it.

Answers Response::Applied with one SheepApplied per entry in apps, in the order given, found or not and changed or not. One app’s refusal rides in SheepApplied::refused and does not cost the rest of the file its load.

Fields

apps: Vec<DeclaredApp>

The apps to merge in, each carrying the keys its document literally wrote. The daemon must re-normalize the merge result, since peer input is untrusted, and refuses the whole request with RpcErrorCode::InvalidConfig when two entries share a name: the second would be merged against a store the first has not written yet.

reset: ResetDepth

How much of what the operator has set since a template last loaded this request may overwrite. Default ResetDepth::None, which overwrites nothing.

Spelled none/file/env/policy on the wire.

SheepConfig

One sheep’s effective config, for a pane that is about to edit it.

env comes back emptied and its key names ride separately, so a value never crosses the wire. Read-only: nothing about the sheep changes.

Answers Response::SheepConfig, or RpcErrorCode::NotFound when no sheep has that name.

Fields

name: String

The sheep’s name, not a selector: a pane edits one sheep, for the reason Self::Scale states at length.

SetSheepEnv

Sets, replaces, or with None removes one env key on one sheep, recorded as an operator override. Never reads it back.

Its own request rather than a Self::ApplyConfig depth, because no depth does this: ResetDepth::None appends only, File and Policy leave env alone, and Env/All replace the whole map with the template’s. A pane cannot send the whole map, since it is never told the values it would have to send back.

The running child holds the env it was spawned from, so the change parks for the next spawn exactly as ApplyConfig parks a respawn-only field, and shep reload/shep restart promote it.

Answers Response::SheepEnvSet, or RpcErrorCode::NotFound when no sheep has that name.

Fields

name: String

The sheep’s name, not a selector, for Self::SheepConfig’s reason.

key: String

The env key.

value: Option<EnvValue>

The value, or None to remove the key.

EnvValue, not a bare String, for the reason that type’s own doc gives: this is the most secret-dense field on the wire and a derived Debug on Request would print it (IR-41).

SetSheepField

Sets one config field on one sheep, recorded as an operator override.

Self::SetSheepEnv’s twin for everything that is not env, and it exists for the reason that one does rather than by symmetry. Self::ApplyConfig can move a single field (one DeclaredApp declaring one key, at ResetDepth::File), but it moves it as a template and spends the operator’s override for it. That reasoning does not hold here: a pane’s value is the operator’s, and the sheep still differs from its file. Routed through ApplyConfig, the * marker would never appear for that edit.

One field, not a map: a pane edits one row at a time, and a request that took several would need Response::Applied’s per-field reporting back again for no caller that wants it.

env is refused here and goes through Self::SetSheepEnv. So are name and instances, which are ApplyGroup::Structural: identity and flock shape rather than runtime knobs, and the count moves through Self::Scale.

The four-way apply classification governs exactly as it does for a load. A Live field is in force at the daemon’s next decision, a NextSpawn field reaches the stored spec, and a NeedsRespawn field parks for shep reload to promote.

Answers Response::SheepFieldSet, or RpcErrorCode::NotFound when no sheep has that name.

Fields

name: String

The sheep’s name, not a selector, for Self::SheepConfig’s reason.

key: String

The AppConfig field to set. A key that type has no such field is refused with RpcErrorCode::InvalidConfig rather than ignored.

value: Value

The new value, in the shape that field serializes as. The daemon must re-validate the resulting config (peer input is untrusted) and refuses with RpcErrorCode::InvalidConfig when it does not deserialize or does not normalize; nothing is written in either case.

A bare serde_json::Value and not a redacting newtype, unlike Self::SetSheepEnv’s EnvValue, and the asymmetry is deliberate. env is the one field AppConfig’s own manual Debug redacts; cwd, script and args are printed in the clear by every request that already carries a whole config (Self::Start, Self::Add, Self::ApplyConfig). A newtype here would protect one copy of a value this enum prints three other ways, which reads as a guarantee the wire does not make. Widening that protection is a change to AppConfig’s Debug, not to this field.

SetDogConfig

Replaces one dog’s [<name>] section in dogs.toml and publishes config.dog.<name> so a running dog re-reads it.

The writing twin of Self::DogConfig, which reads the same section.

Answers Response::DogConfigSet.

Fields

name: String

The dog’s name, the config key.

toml: DogSectionToml

The whole section, as TOML text.

DogSectionToml, not a bare String, for the reason that type’s own doc gives: a section can hold a dog’s credentials and this is what keeps them out of a {:?} (IR-41).

Stop

Stop matching sheep (stay registered)

Fields

selector: SelectorSpec

Which sheep

Restart

Restart matching sheep

Fields

selector: SelectorSpec

Which sheep

Reload

Replace each matching sheep with a fresh instance of the same app, one instance of an app at a time, so the app has a window in which it can stay reachable across the swap

Fields

selector: SelectorSpec

Which sheep. No default: a reload replaces running processes.

Delete

Stop + deregister matching sheep

Fields

selector: SelectorSpec

Which sheep

Scale

Set how many instances one app runs (see shep stock).

Takes a name where every other verb takes a SelectorSpec: instances is a per-app number and slots are allocated against the same-name group, so a selector matching two apps could mean four of each or four in total.

The count is absolute: two operators sending +2 against the same app would get a number neither asked for.

Fields

name: String

The app’s name, exactly as its config spells it. Not a selector: no all, no regex, no fold:.

count: u32

How many instances the app has when this returns. 0 is refused with RpcErrorCode::InvalidConfig: shep delete is the verb for removing an app.

SetSmit

Attach a short marker to sheep for shep flock to paint, or clear it with None.

By name, not a selector: a smit belongs to a sheep, and every instance of that name shows it, one spawned after the paint included.

Held in memory and scoped to the connection that sent it, so a publisher republishes rather than publishing on change.

Fields

sheep: String

Which sheep.

smit: Option<Smit>

The marker, or None to clear it.

Reopen

Reopen every matched sheep’s log files, for an external rotator that has renamed them (create-mode rotation)

Fields

selector: SelectorSpec

Which sheep

Flush

Empty every matched sheep’s log files: flush what is still pending, then truncate the recorded paths

Fields

selector: SelectorSpec

Which sheep. No default: this destroys log data.

Trigger

Send a named action to every matched sheep over its shepherd channel and report what each app says back (see shep trigger).

Fields

selector: SelectorSpec

Which sheep. No default, matching every other verb that reaches a running process.

action: String

The action name. Free-form: the daemon never declares, parses, or validates it, and an app that does not recognize the name is expected to say so in its own reply.

params: Option<String>

Argument text, passed through to the app verbatim. One opaque string, matching the shepherd channel’s own action message this becomes.

Signal

Deliver one signal to every matched sheep’s own process, never its process group (see shep signal).

Fields

selector: SelectorSpec

Which sheep. No default, matching every other verb that reaches a running process.

signal: String

The signal’s name, as OperatorSignal spells it. The SIG prefix and the case are both optional; a name outside the grammar answers RpcErrorCode::InvalidConfig.

SendLine

Write one line to every matched sheep’s stdin (see shep whisper).

Fields

selector: SelectorSpec

Which sheep. No default, matching every other verb that reaches a running process.

line: String

The line, without its terminator: the shepherd appends exactly one \n when it writes.

A line containing an embedded newline is refused (RpcErrorCode::InvalidConfig): it would deliver two commands where the operator typed one.

SaveRoll

Write the muster roll now, bypassing the snapshot writer’s debounce

Muster

Assemble the flock from the muster roll on disk: start every app the roll recorded running, leaving every app the flock already has exactly as it stands

DogConfig

Ask for one dog’s [dog.<name>] section, as the dog itself parses it

Fields

name: String

The dog’s name: the config key, not a selector

EnableDog

Start one dog now, marking it as coming from source

Fields

name: String

The dog’s name

source: DogSource

Where its binary comes from

DisableDog

Stop and deregister one dog

Answers Response::Deleted: disabling deregisters exactly as Delete does.

Fields

name: String

The dog’s name

DogStaleness

Ask which dogs this daemon has given up on, and which it is still waiting to hear from (shep daemon reload).

Read-only, and about this daemon’s own handshakes: take the reading after a reload, not before one. Never sent to an older daemon, on Self::HandoverFitness’s terms.

Answers Response::DogStaleness.

HandoverFitness

Ask whether this daemon could hand its flock to a successor in place, rather than stopping it and starting it again (shep daemon reload).

Read-only: the handover itself is triggered by a signal, which reaches a daemon that refuses the client at the handshake.

Answers Response::HandoverFitness. A refusal is a feature the running daemon cannot carry, not an error: the caller falls back to a stop-and-start and prints the reason. Never sent to an older daemon: shep-cli’s commands::daemon gates it on the crate version the handshake reported.

KillDaemon

Graceful daemon shutdown

Subscribe

Subscribe this connection to bus topics (glob patterns)

Fields

topics: Vec<String>

Topic globs, e.g. process.*

Unrecognized

A request kind this build has not been taught.

#[serde(other)], which serde allows here because Request is internally tagged and this variant carries nothing. The unknown body’s own fields are discarded: the only thing to do with a request we cannot name is refuse it, and the refusal needs the envelope’s id rather than the body.

Trait Implementations

impl Clone for Request

fn clone(&self) -> Request

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Request

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Request

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Request

fn eq(&self, other: &Request) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Request

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Request