Skip to main content

Client

Struct Client 

Source
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

Source

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.

Source

pub async fn connect_with<H, F>(config: Config, make: F) -> Result<Self, Error>
where H: Handler, F: FnOnce(Client) -> H,

connect with a handler that is given the client, to send from it.

Source

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.

Source

pub async fn start_with<H, F>(config: Config, make: F) -> Result<Self, Error>
where H: Handler, F: FnOnce(Client) -> H,

start with a handler that is given the client, to send from it.

Source

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.

Source

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.

Source

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).

Source

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.

Source

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.

Source

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.

Source

pub async fn send_requiring<P, I, T>( &self, kind: &str, payload: &P, topics: I, ) -> Result<(), Error>
where P: Serialize + ?Sized, I: IntoIterator<Item = T>, T: Into<String>,

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.

Source

pub fn try_send_requiring<P, I, T>( &self, kind: &str, payload: &P, topics: I, ) -> Result<(), Error>
where P: Serialize + ?Sized, I: IntoIterator<Item = T>, T: Into<String>,

Client::send_requiring, failing at once when the outbox or the queue is full.

Source

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.

Source

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.

Source

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.

Source

pub fn resume(&self, reason: impl Into<String>) -> Result<(), Error>

Clears reason; once none is left the client connects again.

Source

pub fn subscribe<I, T>(&self, topics: I) -> Result<(), Error>
where I: IntoIterator<Item = T>, T: Into<String>,

Subscribes to topics, on this connection and every later one; after a reconnect the client asks for them from where it left off.

Source

pub fn unsubscribe<I, T>(&self, topics: I) -> Result<(), Error>
where I: IntoIterator<Item = T>, T: Into<String>,

Unsubscribes, and forgets where the client stood in the topics.

Source

pub fn kept(&self) -> usize

How many messages wait in the outbox for the server’s answer (Config::offline).

Source

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.

Source

pub fn topic_states(&self) -> Vec<TopicState>

Each topic held: whether the server took it, and whether its messages run without a break.

Source

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().

Source

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.

Source

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.

Source

pub fn resync<I, T>(&self, topics: I) -> Result<(), Error>
where I: IntoIterator<Item = T>, T: Into<String>,

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.

Source

pub fn reconnect(&self) -> Result<(), Error>

Drops the connection and makes it again at once.

Source

pub fn set_token(&self, token: impl Into<String>)

The token for the next connection attempt.

Source

pub async fn close(&self)

Closes the connection for good, and waits until it is.

Source

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).

Source

pub async fn closed(&self) -> Option<Error>

Waits until the client stops for good; the reason, unless the application closed it.

Source

pub fn status(&self) -> Status

Source

pub fn is_connected(&self) -> bool

The server took the current connection: messages go out.

Source

pub fn connection_id(&self) -> Option<String>

The current connection’s id, as the server named it.

Source

pub fn user_id(&self) -> Option<String>

The user the server took the connection for.

Trait Implementations§

Source§

impl Clone for Client

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
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§

§

impl !RefUnwindSafe for Client

§

impl !UnwindSafe for Client

§

impl Forget for Client

§

impl Freeze for Client

§

impl Move for Client

§

impl Send for Client

§

impl Sync for Client

§

impl Unpin for Client

§

impl UnsafeUnpin for Client

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> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
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> MaybeSend for T
where T: Send,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
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.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more