Skip to main content

Client

Struct Client 

Source
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

Source

pub async fn connect(socket: &Path) -> Result<Self, ConnectError>

Connects to socket and performs the version handshake, bounded by HANDSHAKE_TIMEOUT.

§Errors

See Self::connect_with_timeout.

Source

pub async fn connect_with_timeout( socket: &Path, timeout: Duration, ) -> Result<Self, ConnectError>

As Self::connect, but with a caller-supplied handshake timeout.

§Errors
Source

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

See Self::connect_ssh_with.

Source

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
Source

pub fn daemon(&self) -> &HelloAck

The daemon’s handshake acknowledgement.

Source

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.

Source

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.

Source

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.

Source

pub async fn request(&self, body: Request) -> Result<Response, RequestError>

Sends body with DEFAULT_DEADLINE.

Shorthand for Self::request_with_deadline(body, None).

§Errors

See Self::request_with_deadline.

Source

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
Source

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.

Source

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.

Source

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

Source

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

See Self::reconnect_within.

Source

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
Source§

impl Client

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Trait Implementations§

Source§

impl Debug for Client

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.