Release 0.17.0

CHANGELOG.md

@@ -1,3 +1,52 @@
+# 0.17.0
+## Overview
+
+This release brings a lot of changes and refactors among which the highlights are:
+* A complete rewrite of the JetStream API with a new subscription interface
+* Improvements of JetStream internals
+* Key-Value Store support
+* Object Store support
+
+## Breaking Changes
+* Introduce a `JetStream` type by @caspervonb in https://github.com/nats-io/nats.rs/pull/247
+* Move Consumer Management to JetStream by @Jarema in https://github.com/nats-io/nats.rs/pull/250
+* Re-work JetStream push consumer interface by @caspervonb in https://github.com/nats-io/nats.rs/pull/252
+* Re-work JetStream pull consumer interface by @Jarema in https://github.com/nats-io/nats.rs/pull/302
+* Rename create_stream to add_stream by @Jarema in https://github.com/nats-io/nats.rs/pull/251
+* Change return type of add_consumer to `ConsumerInfo` by @caspervonb in https://github.com/nats-io/nats.rs/pull/252
+
+## Added
+* Add header module by @caspervonb in https://github.com/nats-io/nats.rs/pull/260
+* Implement key-value store by @caspervonb in https://github.com/nats-io/nats.rs/pull/267
+* Implement object store by @caspervonb in https://github.com/nats-io/nats.rs/pull/269
+* Lame duck mode support by @Jarema in https://github.com/nats-io/nats.rs/pull/265
+* Add domain field to `PubAck` by @caspervonb in https://github.com/nats-io/nats.rs/pull/243
+* Add support for JetStream publishing by @caspervonb in https://github.com/nats-io/nats.rs/pull/248
+* Add `error_callback` by @derekcollison in https://github.com/nats-io/nats.rs/pull/253
+* Add `get_message` to JetStream context by @caspervonb in https://github.com/nats-io/nats.rs/pull/267
+* Add `get_last_message` to JetStream context  by @caspervonb in https://github.com/nats-io/nats.rs/pull/267
+* Add option `retry_on_failed_connect` by @pozsgaic in https://github.com/nats-io/nats.rs/pull/223
+* Add support for different .pem contents by @Jarema https://github.com/nats-io/nats.rs/pull/280
+* Introduce ServerAddress https://github.com/nats-io/nats.rs/pull/276
+
+## Changed
+* Allow for inline header description with spaces by @caspervonb in https://github.com/nats-io/nats.rs/pull/241
+* Allow setting a jetstream api prefix from a domain by @caspervonb in https://github.com/nats-io/nats.rs/pull/244
+* Have Client in Message as Option by @Jarema in https://github.com/nats-io/nats.rs/pull/258
+* Change jetstream log level to debug by @caspervonb https://github.com/nats-io/nats.rs/pull/307
+* Bump MSRV to 1.53.0
+
+## Minor
+* Reduce allocations in `Headers::try_from` by @caspervonb in https://github.com/nats-io/nats.rs/pull/238
+* Improve error handling by @caspervonb in https://github.com/nats-io/nats.rs/pull/249
+* Some additions.. by @derekcollison in https://github.com/nats-io/nats.rs/pull/253
+* Bump blocking crate by @Jarema in https://github.com/nats-io/nats.rs/pull/255
+* Add `sealed` field to `jetstream::StreamConfig` by @caspervonb in https://github.com/nats-io/nats.rs/pull/256
+* Fix unsubscribe method behaviour to act as in docs by @Jarema in https://github.com/nats-io/nats.rs/pull/301
+* Fix license formatting so it is properly detected by Github and add missing license banners in files by @Jarema in https://github.com/nats-io/nats.rs/pull/292
+
+**Full Changelog**: https://github.com/nats-io/nats.rs/compare/v0.16.0...v0.17.0
+
 # 0.16.0
 
 ### Added

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "nats"
-version = "0.16.0"
+version = "0.17.0"
 description = "A Rust NATS client"
 authors = ["Derek Collison <[email protected]>", "Tyler Neely <[email protected]>", "Stjepan Glavina <[email protected]>"]
 edition = "2018"
@@ -73,6 +73,7 @@ nats_test_server = { path = "nats_test_server" }
 quicli = "0.4.0"
 smol = "1.2.5"
 structopt = "0.3.21"
+nats_016 = { package = "nats", version = "0.16.0" }
 
 [[bench]]
 name = "nats_bench"

README.md

@@ -39,6 +39,7 @@ as well!
 Basic connections, and those with options. The compiler will force these to be correct.
 
 ```rust
+# fn main() -> std::io::Result<()> {
 let nc = nats::connect("demo.nats.io")?;
 
 let nc2 = nats::Options::with_user_pass("derek", "s3cr3t!")
@@ -51,8 +52,10 @@ let nc3 = nats::Options::with_credentials("path/to/my.creds")
 let nc4 = nats::Options::new()
     .add_root_certificate("my-certs.pem")
     .connect("tls://demo.nats.io:4443")?;
+# Ok(())
+# }
 ```
-
+<!--
 ### Publish
 
 ```rust
@@ -107,6 +110,46 @@ nc.publish_request("foo", &reply, "Help me!")?;
 let response = rsub.iter().take(1);
 ```
 
+### Jetstream
+
+Create a new stream with default options:
+```rust
+let js = nats::jetstream::new(nc);
+
+// add_stream converts a str into a
+// default `StreamConfig`.
+js.add_stream("my_stream")?;
+```
+
+Create a new consumer:
+```rust
+let nc = nats::connect("demo.nats.io")?;
+let js = nats::jetstream::new(nc);
+
+js.add_stream("my_stream")?;
+js.add_consumer("my_stream", "my_consumer")?;
+```
+
+Create a new subscription:
+```rust
+let nc = nats::connect("demo.nats.io")?;
+let js = nats::jetstream::new(nc);
+
+js.add_stream("my_stream")?;
+let subscription = js.subscribe("my_stream")?;
+
+// add stream with options
+js.add_stream(nats::jetstream::StreamConfig{
+    name: "my_another_stream".to_string(),
+    max_msgs: 2000,
+    discard: nats::jetstream::DiscardPolicy::Old,
+    ..Default::default()
+})?
+})
+``` -->
+This will attempt to bind to an existing consumer if it exists, otherwise it will create a new internally managed consumer resource that gets destroyed when the subscription is dropped.
+
+
 ## Minimum Supported Rust Version (MSRV)
 
 The minimum supported Rust version is 1.53.0.

docs/migration-guide-0.17.0.md

@@ -0,0 +1,113 @@
+# Migration guide to version [0.17.0](https://github.com/nats-io/nats.rs/releases/tag/untagged-964d5dad97c03c4aa6f4)
+
+Release 0.17.0 among many features introduced a complete rewrite of the JetStream API with a new subscription interface.
+
+This page is meant to make migration to the new version easier.
+
+Lot of changes were also made to keep Rust NATS Client better aligned with Reference NATS Client (Go).
+
+# Introduction of JetStream context
+
+To make setting `Domain` and `API Prefix` more convinient by setting it once, not for every `JetStream` related operation, `JetStream` struct was introduced.
+
+This change resulted in having all `JetStream` API being called as `JetStream` methods. That applies to both `JetStream management` and `JetStream API`.
+
+```rust no_run
+fn main() -> std::io::Result<()> {
+    let nc = nats::connect("demo.nats.io")?;
+    // create Jetstream context
+    let js = nats::jetstream::new(nc);
+
+    // JetStream management
+    js.add_stream("new_stream")?;
+
+    // subscribing to some stream
+    let subscription = js.subscribe("events")?;
+
+    // publishing to stream
+    js.publish("some_stream", "message")?;
+    Ok(())
+}
+```
+
+# JetStream Management
+
+`JetStream management` changed mostly because of add `JetStream` context struct.
+
+Let's take an example of adding new `stream` with pre 0.17.0:
+
+```rust 
+fn main() -> std::io::Result<()> {
+    use nats_016 as nats;
+    let nc = nats::connect("demo.nats.io")?;
+    nc.create_stream("stream_one")?;
+
+    // create stream with options
+    nc.create_stream(nats::jetstream::StreamConfig{
+        name: "stream_two".to_string(),
+        max_msgs: 2000,
+        discard: nats::jetstream::DiscardPolicy::Old,
+        ..Default::default()
+    })?;
+    Ok(())
+}
+```
+
+And compare it to the new API:
+
+```rust
+fn main() -> std::io::Result<()> {
+    let nc = nats::connect("demo.nats.io")?;
+    // Initialize JetStream struct first
+    let js = nats::jetstream::new(nc);
+    // use it
+    js.add_stream("stream_three")?;
+
+    // add stream with options
+    js.add_stream(nats::jetstream::StreamConfig{
+        name: "stream_four".to_string(),
+        max_msgs: 2000,
+        discard: nats::jetstream::DiscardPolicy::Old,
+        ..Default::default()
+    })?;
+
+Ok(())
+}
+```
+
+As you can see one more thing changed in `JetStream Management` - `create_stream` was renamed to `add_stream` to keep better aligment with reference client.
+
+# JetStream API
+
+JetStream interface was **entirely rewritten**.
+Those changes were necessary for both cleanup and preparation for introduction of `Key-Value Store` and `Object Store`.
+
+Except all methods being moved to `JetStream` struct, their behaviour and API also changed.
+
+Full example with creating stream, publishing and subscribing with ephemeral subscription:
+
+
+```rust
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+
+    let nc = nats::connect("demo.nats.io")?;
+    let js = nats::jetstream::new(nc);
+    js.add_stream(&nats::jetstream::StreamConfig {
+        name: "events".to_string(),
+        subjects: vec![
+            "events.>".to_string(),
+        ],
+        ..Default::default()
+    })?;
+    js.publish("events.test", "test message")?;
+    let sub = js.subscribe("events.>")?;
+    sub.with_handler(move |message| {
+        println!("received {}", &message);
+     Ok(())
+    });
+    js.delete_stream("events")?;
+Ok(()) 
+}
+```
+
+To see all changes, please check cargo docs and it's examples.

src/lib.rs

@@ -230,6 +230,11 @@ fn inject_io_failure() -> io::Result<()> {
     Ok(())
 }
 
+// comment out until we reach MSRV 1.54.0
+// #[doc = include_str!("../docs/migration-guide-0.17.0.md")]
+// #[derive(Copy, Clone)]
+// pub struct Migration0170;
+
 #[doc(hidden)]
 #[deprecated(since = "0.6.0", note = "this has been renamed to `Options`.")]
 pub type ConnectionOptions = Options;

tests/request_timeout.rs

@@ -37,10 +37,6 @@ fn request_timeout() {
         },
     )
     .unwrap();
-    // for __ in 0..100 {
-    //     js.publish("foo", b"data").unwrap();
-    //     println!("published message");
-    // }
 
     let consumer = js
         .pull_subscribe_with_options(
@@ -52,13 +48,13 @@ fn request_timeout() {
     std::thread::spawn(move || {
         for __ in 0..2 {
             js.publish("foo", b"data").unwrap();
-            std::thread::sleep(Duration::from_millis(100));
+            std::thread::sleep(Duration::from_millis(300));
         }
     });
     // set the expiration of request so only first message can keep up.
     consumer
         .request_batch(BatchOptions {
-            expires: Some(Duration::from_millis(50).as_nanos() as usize),
+            expires: Some(Duration::from_millis(200).as_nanos() as usize),
             batch: 2,
             no_wait: false,
         })