Skip to main content

Crate shep_channel

Crate shep_channel 

Source
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.
  • metric and note drop under backpressure; ready and a reply block.
  • Sending queues, and a writer thread writes. Call flush before exiting.
  • An unhandled shutdown warns on stderr. This crate never stops a process.

Structs§

Channel
The channel with no threads: you own the loop.
LambLabel
A sheep’s own name for one of its lambs
MetricOptions
The optional half of a metric sample: kind, labels and help text.
Shepherd
A handle on this process’s shepherd channel.

Enums§

ChannelError
Anything that can go wrong on the shepherd channel.
ChildMessage
Child -> daemon shepherd-channel message (spec §7, kebab-case kinds)
Endpoint
Where this process’s channel is, if it has one.
LambLabelError
Why a string is not a LambLabel.
MetricType
What kind of number a ChildMessage::Metric sample is
ShepherdMessage
Daemon -> child message

Constants§

CHANNEL_VERSION
The value the shepherd exports as SHEP_CHANNEL_VERSION to 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) when var is unset.

Type Aliases§

ActionHandler
What an action handler is: params, then the action’s own name. Returns the reply body the operator reads.
CallerActionHandler
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 None for the operator, and for a shepherd that predates the field.
ShutdownHandler
What a shutdown handler is.