Expand description
Speak the shep shepherd channel: signal readiness, emit a metric,
answer an action. docs/shepherd-channel.md has the contract.
With no channel, nothing is sent and no handler runs. Registering one still succeeds, so an app needs no branch at its call sites.
let shepherd = shep_channel::serve();
shepherd.on_action("gc", |params, _name| {
format!("collected, params={params:?}")
});
shepherd.on_shutdown(|| { /* stop gracefully */ });
// No channel here: this test runs outside shep. See `is_active`.
assert!(!shepherd.is_active());
shepherd.metric("rps", 4200.0);
shepherd.ready().unwrap();
// Before the app exits, so a queued reply is not lost with it.
shepherd.flush(std::time::Duration::from_secs(2)).unwrap();- An action’s handler runs on its own thread, never delaying the reader.
metricandnotedrop under backpressure;readyand a reply block.- Sending queues, and a writer thread writes. Call
flushbefore exiting. - An unhandled shutdown warns on stderr. This crate never stops a process.
Structs§
- Channel
- The channel with no threads: you own the loop.
- Lamb
Label - A sheep’s own name for one of its lambs
- Metric
Options - The optional half of a metric sample: kind, labels and help text.
- Shepherd
- A handle on this process’s shepherd channel.
Enums§
- Channel
Error - Anything that can go wrong on the shepherd channel.
- Child
Message - Child -> daemon shepherd-channel message (spec §7, kebab-case kinds)
- Endpoint
- Where this process’s channel is, if it has one.
- Lamb
Label Error - Why a string is not a
LambLabel. - Metric
Type - What kind of number a
ChildMessage::Metricsample is - Shepherd
Message - Daemon -> child message
Constants§
- CHANNEL_
VERSION - The value the shepherd exports as
SHEP_CHANNEL_VERSIONto every child it opens a channel for. - FD_VAR
- The descriptor number variable, set on unix only.
- PIPE_
VAR - The named pipe variable, set on Windows only.
- VERSION_
VAR - The wire version stamp, set on both platforms whenever a channel exists.
Functions§
- discover
- Reads the environment and says where the channel is.
- serve
- Opens this process’s channel and starts serving it.
- take_
inherited_ socket - Takes the connected socket the shepherd handed this process, named by the
environment variable
var.Ok(None)whenvaris unset.
Type Aliases§
- Action
Handler - What an action handler is: params, then the action’s own name. Returns the reply body the operator reads.
- Caller
Action Handler - What an action handler is when it also wants to know who triggered
the action: params, the action’s own name, then the calling dog’s name.
The caller is
Nonefor the operator, and for a shepherd that predates the field. - Shutdown
Handler - What a shutdown handler is.