Crate nats

A Rust client for the NATS.io ecosystem.

This is the old legacy client. It will not get new features or updates beyond critical security fixes. Use async-nats instead.

git clone https://github.com/nats-io/nats.rs

NATS.io is a simple, secure and high performance open source messaging system for cloud native applications, IoT messaging, and microservices architectures.

For async API refer to the asynk module.

For more information see https://nats.io/.

Examples

> cargo run --example nats-box -- -h

Basic connections, and those with options. The compiler will force these to be correct.

let nc = nats::connect("demo.nats.io")?;

let nc2 = nats::Options::with_user_pass("derek", "s3cr3t!")
    .with_name("My Rust NATS App")
    .connect("127.0.0.1")?;

let nc3 = nats::Options::with_credentials("path/to/my.creds").connect("connect.ngs.global")?;

let nc4 = nats::Options::new()
    .add_root_certificate("my-certs.pem")
    .connect("tls://demo.nats.io:4443")?;

Publish

let nc = nats::connect("demo.nats.io")?;
nc.publish("my.subject", "Hello World!")?;

nc.publish("my.subject", "my message")?;

// Publish a request manually.
let reply = nc.new_inbox();
let rsub = nc.subscribe(&reply)?;
nc.publish_request("my.subject", &reply, "Help me!")?;

Subscribe

let nc = nats::connect("demo.nats.io")?;
let sub = nc.subscribe("foo")?;
for msg in sub.messages() {}

// Using next.
if let Some(msg) = sub.next() {}

// Other iterators.
for msg in sub.try_iter() {}
for msg in sub.timeout_iter(Duration::from_secs(10)) {}

// Using a threaded handler.
let sub = nc.subscribe("bar")?.with_handler(move |msg| {
    println!("Received {}", &msg);
    Ok(())
});

// Queue subscription.
let qsub = nc.queue_subscribe("foo", "my_group")?;

Request/Response

let nc = nats::connect("demo.nats.io")?;
let resp = nc.request("foo", "Help me?")?;

// With a timeout.
let resp = nc.request_timeout("foo", "Help me?", Duration::from_secs(2))?;

// With multiple responses.
for msg in nc.request_multi("foo", "Help")?.iter() {}

// Publish a request manually.
let reply = nc.new_inbox();
let rsub = nc.subscribe(&reply)?;
nc.publish_request("foo", &reply, "Help me!")?;
let response = rsub.iter().take(1);

Re-exports

• pub use header::HeaderMap;
• pub use jetstream::JetStreamOptions;
• pub use rustls;

Modules

• asynk
  Async-enabled NATS client. An async Rust client for the NATS.io ecosystem.
• header
  Header constants and types.
• jetstream
  JetStream stream management and consumers. Support for the JetStream at-least-once messaging system.
• kvunstable
  Support for Key Value Store. This feature is experimental and the API may change.
• object_storeunstable
  Support for Object Store. This feature is experimental and the API may change.

Structs

• Connection
  A NATS connection.
• Handler
  A Handler may be used to unsubscribe a handler thread.
• Message
  A message received on a subject.
• Options
  Connect options.
• ServerAddress
  Address of a NATS server.
• ServerInfo
  Information sent by the server back to this client during initial connection, and possibly again later.
• Subscription
  A Subscription receives Messages published to specific NATS Subjects.

Traits

• IntoServerList
  Capability to convert into a list of NATS server addresses.

Functions

• connect
  Connect to one or more NATS servers at the given URLs.