Crate async_nats

Expand description

A Rust asynchronous client for the NATS.io ecosystem.

To access the repository, you can clone it by running:

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

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

Note: The synchronous NATS API is deprecated and no longer actively maintained. If you need to use the deprecated synchronous API, you can refer to: https://crates.io/crates/nats

For more information on NATS.io visit: https://nats.io

§Examples

Below, you can find some basic examples on how to use this library.

For more details, please refer to the specific methods and structures documentation.

§Complete example

Connect to the NATS server, publish messages and subscribe to receive messages.

use bytes::Bytes;
use futures::StreamExt;

#[tokio::main]
async fn main() -> Result<(), async_nats::Error> {
    // Connect to the NATS server
    let client = async_nats::connect("demo.nats.io").await?;

    // Subscribe to the "messages" subject
    let mut subscriber = client.subscribe("messages").await?;

    // Publish messages to the "messages" subject
    for _ in 0..10 {
        client.publish("messages", "data".into()).await?;
    }

    // Receive and process messages
    while let Some(message) = subscriber.next().await {
        println!("Received message {:?}", message);
    }

    Ok(())
}

§Publish

Connect to the NATS server and publish messages to a subject.

// Connect to the NATS server
let client = async_nats::connect("demo.nats.io").await?;

// Prepare the subject and data
let subject = "foo";
let data = Bytes::from("bar");

// Publish messages to the NATS server
for _ in 0..10 {
    client.publish(subject, data.clone()).await?;
}

// Flush internal buffer before exiting to make sure all messages are sent
client.flush().await?;

Connect to the NATS server, subscribe to a subject and receive messages.

// Connect to the NATS server
let client = async_nats::connect("demo.nats.io").await?;

// Subscribe to the "foo" subject
let mut subscriber = client.subscribe("foo").await.unwrap();

// Receive and process messages
while let Some(message) = subscriber.next().await {
    println!("Received message {:?}", message);
}

§JetStream

To access JetStream API, create a JetStream jetstream::Context.

// Connect to the NATS server
let client = async_nats::connect("demo.nats.io").await?;
// Create a JetStream context.
let jetstream = async_nats::jetstream::new(client);

// Publish JetStream messages, manage streams, consumers, etc.
jetstream.publish("foo", "bar".into()).await?;

§Key-value Store

Key-value Store is accessed through jetstream::Context.

// Connect to the NATS server
let client = async_nats::connect("demo.nats.io").await?;
// Create a JetStream context.
let jetstream = async_nats::jetstream::new(client);
// Access an existing key-value.
let kv = jetstream.get_key_value("store").await?;

§Object Store store

Object Store is accessed through jetstream::Context.

// Connect to the NATS server
let client = async_nats::connect("demo.nats.io").await?;
// Create a JetStream context.
let jetstream = async_nats::jetstream::new(client);
// Access an existing key-value.
let kv = jetstream.get_object_store("store").await?;

§Service API

Service API is accessible through Client after importing its trait.

use async_nats::service::ServiceExt;
// Connect to the NATS server
let client = async_nats::connect("demo.nats.io").await?;
let mut service = client
    .service_builder()
    .description("some service")
    .stats_handler(|endpoint, stats| serde_json::json!({ "endpoint": endpoint }))
    .start("products", "1.0.0")
    .await?;

Re-exports§

pub use header::HeaderMap;
pub use header::HeaderName;
pub use header::HeaderValue;
pub use subject::Subject;
pub use client::Client;
pub use client::PublishError;
pub use client::Request;
pub use client::RequestError;
pub use client::RequestErrorKind;
pub use client::Statistics;
pub use client::SubscribeError;
pub use message::Message;
pub use status::StatusCode;
pub use tokio_rustls::rustls;

Modules§

client
connection: This module provides a connection implementation for communicating with a NATS server.
error
header: NATS Message headers, modeled loosely after the http::header crate.
jetstream: JetStream is a built-in persistence layer for NATS that provides powerful stream-based messaging capabilities, with integrated support for both at least once and exactly once delivery semantics.
message: A Core NATS message.
serviceservice
status: NATS status codes.
subject

Structs§

Auth
AuthError: Error report from signing callback.
ConnectInfo: Info to construct a CONNECT message.
ConnectOptions: Connect options. Used to connect with NATS when custom config is needed.
PublishMessage: PublishMessage represents a message being published
ServerAddr: Address of a NATS server.
ServerInfo: Information sent by the server back to this client during initial connection, and possibly again later.
Subscriber: Retrieves messages from given subscription created by Client::subscribe.
UnsubscribeError

Enums§

CallbackError
ClientError
ConnectErrorKind
Event
Protocol: Protocol version used by the client.
ServerError

Traits§

ToServerAddrs: Capability to convert into a list of NATS server addresses.

Functions§

connect: Connects to NATS with default config.
connect_with_options: Connects to NATS with specified options.

Type Aliases§

ConnectError: Returned when initial connection fails. To be enumerate over the variants, call ConnectError::kind.
Error

Crate async_natsCopy item path