Skip to main content

ReconnectingClient

Struct ReconnectingClient 

Source
pub struct ReconnectingClient { /* private fields */ }
Expand description

A Client that re-establishes its own connection when the daemon it was talking to is replaced.

Built for dogs, which outlive the shepherd they connected to: a dog’s process crosses a daemon handover as an ordinary child, so it is still running when its socket dies. The CLI uses a bare Client instead.

§Example

use shep_client::{ReconnectingClient, shep_core::protocol::Request};

// `name` is what the daemon put in `$SHEP_DOG_NAME` when it spawned
// this process; it lets the daemon act on a refusal (G8).
let client = ReconnectingClient::connect_as_dog(socket, "metrics").await?;
// Survives the daemon being replaced underneath it; a request that was
// in flight at the moment it happened still fails rather than retrying.
let _flock = client.request(Request::ListFlock).await?;

Implementations§

Source§

impl ReconnectingClient

Source

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

Connects to socket, performs the version handshake bounded by HANDSHAKE_TIMEOUT, and starts the supervisor that will re-establish this connection whenever it dies.

The FIRST connection is not supervised: a socket nobody is listening on is a caller’s error, not a handover, so this reports it rather than retrying behind the caller’s back.

§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, used for the first connection and for every reconnect after it.

§Errors
Source

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

As Self::connect, but announcing this client as the dog registered under name, the value the daemon put in $SHEP_DOG_NAME when it spawned this process.

A dog should use this rather than Self::connect: the name makes a refused handshake actionable, since a refusal never reaches a request. Without it, the daemon still stops rather than spins on a refusal, but cannot say which dog went stale or restart it.

§Errors

See Self::connect_with_timeout.

Source

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

As Self::connect_as_dog, but with a caller-supplied handshake timeout, used for the first connection and for every reconnect after it.

§Errors

See Self::connect_with_timeout.

Source

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

Connects as identity says: as its dog when a shepherd named this process, and anonymously when none did.

§Errors

See Self::connect_with_timeout.

Source

pub fn dog_name(&self) -> Option<&str>

The name this client announces itself as a dog under, or None for a caller that is not one.

Source

pub fn daemon(&self) -> HelloAck

The handshake acknowledgement of the daemon this client is talking to right now.

Owned rather than borrowed, unlike Client::daemon: a reconnect can replace the generation this ack came from at any moment. A cached ack would describe the predecessor.

Source

pub fn socket(&self) -> &Path

The path this client connects (and reconnects) through.

What the supervisor is doing right now.

Source

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

Sends body with DEFAULT_DEADLINE on the current generation of the connection.

§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 on the current generation.

Never retried: a request on the wire when the daemon was replaced fails, and so does one issued while reconnecting. Only the connection re-establishes; the caller decides whether resending is safe.

§Errors
Source

pub async fn subscribe( &self, topics: Vec<String>, ) -> Result<EventStream, RequestError>

Subscribes the current generation of the connection to topics.

The returned stream belongs to one generation and is not re-armed across a reconnect: it ends when that connection dies, like Client::subscribe’s would. A consumer that wants events past a handover subscribes again; re-arming here would silently swallow the gap between the old connection dying and a new Subscribe.

§Errors

Same as Self::request.

Source

pub async fn connected_within(&self, budget: Duration) -> Result<(), LinkLost>

Waits for the supervisor to be on a connection again, for at most budget, and returns at once when it already is.

What a caller needing a fresh EventStream after a handover waits on. A Subscribe issued against a dead generation fails at once with RequestError::Closed. That says nothing about a successor on its way. A returned Ok is where to try, never a promise: the report can still say LinkState::Connected in the moment after a socket dies.

§Errors

Waits until the link has been down for a whole budget without coming back, or has been refused.

The clock runs only while the link is down, so a connection that drops and returns inside budget leaves the next one a full budget. Never resolves while the link is up, which is what lets it sit in a select! arm beside a caller’s own work.

Source§

impl ReconnectingClient

Source

pub async fn publish_event( &self, event: &str, payload: Value, ) -> Result<(), RequestError>

Shorthand for Client::publish_event on the current generation.

§Errors

As Client::publish_event.

Source

pub async fn dog_config( &self, name: &str, ) -> Result<DogSectionToml, RequestError>

Shorthand for Client::dog_config on the current generation.

§Errors

As Client::dog_config.

Source

pub async fn sheep_dog_table( &self, name: &str, dog: &str, ) -> Result<Option<DogTable>, RequestError>

Shorthand for Client::sheep_dog_table on the current generation.

§Errors

As Client::sheep_dog_table.

Source

pub async fn list_flock(&self) -> Result<Vec<ProcessInfo>, RequestError>

Shorthand for Client::list_flock on the current generation.

§Errors

As Client::list_flock.

Source

pub async fn reopen( &self, selector: SelectorSpec, ) -> Result<Vec<ProcessInfo>, RequestError>

Shorthand for Client::reopen on the current generation.

§Errors

As Client::reopen.

Source

pub async fn host_usage(&self) -> Result<Option<HostUsage>, RequestError>

Shorthand for Client::host_usage on the current generation.

§Errors

As Client::host_usage.

Source

pub async fn tail_log( &self, id: u32, stream: LogStream, lines: u32, ) -> Result<LogTail, RequestError>

Shorthand for Client::tail_log on the current generation.

§Errors

As Client::tail_log.

Trait Implementations§

Source§

impl Debug for ReconnectingClient

Manual, not derived: the socket path and the HelloAck carry no secret, and neither does LinkState, whose one payload is the daemon’s own refusal sentence. Manual because RwLock and JoinHandle derive into noise, and a derived impl would print the inner Client where the link state is the useful fact.

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Drop for ReconnectingClient

Stops the supervisor when the handle goes away.

Without this, a dropped ReconnectingClient whose daemon is gone leaves a task reconnecting forever, holding the last generation’s socket open with it. abort rather than a cooperative signal: the supervisor is parked on a connect attempt that would not see a flag.

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. 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.