pub struct Client { /* private fields */ }Expand description
A live connection to the daemon.
Backed by one actor task (see the crate’s actor module) that owns the
socket; request/request_with_deadline/close all take &self, so
callers share one Client behind an Arc or a reference rather than
cloning a handle per caller.
Implementations§
Source§impl Client
impl Client
Sourcepub async fn connect(socket: &Path) -> Result<Self, ConnectError>
pub async fn connect(socket: &Path) -> Result<Self, ConnectError>
Connects to socket and performs the version handshake, bounded by
HANDSHAKE_TIMEOUT.
§Errors
Sourcepub async fn connect_with_timeout(
socket: &Path,
timeout: Duration,
) -> Result<Self, ConnectError>
pub async fn connect_with_timeout( socket: &Path, timeout: Duration, ) -> Result<Self, ConnectError>
As Self::connect, but with a caller-supplied handshake timeout.
§Errors
ConnectError::Connect: the initialconnect(2)call failed.ConnectError::Wire:Hellofailed to encode, or the reply failed to decode.ConnectError::Io: a framed read or write failed after connect.ConnectError::HandshakeClosed: the peer closed before aHelloReply.ConnectError::HandshakeTimeout: noHelloReplyarrived withintimeout.ConnectError::ProtocolMismatch: the daemon refused on protocol-version skew.
Sourcepub async fn connect_ssh(dest: &str) -> Result<Self, ConnectError>
pub async fn connect_ssh(dest: &str) -> Result<Self, ConnectError>
Connects to the shepherd on another host through the system ssh,
with SshOptions::default.
Shorthand for Self::connect_ssh_with.
§Example
use shep_client::Client;
use shep_client::shep_core::protocol::Request;
let client = Client::connect_ssh("deploy@build-01").await?;
let flock = client.request(Request::ListFlock).await?;§Errors
Sourcepub async fn connect_ssh_with(
dest: &str,
options: &SshOptions,
) -> Result<Self, ConnectError>
pub async fn connect_ssh_with( dest: &str, options: &SshOptions, ) -> Result<Self, ConnectError>
Connects to the shepherd on another host by running
ssh -T [-o BatchMode=yes] -- <dest> shep dial-stdio and handshaking
over the child’s pipes.
§Example
use std::time::Duration;
use shep_client::{Client, SshOptions};
let options = SshOptions::default()
.batch_mode(true)
.timeout(Some(Duration::from_secs(10)));
let client = Client::connect_ssh_with("build-01", &options).await?;
assert_eq!(client.host(), Some("build-01"));§Errors
ConnectError::Destination:destis not a destination ssh can be handed safely. ssh would read-oProxyCommand=..as an option and run it.ConnectError::Ssh: ssh could not run, reach the host, or be served by the far side.ConnectError::Wire,ConnectError::Io: a frame failed to encode or decode.ConnectError::HandshakeClosed: the stream closed before aHelloReply.ConnectError::HandshakeTimeout: the phase ran pastSshOptions::timeout.ConnectError::ProtocolMismatch: the shepherd refused on version skew.
Sourcepub async fn closed(&self)
pub async fn closed(&self)
Resolves once this connection has ended: daemon exit, crash,
execve, a write failure, or a prior Self::close. Resolves
immediately if already gone, and may be awaited more than once.
This does not reconnect, and Self::request does not retry. See
ReconnectingClient for the supervised
wrapper.
Sourcepub fn socket(&self) -> &Path
pub fn socket(&self) -> &Path
The path this client is connected through.
HelloAck doesn’t carry the socket path, so the Client keeps the
PathBuf it connected with, for a caller that needs it after
teardown. Empty for a client from Self::connect_ssh, which has no
socket on this host: see Self::host.
Sourcepub fn host(&self) -> Option<&str>
pub fn host(&self) -> Option<&str>
The destination this client reached over ssh, or None for a client
connected to a socket on this host.
Sourcepub async fn request(&self, body: Request) -> Result<Response, RequestError>
pub async fn request(&self, body: Request) -> Result<Response, RequestError>
Sourcepub async fn request_with_deadline(
&self,
body: Request,
deadline: Option<Duration>,
) -> Result<Response, RequestError>
pub async fn request_with_deadline( &self, body: Request, deadline: Option<Duration>, ) -> Result<Response, RequestError>
Sends body with deadline, or DEFAULT_DEADLINE if None. The
client waits deadline plus DEADLINE_GRACE for a reply before
giving up locally.
§Errors
RequestError::Rpc: the daemon answered with a structured error, orbodycarries a key a shepherd below its protocol version would drop (dogs.sandbox,sandbox,listen,memory_enforce,max_cpu_cores,max_tasks,pty; seeRequest::gated_key_dropped_at), which is refused asUnsupportedbefore anything is sent.RequestError::Timeout: no reply withindeadline + DEADLINE_GRACE.RequestError::Closed: the connection closed before a reply arrived.RequestError::Wire:bodyfailed to encode.
Sourcepub async fn subscribe(
&self,
topics: Vec<String>,
) -> Result<EventStream, RequestError>
pub async fn subscribe( &self, topics: Vec<String>, ) -> Result<EventStream, RequestError>
Subscribes this connection to topics: dotted glob patterns matched
against shep_core::protocol::BusEvent::topic (process.*,
log.*, daemon.*, …).
A second call on the same Client replaces the daemon-side filter
rather than adding to it; a caller wanting two topic sets needs two
Clients. The returned EventStream’s receiver is installed
before the Subscribe request is sent, so no pushed event is missed.
§Errors
Same as Self::request.
Sourcepub async fn events(&self) -> Result<EventStream, RequestError>
pub async fn events(&self) -> Result<EventStream, RequestError>
A stream of what this connection is already being sent, with no
Subscribe to change what that is.
For the events a request opens on its own, such as the pty.out
frames after a Request::Attach. Open it before sending that request:
a receiver sees nothing sent before it existed.
§Errors
RequestError::Closed: the connection is already gone.
Sourcepub async fn close(self) -> Result<(), RequestError>
pub async fn close(self) -> Result<(), RequestError>
Closes the connection.
Drops the command channel to the actor task, which ends the actor’s loop and drops the underlying socket.
§Errors
Never fails today. Result leaves room for a later, more graceful
teardown (draining in-flight requests before dropping, say) to start
returning one without an API break.
Source§impl Client
impl Client
Sourcepub async fn reconnect(&mut self) -> Result<Reconnected, ConnectError>
pub async fn reconnect(&mut self) -> Result<Reconnected, ConnectError>
Re-establishes this connection, reporting which daemon answered.
Shorthand for Self::reconnect_within with HANDSHAKE_TIMEOUT.
§Errors
Sourcepub async fn reconnect_within(
&mut self,
budget: Duration,
) -> Result<Reconnected, ConnectError>
pub async fn reconnect_within( &mut self, budget: Duration, ) -> Result<Reconnected, ConnectError>
Re-establishes this connection, retrying until budget is spent.
Meant for a connection that has already ended, as Self::closed
reports. A successor still coming up is retried, from
RECONNECT_MIN_DELAY doubling to RECONNECT_MAX_DELAY; a refusal is
not. Safe to cancel: the old connection is held until a new one
handshakes. An EventStream belongs to the connection it was taken on.
§Example
use shep_client::{Client, Reconnected};
client.closed().await;
if client.reconnect().await? == Reconnected::NewDaemon {
// Ids are minted per daemon and never persisted, so this one now
// names a different sheep, or none at all.
*held = None;
}§Errors
ConnectError::ProtocolMismatch: a daemon refused on version skew, and is not asked again.- Anything else
Self::connect_with_timeoutreports, oncebudgetleaves no room.
Source§impl Client
impl Client
Sourcepub async fn dog_config(
&self,
name: &str,
) -> Result<DogSectionToml, RequestError>
pub async fn dog_config( &self, name: &str, ) -> Result<DogSectionToml, RequestError>
The dog name’s own section of dogs.toml with every
{{secret:...}} reference resolved, empty when it has none.
Asks Request::DogConfigResolved. A shepherd too old to know it
is asked Request::DogConfig instead, and a section that still
holds a reference is refused rather than handed over unresolved.
§Errors
As Self::request, and RequestError::UnexpectedReply for any
answer but Response::DogSection. RequestError::Rpc with
RpcErrorCode::Unsupported when an older shepherd’s section names
a secret reference it cannot resolve.
Sourcepub async fn sheep_dog_table(
&self,
name: &str,
dog: &str,
) -> Result<Option<DogTable>, RequestError>
pub async fn sheep_dog_table( &self, name: &str, dog: &str, ) -> Result<Option<DogTable>, RequestError>
The sheep name’s [app.dogs.<dog>] table, with every
{{secret:...}} reference resolved in that sheep’s own environment.
None when it carries no such table.
Asks Request::SheepDogSettingsResolved. A shepherd too old to know
it is asked Request::DogSheepSettings instead, and a table still
holding a reference is refused rather than handed over unresolved.
§Errors
As Self::request: RpcErrorCode::NotFound for a name no sheep
holds, and RpcErrorCode::InvalidConfig for a reference that cannot
resolve. A different answer gives RequestError::UnexpectedReply.
Sourcepub async fn list_flock(&self) -> Result<Vec<ProcessInfo>, RequestError>
pub async fn list_flock(&self) -> Result<Vec<ProcessInfo>, RequestError>
Every supervised entry, dogs included.
§Errors
As Self::request, and RequestError::UnexpectedReply for any
answer but Response::Flock.
Sourcepub async fn reopen(
&self,
selector: SelectorSpec,
) -> Result<Vec<ProcessInfo>, RequestError>
pub async fn reopen( &self, selector: SelectorSpec, ) -> Result<Vec<ProcessInfo>, RequestError>
Reopens the log files of every sheep selector matches, under
LOG_PLANE_DEADLINE, answering each one it matched.
§Errors
As Self::request, and RequestError::UnexpectedReply for any
answer but Response::Reopened.
Sourcepub async fn host_usage(&self) -> Result<Option<HostUsage>, RequestError>
pub async fn host_usage(&self) -> Result<Option<HostUsage>, RequestError>
What the flock’s machine is doing, or None where the shepherd
cannot read its host at all.
§Errors
As Self::request, and RequestError::UnexpectedReply for any
answer but Response::HostUsage.
Sourcepub async fn publish_event(
&self,
event: &str,
payload: Value,
) -> Result<(), RequestError>
pub async fn publish_event( &self, event: &str, payload: Value, ) -> Result<(), RequestError>
Publishes payload as the event kind event of the dog on this
connection: it reaches subscribers as dog.<name>.<event>.
Asks Request::PublishEvent, which only a dog’s own connection may
send. The shepherd checks that event is in the dog’s manifest and
nothing about payload.
§Errors
As Self::request: RpcErrorCode::Forbidden naming the kind when
the dog did not declare it or this is not a dog’s connection. A
different answer gives RequestError::UnexpectedReply.
Sourcepub async fn tail_log(
&self,
id: u32,
stream: LogStream,
lines: u32,
) -> Result<LogTail, RequestError>
pub async fn tail_log( &self, id: u32, stream: LogStream, lines: u32, ) -> Result<LogTail, RequestError>
The last lines lines of one sheep’s out or err log, read by the
shepherd on its own host.
A file that is absent, unreadable or not recorded is a LogTail
variant, not an error.
§Errors
As Self::request, including RpcErrorCode::NotFound for an id
no sheep holds, and RequestError::UnexpectedReply for any answer
but Response::LogTail.