pub struct Options { /* private fields */ }
Expand description
Connect options.
Implementations
sourceimpl Options
impl Options
sourcepub fn new() -> Options
pub fn new() -> Options
Options
for establishing a new NATS Connection
.
Example
let options = nats::Options::new();
let nc = options.connect("demo.nats.io")?;
sourcepub fn with_token(token: &str) -> Options
pub fn with_token(token: &str) -> Options
Authenticate with NATS using a token.
Example
let nc = nats::Options::with_token("t0k3n!")
.connect("demo.nats.io")?;
sourcepub fn with_user_pass(user: &str, password: &str) -> Options
pub fn with_user_pass(user: &str, password: &str) -> Options
Authenticate with NATS using a username and password.
Example
let nc = nats::Options::with_user_pass("derek", "s3cr3t!")
.connect("demo.nats.io")?;
sourcepub fn with_credentials(path: impl AsRef<Path>) -> Options
pub fn with_credentials(path: impl AsRef<Path>) -> Options
Authenticate with NATS using a .creds
file.
This will open the provided file, load its creds, perform the desired authentication, and then zero the memory used to store the creds before continuing.
Example
let nc = nats::Options::with_credentials("path/to/my.creds")
.connect("connect.ngs.global")?;
sourcepub fn with_static_credentials(creds: &str) -> Result<Options>
pub fn with_static_credentials(creds: &str) -> Result<Options>
Authenticate with NATS using a static credential str, using
the creds file format. Note that this is more hazardous than
using the above with_credentials
method because it retains
the secret in-memory for the lifetime of this client instead
of zeroing the credentials after holding them for a very short
time, as the with_credentials
method does.
Example
let creds =
"-----BEGIN NATS USER JWT-----
eyJ0eXAiOiJqd3QiLCJhbGciOiJlZDI1NTE5...
------END NATS USER JWT------
************************* IMPORTANT *************************
NKEY Seed printed below can be used sign and prove identity.
NKEYs are sensitive and should be treated as secrets.
-----BEGIN USER NKEY SEED-----
SUAIO3FHUX5PNV2LQIIP7TZ3N4L7TX3W53MQGEIVYFIGA635OZCKEYHFLM
------END USER NKEY SEED------
";
let nc = nats::Options::with_static_credentials(creds)
.expect("failed to parse static creds")
.connect("connect.ngs.global")?;
sourcepub fn with_jwt<J, S>(jwt_cb: J, sig_cb: S) -> Optionswhere
J: Fn() -> Result<String> + Send + Sync + 'static,
S: Fn(&[u8]) -> Vec<u8> + Send + Sync + 'static,
pub fn with_jwt<J, S>(jwt_cb: J, sig_cb: S) -> Optionswhere
J: Fn() -> Result<String> + Send + Sync + 'static,
S: Fn(&[u8]) -> Vec<u8> + Send + Sync + 'static,
Authenticate with a function that loads user JWT and a signature function.
Example
let seed = "SUANQDPB2RUOE4ETUA26CNX7FUKE5ZZKFCQIIW63OX225F2CO7UEXTM7ZY";
let kp = nkeys::KeyPair::from_seed(seed).unwrap();
fn load_jwt() -> std::io::Result<String> {
todo!()
}
let nc = nats::Options::with_jwt(load_jwt, move |nonce| kp.sign(nonce).unwrap())
.connect("localhost")?;
sourcepub fn with_nkey<F>(nkey: &str, sig_cb: F) -> Optionswhere
F: Fn(&[u8]) -> Vec<u8> + Send + Sync + 'static,
pub fn with_nkey<F>(nkey: &str, sig_cb: F) -> Optionswhere
F: Fn(&[u8]) -> Vec<u8> + Send + Sync + 'static,
Authenticate with NATS using a public key and a signature function.
Example
let nkey = "UAMMBNV2EYR65NYZZ7IAK5SIR5ODNTTERJOBOF4KJLMWI45YOXOSWULM";
let seed = "SUANQDPB2RUOE4ETUA26CNX7FUKE5ZZKFCQIIW63OX225F2CO7UEXTM7ZY";
let kp = nkeys::KeyPair::from_seed(seed).unwrap();
let nc = nats::Options::with_nkey(nkey, move |nonce| kp.sign(nonce).unwrap())
.connect("localhost")?;
sourcepub fn client_cert(self, cert: impl AsRef<Path>, key: impl AsRef<Path>) -> Options
pub fn client_cert(self, cert: impl AsRef<Path>, key: impl AsRef<Path>) -> Options
Set client certificate and private key files.
Example
let nc = nats::Options::new()
.client_cert("client-cert.pem", "client-key.pem")
.connect("nats://localhost:4443")?;
sourcepub fn tls_client_config(self, tls_client_config: ClientConfig) -> Options
pub fn tls_client_config(self, tls_client_config: ClientConfig) -> Options
Set the default TLS config that will be used
for connections. Note that this is less secure
than specifying TLS certificate file paths
using the other methods on Options
, which
will avoid keeping raw key material in-memory
and will zero memory buffers that temporarily
contain key material during connection attempts.
This is intended to be used as a method of
last-resort when providing well-known file
paths is not feasible.
To avoid version conflicts, the rustls
version
used by this crate is exported as nats::rustls
.
Example
let mut tls_client_config = nats::rustls::ClientConfig::default();
tls_client_config
.set_single_client_cert(
vec![nats::rustls::Certificate(b"MY_CERT".to_vec())],
nats::rustls::PrivateKey(b"MY_KEY".to_vec()),
);
let nc = nats::Options::new()
.tls_client_config(tls_client_config)
.connect("nats://localhost:4443")?;
sourcepub fn with_name(self, name: &str) -> Options
pub fn with_name(self, name: &str) -> Options
Add a name option to this configuration.
Example
let nc = nats::Options::new()
.with_name("My App")
.connect("demo.nats.io")?;
sourcepub fn no_echo(self) -> Options
pub fn no_echo(self) -> Options
Select option to not deliver messages that we have published.
Example
let nc = nats::Options::new()
.no_echo()
.connect("demo.nats.io")?;
sourcepub fn retry_on_failed_connect(self) -> Options
pub fn retry_on_failed_connect(self) -> Options
Select option to enable reconnect with backoff
on first failed connection attempt.
The reconnect logic with max_reconnects
and the
reconnect_delay_callback
will be specified the same
as before but will be invoked on the first failed
connection attempt.
Example
let nc = nats::Options::new()
.retry_on_failed_connect()
.connect("demo.nats.io")?;
sourcepub fn max_reconnects<T: Into<Option<usize>>>(self, max_reconnects: T) -> Options
pub fn max_reconnects<T: Into<Option<usize>>>(self, max_reconnects: T) -> Options
Set the maximum number of reconnect attempts. If no servers remain that are under this threshold, then no further reconnect shall be attempted. The reconnect attempt for a server is reset upon successfull connection. If None then there is no maximum number of attempts.
Example
let nc = nats::Options::new()
.max_reconnects(3)
.connect("demo.nats.io")?;
sourcepub fn reconnect_buffer_size(self, reconnect_buffer_size: usize) -> Options
pub fn reconnect_buffer_size(self, reconnect_buffer_size: usize) -> Options
Set the maximum amount of bytes to buffer when accepting outgoing traffic in disconnected mode.
The default value is 8mb.
Example
let nc = nats::Options::new()
.reconnect_buffer_size(64 * 1024)
.connect("demo.nats.io")?;
sourcepub fn connect<I: IntoServerList>(self, nats_urls: I) -> Result<Connection>
pub fn connect<I: IntoServerList>(self, nats_urls: I) -> Result<Connection>
Establish a Connection
with one or more NATS servers.
To pass more than one URL check out the the documentation of crate::connect()
.
Note: If an URL provides username and password, e.g. nats://derek:s3cr3t!@demo.nats.io
,
it will override the username and password set by the Options
. Be aware that providing
credentials in the URL is not safe and should not be used in production.
Example
let options = nats::Options::new();
let nc = options.connect("demo.nats.io")?;
In the below case, the second server is configured to use TLS but the first one is not.
Using the Options::tls_required()
method can ensure that all servers are connected
to with TLS, if that is your intention.
let options = nats::Options::new();
let nc = options.connect("nats://demo.nats.io:4222,tls://demo.nats.io:4443")?;
sourcepub fn error_callback<F>(self, cb: F) -> Selfwhere
F: Fn(Error) + Send + Sync + 'static,
pub fn error_callback<F>(self, cb: F) -> Selfwhere
F: Fn(Error) + Send + Sync + 'static,
Set a callback to be executed when an async error from a server has been received.
Example
let nc = nats::Options::new()
.error_callback(|err| println!("connection received an error: {}", err))
.connect("demo.nats.io")?;
sourcepub fn disconnect_callback<F>(self, cb: F) -> Selfwhere
F: Fn() + Send + Sync + 'static,
pub fn disconnect_callback<F>(self, cb: F) -> Selfwhere
F: Fn() + Send + Sync + 'static,
Set a callback to be executed when connectivity to a server has been lost.
Example
let nc = nats::Options::new()
.disconnect_callback(|| println!("connection has been lost"))
.connect("demo.nats.io")?;
sourcepub fn reconnect_callback<F>(self, cb: F) -> Selfwhere
F: Fn() + Send + Sync + 'static,
pub fn reconnect_callback<F>(self, cb: F) -> Selfwhere
F: Fn() + Send + Sync + 'static,
Set a callback to be executed when connectivity to a server has been reestablished.
Example
let nc = nats::Options::new()
.reconnect_callback(|| println!("connection has been reestablished"))
.connect("demo.nats.io")?;
sourcepub fn close_callback<F>(self, cb: F) -> Selfwhere
F: Fn() + Send + Sync + 'static,
pub fn close_callback<F>(self, cb: F) -> Selfwhere
F: Fn() + Send + Sync + 'static,
Set a callback to be executed when the client has been closed due to exhausting reconnect retries to known servers or by completing a drain request.
Example
let nc = nats::Options::new()
.close_callback(|| println!("connection has been closed"))
.connect("demo.nats.io")?;
nc.drain().unwrap();
sourcepub fn lame_duck_callback<F>(self, cb: F) -> Selfwhere
F: Fn() + Send + Sync + 'static,
pub fn lame_duck_callback<F>(self, cb: F) -> Selfwhere
F: Fn() + Send + Sync + 'static,
Set a callback to be executed when the server enters lame duck mode. Can be set to enable letting user know that client will be soon evicted.
Example
let nc = nats::Options::new()
.lame_duck_callback(|| println!("server entered lame duck mode"))
.connect("demo.nats.io")?;
nc.drain().unwrap();
sourcepub fn reconnect_delay_callback<F>(self, cb: F) -> Selfwhere
F: Fn(usize) -> Duration + Send + Sync + 'static,
pub fn reconnect_delay_callback<F>(self, cb: F) -> Selfwhere
F: Fn(usize) -> Duration + Send + Sync + 'static,
Set a callback to be executed for calculating the backoff duration to wait before a server reconnection attempt.
The function takes the number of reconnects as an argument
and returns the Duration
that should be waited before
making the next connection attempt.
It is recommended that some random jitter is added to
your returned Duration
.
Example
let nc = nats::Options::new()
.reconnect_delay_callback(|c| Duration::from_millis(std::cmp::min((c * 100) as u64, 8000)))
.connect("demo.nats.io")?;
sourcepub fn tls_required(self, tls_required: bool) -> Options
pub fn tls_required(self, tls_required: bool) -> Options
Setting this requires that TLS be set for all server connections.
If you only want to use TLS for some server connections, you may
declare them separately in the connect string by prefixing them
with tls://host:port
instead of nats://host:port
.
Examples
let nc = nats::Options::new()
.tls_required(true)
.connect("tls://demo.nats.io:4443")?;