Struct Client 

pub struct Client { /* private fields */ }

A connection to a host.

Async because the transport is. A caller that wants blocking behavior runs it on a runtime it owns; the crate does not choose one on its behalf.

Implementations

impl Client

pub async fn connect(address: &str) -> Result<Self, Error>

Connects to a host.

address is a websocket URL, such as ws://127.0.0.1:50751.

Errors

Error::Transport if the connection or handshake fails.

pub async fn connect_with_backoff( address: &str, backoff: Backoff, ) -> Result<Self, Error>

Connects, retrying while the host is unreachable.

For a panel meant to survive a host restart. Returns the last failure once the attempts run out, rather than looping for ever, so a caller still learns that the host is gone.

Errors

Error::Transport carrying the final failure.

pub async fn send(&mut self, command: &Command) -> Result<(), Error>

Sends one command.

Errors

Error::Payload if the command cannot be encoded, or Error::Transport if the socket refuses it.

pub async fn next(&mut self) -> Result<Option<Inbound>, Error>

Reads the next acknowledgement or event.

Returns None once the host closes the connection. Frames that are not text are skipped, so a ping or a pong does not look like an answer.

Errors

Error::Transport if the socket fails, or Error::Payload if a text frame is neither shape.

pub async fn close(self, observe: impl FnMut(Inbound)) -> Result<(), Error>

Starts a close, then reads until the peer closes back.

RFC 6455 section 5.5.1 makes closing a handshake rather than a hang-up: each side sends a Close and waits for the other. Dropping the socket without it leaves the peer to time out.

No data frame goes out after the Close, which the same section forbids. This only reads from that point on.

Messages arriving before the peer’s Close are handed to observe, since a run can still be reporting when a client decides to leave.

Errors

Error::Transport if the Close cannot be sent.

pub async fn ping(&mut self, payload: Vec<u8>) -> Result<(), Error>

Sends a ping carrying payload.

RFC 6455 section 5.5.2: an endpoint receiving a Ping MUST answer with a Pong, unless it has already received a Close. The section names this use directly, as a keepalive or a way to check the peer still responds, which is what a connection count alone cannot tell you.

The pong is consumed by the library rather than surfaced here, so this proves liveness by the absence of a transport error rather than by a returned value.

A payload over MAX_CONTROL_PAYLOAD is refused here. Section 5.5 caps every control frame at 125 bytes, and measured against a live peer an oversized ping is not rejected on the way out: the send reports success and the connection is then torn down, so the caller is told the ping worked and loses the session. Refusing before the send turns a silent kill into an error the caller can act on.

Errors

Error::ControlFrameTooLarge if the payload exceeds the cap, or Error::Transport if the ping cannot be sent.

pub async fn request( &mut self, command: &Command, observe: impl FnMut(&MessageEvent), ) -> Result<Ack, Error>

Sends a command and reads until its acknowledgement arrives.

Events that arrive first are handed to observe rather than dropped, because a run reports progress while a command is in flight and a caller that discards those loses the trace.

Errors

Error if the send fails, the socket fails, or the host closes before answering.

Trait Implementations

impl Debug for Client

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

Formats the value using the given formatter.