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
impl ReconnectingClient
Sourcepub async fn connect(socket: &Path) -> Result<Self, ConnectError>
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
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,
used for the first connection and for every reconnect after it.
§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_as_dog(
socket: &Path,
name: &str,
) -> Result<Self, ConnectError>
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
Sourcepub async fn connect_as_dog_with_timeout(
socket: &Path,
timeout: Duration,
name: &str,
) -> Result<Self, ConnectError>
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
Sourcepub async fn connect_as(
socket: &Path,
identity: &DogIdentity,
) -> Result<Self, ConnectError>
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
Sourcepub fn dog_name(&self) -> Option<&str>
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.
Sourcepub fn daemon(&self) -> HelloAck
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.
Sourcepub async fn request(&self, body: Request) -> Result<Response, RequestError>
pub async fn request(&self, body: Request) -> Result<Response, RequestError>
Sends body with DEFAULT_DEADLINE on
the current generation of the connection.
§Errors
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 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
RequestError::Rpc: the daemon answered with a structured error.RequestError::Timeout: no reply within the request’s budget.RequestError::Closed: the connection closed before a reply arrived, or already had.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 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.
Sourcepub async fn connected_within(&self, budget: Duration) -> Result<(), LinkLost>
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
LinkLost::Refused: a successor refused on version skew, and the supervisor stopped.LinkLost::Budget:budgetran out with the supervisor still dialling.
Sourcepub async fn link_lost(&self, budget: Duration) -> LinkLost
pub async fn link_lost(&self, budget: Duration) -> LinkLost
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
impl ReconnectingClient
Sourcepub async fn publish_event(
&self,
event: &str,
payload: Value,
) -> Result<(), RequestError>
pub async fn publish_event( &self, event: &str, payload: Value, ) -> Result<(), RequestError>
Sourcepub async fn dog_config(
&self,
name: &str,
) -> Result<DogSectionToml, RequestError>
pub async fn dog_config( &self, name: &str, ) -> Result<DogSectionToml, RequestError>
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>
Shorthand for Client::sheep_dog_table on the current generation.
§Errors
Sourcepub async fn list_flock(&self) -> Result<Vec<ProcessInfo>, RequestError>
pub async fn list_flock(&self) -> Result<Vec<ProcessInfo>, RequestError>
Sourcepub async fn reopen(
&self,
selector: SelectorSpec,
) -> Result<Vec<ProcessInfo>, RequestError>
pub async fn reopen( &self, selector: SelectorSpec, ) -> Result<Vec<ProcessInfo>, RequestError>
Sourcepub async fn host_usage(&self) -> Result<Option<HostUsage>, RequestError>
pub async fn host_usage(&self) -> Result<Option<HostUsage>, RequestError>
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.
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§impl Drop for ReconnectingClient
Stops the supervisor when the handle goes away.
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.