rants 0.1.0

An async NATS client library.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

# Rants

![crates.io](https://img.shields.io/crates/v/rants.svg)
![docs](https://docs.rs/rants/badge.svg)
![License](https://img.shields.io/badge/license-MIT-blue.svg)
![License](https://img.shields.io/badge/license-APACHE-blue.svg)

An async [NATS](https://nats.io/) client library for the Rust programming language.

**Note:** Currently, `rants` requires a nightly version of the rust compiler due to its use of `async`/`await` syntax, but it should work on stable [soon](https://areweasyncyet.rs/)!

The client aims to be an ergonomic, yet thin, wrapper over the NATS client protocol. The easiest way to learn to use the client is by reading the [NATS client protocol documentation](https://nats-io.github.io/docs/nats_protocol/nats-protocol.html). The main entry point into the library's API is the [`Client`](struct.Client.html) struct.

# Example

```rust
use futures::stream::StreamExt;
use rants::Client;
use tokio::runtime::Runtime;

let main_future = async {
   // A NATS server must be running on `127.0.0.1:4222`
   let address = "127.0.0.1:4222".parse().unwrap();
   let client = Client::new(vec![address]);

   // Configure the client to receive messages even if it sent the message
   client.connect_mut().await.echo(true);

   // Connect to the server
   client.connect().await;

   // Create a new subject called "test"
   let subject = "test".parse().unwrap();

   // Subscribe to the "test" subject
   let (_, mut subscription) = client.subscribe(&subject, 1024).await.unwrap();

   // Publish a message to the "test" subject
   client
       .publish(&subject, b"This is a message!")
       .await
       .unwrap();

   // Read a message from the subscription
   let message = subscription.next().await.unwrap();
   let message = String::from_utf8(message.into_payload()).unwrap();
   println!("Received '{}'", message);

   // Disconnect from the server
   client.disconnect().await;
};

let runtime = Runtime::new().expect("to create Runtime");
runtime.spawn(main_future);
runtime.shutdown_on_idle();
```

## Development

The integration test suite requires the [NATS server](https://nats.io/download/nats-io/nats-server/) to be reachable at `127.0.0.1:4222`:

    > cargo test

## Roadmap

- [ ] Increase test coverage
- [ ] TLS support
- [ ] Explore automatically disconnecting the client when it is dropped
- [ ] Support improved [request-reply](https://github.com/nats-io/nats.go/issues/294) implementation
- [ ] Benchmarks and performance

## Alternatives

- [`rust-nats`](https://github.com/jedisct1/rust-nats)
- [`ratsio`](https://github.com/mnetship/ratsio)
- [`nitox`](https://github.com/YellowInnovation/nitox)