Struct Client

pub struct Client { /* private fields */ }

The entry point to the NATS client protocol

Implementations

impl Client

pub fn new(addresses: Vec<Address>) -> Self

Create a new Client with a default Connect

Arguments

• addresses - the list of addresses to try and establish a connection to a server

pub fn with_connect(addresses: Vec<Address>, connect: Connect) -> Self

Create a new Client with the provided Connect

Arguments

• addresses - the list of addresses to try and establish a connection to a server

pub async fn state(&self) -> ClientState

Get the current state of the Client

pub async fn state_stream(&self) -> WatchReceiver<ClientState>

Get a watch stream of Client state transitions

pub async fn info(&self) -> Info

Get a the most recent Info sent from the server

pub async fn connect_mut(&self) -> ClientRefMut<'_, Connect>

Get a mutable reference to this Client’s Connect

pub async fn addresses_mut(&self) -> ClientRefMut<'_, [Address]>

Get a mutable reference to the list of addresses used to try and establish a connection to a server.

pub async fn tcp_connect_timeout(&self) -> Duration

Get the configured TCP connect timeout. [default = 10s]

This is the timeout of a single connect attempt. It is not the timeout of the connect future which has no internal timeout.

pub async fn set_tcp_connect_timeout( &self, tcp_connect_timeout: Duration, ) -> &Self

Set the TCP connect timeout.

pub async fn delay_generator_mut(&self) -> ClientRefMut<'_, DelayGenerator>

Get the DelayGenerator

The default generator is generated with generate_delay_generator with the following parameters:

• connect_series_attempts_before_cool_down = 3
• connect_delay = 0s
• connect_series_delay = 5s
• cool_down = 60s

pub async fn sids(&self) -> Vec<Sid>

Get a list of all currently subscribed subscription IDs

pub async fn subscription( &self, sid: Sid, ) -> Option<ClientRef<'_, Subscription>>

Return a reference to a Subscription if the client is aware of the specified subscription ID

pub async fn send_connect(&self) -> Result<()>

Send a CONNECT message to the server using the configured Connect.

Note: connect automatically sends a CONNECT message. This is only needed in the case that you want to change the connection parameters after already establishing a connection.

pub async fn connect(&self)

Connect to a NATS server

This will randomly shuffle a list consisting of all explicitly specified addresses and addresses received in an INFO message’s connect_urls. A randomized list of addresses is used to avoid a thundering herd. The client will continuously try to connect to each address in this list. The timeout of each connect attempt is specified by the tcp_connect_timeout. The delay between each connect attempt is specified by the delay_generator_mut.

When this future resolves, we are guaranteed to have entered the Connected state. Unless, disconnect was called.

Should the client become disconnected for any reason, other than calling disconnect, the client will continuously try to reconnect. Upon a successful reconnect, the client will automatically subscribe to all subscriptions.

pub async fn disconnect(&self)

Disconnect from the NATS server

When this future resolves, we are guaranteed to have entered the Disconnected state.

Note: Client does not disconnect when it is Dropped. In order to avoid leaking futures, you must explicitly call disconnect.

pub async fn publish(&self, subject: &Subject, payload: &[u8]) -> Result<()>

Convenience wrapper around publish_with_optional_reply

pub async fn publish_with_reply( &self, subject: &Subject, reply_to: &Subject, payload: &[u8], ) -> Result<()>

Convenience wrapper around publish_with_optional_reply

pub async fn publish_with_optional_reply( &self, subject: &Subject, reply_to: Option<&Subject>, payload: &[u8], ) -> Result<()>

PUBlish a message

Arguments

• subject - The subject to publish to
• reply_to - The optional reply to subject
• payload - The actual contents of the message

pub async fn request(&self, subject: &Subject, payload: &[u8]) -> Result<Msg>

Implements the request-reply pattern

pub async fn request_with_timeout( &self, subject: &Subject, payload: &[u8], duration: Duration, ) -> Result<Msg>

Implements the request-reply pattern with a timeout

pub async fn subscribe( &self, subject: &Subject, buffer: usize, ) -> Result<(Sid, MpscReceiver<Msg>)>

Convenience wrapper around subscribe_with_optional_queue_group

pub async fn subscribe_with_queue_group( &self, subject: &Subject, queue_group: &str, buffer: usize, ) -> Result<(Sid, MpscReceiver<Msg>)>

Convenience wrapper around subscribe_with_optional_queue_group

pub async fn subscribe_with_optional_queue_group( &self, subject: &Subject, queue_group: Option<&str>, buffer: usize, ) -> Result<(Sid, MpscReceiver<Msg>)>

SUBscribe to a Subject

Returns the subscription ID of the newly created subscription and a channel to receive incoming messages on.

Arguments

• subject - The subject to subscribe to
• reply_to - The optional queue group to join
• buffer - The size of the underlying mpsc channel

pub async fn unsubscribe(&self, sid: Sid) -> Result<()>

Convenience wrapper around unsubscribe_optional_max_msgs

pub async fn unsubscribe_with_max_msgs( &self, sid: Sid, max_msgs: u64, ) -> Result<()>

Convenience wrapper around unsubscribe_optional_max_msgs

pub async fn unsubscribe_optional_max_msgs( &self, sid: Sid, max_msgs: Option<u64>, ) -> Result<()>

UNSUBscribe from a subscription ID

Arguments

• sid - The subscription id to unsubscribe from
• max_msgs - Unsubscribe after receiving the specified number of messages. If this is None, the subscription is immediately unsubscribed.

pub async fn unsubscribe_all(&self) -> Result<()>

Unsubscribe from all subscriptions

pub async fn info_stream(&self) -> WatchReceiver<Info>

Get a watch stream of INFO messages received from the server

pub async fn ping_stream(&self) -> WatchReceiver<()>

Get a watch stream of PING messages received from the server

pub async fn pong_stream(&self) -> WatchReceiver<()>

Get a watch stream of PONG messages received from the server

pub async fn ok_stream(&self) -> WatchReceiver<()>

Get a watch stream of +OK messages received from the server

pub async fn err_stream(&self) -> WatchReceiver<ProtocolError>

Get a watch stream of -ERR messages received from the server

pub async fn ping(&self) -> Result<()>

Send a PING to the server.

This method, coupled with a pong_stream, can be a useful way to check that the client is still connected to the server.

pub async fn pong(&self) -> Result<()>

Send a PONG to the server.

Note: you do not have to manually send a PONG as part of the servers ping/pong keep alive. The client library automatically handles replying to pings. You should not need to use this method.

pub async fn ping_pong(&self) -> Result<()>

Send a PONG and wait for a PONG from the server

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Drop for Client

fn drop(&mut self)

Executes the destructor for this type.