pub struct Client { /* private fields */ }Expand description
A connection to a WSE server, made again when it is lost.
Clones share the connection, which lives as long as the application
holds a handle (or until close); the client a handler
is given by connect_with does not keep it.
Sends go out in the order they were made; what the server sends goes to
the Handler the client was made with, or to the
Events of connect.
A message still queued when the connection is lost goes out on the next one, unless the server takes that one for another user: then it goes nowhere, and the topics start over. A signed message goes out on the connection it was signed on, or not at all.
Implementations§
Source§impl Client
impl Client
Sourcepub async fn connect<H: Handler>(
config: Config,
handler: H,
) -> Result<Self, Error>
pub async fn connect<H: Handler>( config: Config, handler: H, ) -> Result<Self, Error>
Connects, and returns once the server took the connection. What it
sends goes to handler.
The first connection is not made again when it fails: the error is
returned. Later ones are, as Config::reconnect says.
Sourcepub async fn connect_with<H, F>(config: Config, make: F) -> Result<Self, Error>
pub async fn connect_with<H, F>(config: Config, make: F) -> Result<Self, Error>
connect with a handler that is given the client,
to send from it.
Sourcepub async fn start<H: Handler>(
config: Config,
handler: H,
) -> Result<Self, Error>
pub async fn start<H: Handler>( config: Config, handler: H, ) -> Result<Self, Error>
Starts, and returns at once: the connection is made in the
background, a failed first attempt made again as any later one
(Config::reconnect). What is sent meanwhile waits in the outbox.
For an application that may start without a network; a client that
gives up says so in Client::closed.
Sourcepub async fn start_with<H, F>(config: Config, make: F) -> Result<Self, Error>
pub async fn start_with<H, F>(config: Config, make: F) -> Result<Self, Error>
start with a handler that is given the client, to
send from it.
Sourcepub fn try_send<P: Serialize + ?Sized>(
&self,
kind: &str,
payload: &P,
) -> Result<(), Error>
pub fn try_send<P: Serialize + ?Sized>( &self, kind: &str, payload: &P, ) -> Result<(), Error>
Sends a message {"t": kind, "p": payload}; fails at once when the
outbox or the queue is full.
Sourcepub async fn send<P: Serialize + ?Sized>(
&self,
kind: &str,
payload: &P,
) -> Result<(), Error>
pub async fn send<P: Serialize + ?Sized>( &self, kind: &str, payload: &P, ) -> Result<(), Error>
Sends a message {"t": kind, "p": payload}, waiting for room in the
queue. It waits in the outbox (Config::offline, in memory by
default) until the server answers for it, and goes again after a
reconnect; with no outbox, a send with no connection fails with
Error::NotConnected.
Sourcepub async fn send_with<P: Serialize + ?Sized>(
&self,
kind: &str,
payload: &P,
options: &SendOptions,
) -> Result<String, Error>
pub async fn send_with<P: Serialize + ?Sized>( &self, kind: &str, payload: &P, options: &SendOptions, ) -> Result<String, Error>
Client::send with its options: its own id, how long it may
wait, the topics it requires, its correlation id and priority, or
live. Returns its id, which its outcome names
(Event::Delivered,
Event::NotDelivered).
Sourcepub fn try_send_with<P: Serialize + ?Sized>(
&self,
kind: &str,
payload: &P,
options: &SendOptions,
) -> Result<String, Error>
pub fn try_send_with<P: Serialize + ?Sized>( &self, kind: &str, payload: &P, options: &SendOptions, ) -> Result<String, Error>
Client::send_with, failing at once when the outbox or the queue
is full.
Sourcepub fn try_send_live<P: Serialize + ?Sized>(
&self,
kind: &str,
payload: &P,
) -> Result<(), Error>
pub fn try_send_live<P: Serialize + ?Sized>( &self, kind: &str, payload: &P, ) -> Result<(), Error>
Sends a message {"t": kind, "p": payload} on the connection that is
ready now, or not at all: one this connection did not write is
dropped, never sent on a later connection, and it never waits in the
outbox. For commands that must not run late (a valve, a door, an
order). Fails at once when the queue is full.
Sourcepub async fn send_live<P: Serialize + ?Sized>(
&self,
kind: &str,
payload: &P,
) -> Result<(), Error>
pub async fn send_live<P: Serialize + ?Sized>( &self, kind: &str, payload: &P, ) -> Result<(), Error>
Client::try_send_live, waiting for room in the queue.
Sourcepub async fn send_requiring<P, I, T>(
&self,
kind: &str,
payload: &P,
topics: I,
) -> Result<(), Error>
pub async fn send_requiring<P, I, T>( &self, kind: &str, payload: &P, topics: I, ) -> Result<(), Error>
Sends a message {"t": kind, "p": payload} once each of topics is
continuous on the connection (the delivery’s
TopicState): until then it waits, in order with
the others that wait, while sends that require nothing go past it.
It is checked as it is taken to go out, so one waiting does not go
after a reconnect before the resync; it is the user’s who made it, and
goes nowhere once the server takes a connection for another. Waits
for room in the queue.
Sourcepub fn try_send_requiring<P, I, T>(
&self,
kind: &str,
payload: &P,
topics: I,
) -> Result<(), Error>
pub fn try_send_requiring<P, I, T>( &self, kind: &str, payload: &P, topics: I, ) -> Result<(), Error>
Client::send_requiring, failing at once when the outbox or the
queue is full.
Sourcepub async fn send_raw(&self, json: impl Into<String>) -> Result<(), Error>
pub async fn send_raw(&self, json: impl Into<String>) -> Result<(), Error>
Sends JSON text as it is: a message the application built itself, a
JSON object. It waits in the outbox as Client::send does.
Sourcepub async fn send_signed<P: Serialize + ?Sized>(
&self,
kind: &str,
payload: &P,
n: Option<&str>,
) -> Result<String, Error>
pub async fn send_signed<P: Serialize + ?Sized>( &self, kind: &str, payload: &P, n: Option<&str>, ) -> Result<String, Error>
Sends a signed message {"t": kind, "p": payload}: signed with
Config::signing_key for the server’s signing key, so whoever
keeps it can show who sent it. n names it once, 1 to 128
characters (an order id, say; a random one when None). Returns the
n it went with: the server’s signed receipt, or its error
SIGNATURE_REFUSED, names it.
Sourcepub fn pause(&self, reason: impl Into<String>) -> Result<(), Error>
pub fn pause(&self, reason: impl Into<String>) -> Result<(), Error>
Ends the connection for reason ("background", "offline",
…) and makes no attempt while any reason holds: topics and
positions stay, and what is queued goes out first. The last reason
cleared with resume, the client connects at once
and recovers what it missed.
Sourcepub fn resume(&self, reason: impl Into<String>) -> Result<(), Error>
pub fn resume(&self, reason: impl Into<String>) -> Result<(), Error>
Clears reason; once none is left the client connects again.
Sourcepub fn subscribe<I, T>(&self, topics: I) -> Result<(), Error>
pub fn subscribe<I, T>(&self, topics: I) -> Result<(), Error>
Subscribes to topics, on this connection and every later one; after a reconnect the client asks for them from where it left off.
Sourcepub fn unsubscribe<I, T>(&self, topics: I) -> Result<(), Error>
pub fn unsubscribe<I, T>(&self, topics: I) -> Result<(), Error>
Unsubscribes, and forgets where the client stood in the topics.
Sourcepub fn kept(&self) -> usize
pub fn kept(&self) -> usize
How many messages wait in the outbox for the server’s answer
(Config::offline).
Sourcepub fn clear(&self) -> Result<(), Error>
pub fn clear(&self) -> Result<(), Error>
The user signs out: every message in the outbox, and every one sent
before this call, goes (Event::NotDelivered,
cleared), and the user is forgotten, so nothing of theirs is sent as
the next one. One the server has in hand already is delivered if it
confirms it on the current connection.
Sourcepub fn topic_states(&self) -> Vec<TopicState>
pub fn topic_states(&self) -> Vec<TopicState>
Each topic held: whether the server took it, and whether its messages run without a break.
Sourcepub fn commit(&self, message: &Message<'_>)
pub fn commit(&self, message: &Message<'_>)
The consumer applied message (a topic message): the checkpoint
moves on through what was applied without a hole. A message handed
out before the events showed another user counts for nobody. An
OwnedMessage commits as owned.as_message().
Sourcepub fn checkpoint(&self) -> String
pub fn checkpoint(&self) -> String
What the consumer committed, bound to the realm, the user, the
consumer and the schema: to save with the application’s own state and
give back as Delivery::checkpoint.
Sourcepub fn resynced(&self, round: u64) -> Result<(), Error>
pub fn resynced(&self, round: u64) -> Result<(), Error>
recover-or-resync: the application brought the topics of round
(Event::Resync) up to date; what they held
comes next.
Sourcepub fn resync<I, T>(&self, topics: I) -> Result<(), Error>
pub fn resync<I, T>(&self, topics: I) -> Result<(), Error>
Bring topics up to date: in recover-or-resync a resync round asks
for it; in best effort the application did so itself, and they read
continuous again.
Sourcepub async fn close_within(&self, deadline: Duration)
pub async fn close_within(&self, deadline: Duration)
Closes the client, giving what is queued deadline to go out: past
it the connection is dropped where it stands (a link that takes
nothing holds a close for as long as the system keeps the
connection).
Sourcepub async fn closed(&self) -> Option<Error>
pub async fn closed(&self) -> Option<Error>
Waits until the client stops for good; the reason, unless the application closed it.
pub fn status(&self) -> Status
Sourcepub fn is_connected(&self) -> bool
pub fn is_connected(&self) -> bool
The server took the current connection: messages go out.
Sourcepub fn connection_id(&self) -> Option<String>
pub fn connection_id(&self) -> Option<String>
The current connection’s id, as the server named it.