Event listener interface and presence changes (#183)

feat(listener): change the real-time event handling interface

feat(presence-state): state maintained after set state is used

`user_id` state for specified channels will be maintained by the SDK. State with subscribe calls
has been improved.

feat(api): adding first-class citizens to access subscription

Adding `Channel`, `ChannelGroup`, `ChannelMetadata` and `UuidMetadata` entities to be first-class
citizens to access APIs related to them. Currently, access is provided only for subscription APIs.

feat(auto-retry): added ability to exclude endpoints from retry

Added ability to configure request retry policies to exclude specific endpoints from retry.

Author: parfeon

.pubnub.yml

@@ -1,9 +1,20 @@
 name: rust
-version: 0.4.1
+version: 0.5.0
 schema: 1
 scm: github.com/pubnub/rust
 files: []
 changelog:
+  - date: 2024-01-25
+    version: 0.5.0
+    changes:
+      - type: feature
+        text: "Change the real-time event handling interface."
+      - type: feature
+        text: "`user_id` state for specified channels will be maintained by the SDK. State with subscribe calls has been improved."
+      - type: feature
+        text: "Adding `Channel`, `ChannelGroup`, `ChannelMetadata` and `UuidMetadata` entities to be first-class citizens to access APIs related to them. Currently, access is provided only for subscription APIs."
+      - type: feature
+        text: "Added ability to configure request retry policies to exclude specific endpoints from retry."
   - date: 2023-11-03
     version: 0.4.1
     changes:

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pubnub"
-version = "0.4.1"
+version = "0.5.0"
 edition = "2021"
 license-file = "LICENSE"
 authors = ["PubNub <[email protected]>"]
@@ -63,7 +63,7 @@ std = ["derive_builder/std", "log/std", "uuid/std", "base64/std", "spin/std", "s
 extra_platforms = ["spin/portable_atomic", "dep:portable-atomic"]
 
 # [Internal features] (not intended for use outside of the library)
-contract_test = ["parse_token", "publish", "access", "crypto"]
+contract_test = ["parse_token", "publish", "access", "crypto", "std", "subscribe", "presence", "tokio"]
 full_no_std = ["serde", "reqwest", "crypto", "parse_token", "blocking", "publish", "access", "subscribe", "tokio", "presence"]
 full_no_std_platform_independent = ["serde", "crypto", "parse_token", "blocking", "publish", "access", "subscribe", "presence"]
 pubnub_only = ["crypto", "parse_token", "blocking", "publish", "access", "subscribe", "presence"]
@@ -106,7 +106,7 @@ getrandom = { version = "0.2", optional = true }
 # parse_token
 ciborium = { version = "0.2.1", default-features = false, optional = true }
 
-# subscribe
+# subscribe, presence
 futures = { version = "0.3.28", default-features = false, optional = true }
 tokio = { version = "1", optional = true, features = ["rt-multi-thread", "macros", "time"] }
 async-channel = { version = "1.8", optional = true }
@@ -122,7 +122,7 @@ async-trait = "0.1"
 tokio = { version = "1", features = ["rt-multi-thread", "macros", "time"] }
 wiremock = "0.5"
 env_logger = "0.10"
-cucumber = { version = "0.20.0", features = ["output-junit"] }
+cucumber = { version = "0.20.2", features = ["output-junit"] }
 reqwest = { version = "0.11", features = ["json"] }
 test-case = "3.0"
 hashbrown = { version = "0.14.0", features = ["serde"] }
@@ -165,7 +165,7 @@ required-features = ["default"]
 
 [[example]]
 name = "subscribe"
-required-features = ["default", "subscribe"]
+required-features = ["default", "subscribe", "presence"]
 
 [[example]]
 name = "subscribe_raw"

README.md

@@ -36,11 +36,11 @@ Add `pubnub` to your Rust project in the `Cargo.toml` file:
 ```toml
 # default features
 [dependencies]
-pubnub = "0.4.1"
+pubnub = "0.5.0"
 
 # all features
 [dependencies]
-pubnub = { version = "0.4.1", features = ["full"] }
+pubnub = { version = "0.5.0", features = ["full"] }
 ```
 
 ### Example
@@ -57,53 +57,53 @@ use serde_json;
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let publish_key = "my_publish_key";
+    use pubnub::subscribe::{EventEmitter, SubscriptionParams};
+let publish_key = "my_publish_key";
     let subscribe_key = "my_subscribe_key";
     let client = PubNubClientBuilder::with_reqwest_transport()
-      .with_keyset(Keyset {
-           subscribe_key,
-           publish_key: Some(publish_key),
-           secret_key: None,
-       })
-       .with_user_id("user_id")
-       .build()?;
-   println!("PubNub instance created");
-
-   let subscription = client
-      .subscribe()
-       .channels(["my_channel".into()].to_vec())
-       .execute()?;
-
-   println!("Subscribed to channel");
-
-  // Launch a new task to print out each received message
-  tokio::spawn(subscription.stream().for_each(|event| async move {
-       match event {
-           SubscribeStreamEvent::Update(update) => {
-               match update {
-                   Update::Message(message) | Update::Signal(message) => {
-                       // Silently log if UTF-8 conversion fails
-                       if let Ok(utf8_message) = String::from_utf8(message.data.clone()) {
-                           if let Ok(cleaned) = serde_json::from_str::<String>(&utf8_message) {
-                               println!("message: {}", cleaned);
-                           }
-                      }
-                   }
-                    Update::Presence(presence) => {
-                        println!("presence: {:?}", presence)
-                    }
-                    Update::Object(object) => {
-                        println!("object: {:?}", object)
-                    }
-                    Update::MessageAction(action) => {
-                        println!("message action: {:?}", action)
-                    }
-                    Update::File(file) => {
-                        println!("file: {:?}", file)
+        .with_keyset(Keyset {
+            subscribe_key,
+            publish_key: Some(publish_key),
+            secret_key: None,
+        })
+        .with_user_id("user_id")
+        .build()?;
+    println!("PubNub instance created");
+
+    let subscription = client.subscription(SubscriptionParams {
+        channels: Some(&["my_channel"]),
+        channel_groups: None,
+        options: None
+    });
+
+    println!("Subscribed to channel");
+
+    // Launch a new task to print out each received message
+    tokio::spawn(client.status_stream().for_each(|status| async move {
+        println!("\nStatus: {:?}", status)
+    }));
+    tokio::spawn(subscription.stream().for_each(|event| async move {
+        match event {
+            Update::Message(message) | Update::Signal(message) => {
+                // Silently log if UTF-8 conversion fails
+                if let Ok(utf8_message) = String::from_utf8(message.data.clone()) {
+                    if let Ok(cleaned) = serde_json::from_str::<String>(&utf8_message) {
+                        println!("message: {}", cleaned);
                     }
                 }
             }
-            SubscribeStreamEvent::Status(status) => println!("\nstatus: {:?}", status),
+            Update::Presence(presence) => {
+                println!("presence: {:?}", presence)
+            }
+            Update::AppContext(object) => {
+                println!("object: {:?}", object)
+            }
+            Update::MessageAction(action) => {
+                println!("message action: {:?}", action)
+            }
+            Update::File(file) => {
+                println!("file: {:?}", file)
+            }
         }
     }));
 
@@ -132,11 +132,11 @@ disable them in the `Cargo.toml` file, like so:
 ```toml
 # only blocking and access + default features
 [dependencies]
-pubnub = { version = "0.4.1", features = ["blocking", "access"] }
+pubnub = { version = "0.5.0", features = ["blocking", "access"] }
 
 # only parse_token + default features
 [dependencies]
-pubnub = { version = "0.4.1", features = ["parse_token"] }
+pubnub = { version = "0.5.0", features = ["parse_token"] }
 ```
 
 ### Available features
@@ -175,7 +175,7 @@ you need, for example:
 
 ```toml
 [dependencies]
-pubnub = { version = "0.4.1", default-features = false, features = ["serde", "publish",
+pubnub = { version = "0.5.0", default-features = false, features = ["serde", "publish",
 "blocking"] }
 ```
 

examples/no_std/src/subscribe.rs

@@ -38,7 +38,8 @@ getrandom::register_custom_getrandom!(custom_random);
 fn custom_random(buf: &mut [u8]) -> Result<(), getrandom::Error> {
     // We're using `42` as a random number, because it's the answer
     // to the Ultimate Question of Life, the Universe, and Everything.
-    // In your program, you should use proper random number generator that is supported by your target.
+    // In your program, you should use proper random number generator that is
+    // supported by your target.
     for i in buf.iter_mut() {
         *i = 42;
     }
@@ -48,7 +49,8 @@ fn custom_random(buf: &mut [u8]) -> Result<(), getrandom::Error> {
 
 // Many targets have very specific requirements for networking, so it's hard to
 // provide a generic implementation.
-// Depending on the target, you will probably need to implement `Transport` trait.
+// Depending on the target, you will probably need to implement `Transport`
+// trait.
 struct MyTransport;
 
 impl Transport for MyTransport {
@@ -64,8 +66,8 @@ impl Transport for MyTransport {
 // As our target does not have `std` library, we need to provide custom
 // implementation of `GlobalAlloc` trait.
 //
-// In your program, you should use proper allocator that is supported by your target.
-// Here you have dummy implementation that does nothing.
+// In your program, you should use proper allocator that is supported by your
+// target. Here you have dummy implementation that does nothing.
 #[derive(Default)]
 pub struct Allocator;
 
@@ -82,23 +84,23 @@ static GLOBAL_ALLOCATOR: Allocator = Allocator;
 // As our target does not have `std` library, we need to provide custom
 // implementation of `panic_handler`.
 //
-// In your program, you should use proper panic handler that is supported by your target.
-// Here you have dummy implementation that does nothing.
+// In your program, you should use proper panic handler that is supported by
+// your target. Here you have dummy implementation that does nothing.
 #[panic_handler]
 fn panicking(_: &PanicInfo) -> ! {
     loop {}
 }
 
-// As we're using `no_main` attribute, we need to define `main` function manually.
-// For this example we're using `extern "C"` ABI to make it work.
+// As we're using `no_main` attribute, we need to define `main` function
+// manually. For this example we're using `extern "C"` ABI to make it work.
 #[no_mangle]
 pub extern "C" fn main(_argc: isize, _argv: *const *const u8) -> usize {
     publish_example().map(|_| 0).unwrap()
 }
 
-// In standard subscribe examples we use `println` macro to print the result of the operation
-// and it shows the idea of the example. `no_std` does not support `println` macro,
-// so we're using `do_a_thing` function instead.
+// In standard subscribe examples we use `println` macro to print the result of
+// the operation and it shows the idea of the example. `no_std` does not support
+// `println` macro, so we're using `do_a_thing` function instead.
 fn do_a_thing<T>(_: T) {}
 
 // As `no_std` does not support `Error` trait, we use `PubNubError` instead.
@@ -133,7 +135,7 @@ fn publish_example() -> Result<(), PubNubError> {
             match update? {
                 Update::Message(message) | Update::Signal(message) => do_a_thing(message),
                 Update::Presence(presence) => do_a_thing(presence),
-                Update::Object(object) => do_a_thing(object),
+                Update::AppContext(object) => do_a_thing(object),
                 Update::MessageAction(action) => do_a_thing(action),
                 Update::File(file) => do_a_thing(file),
             };

examples/presence_state.rs

@@ -1,16 +1,24 @@
+use std::collections::HashMap;
+
 use pubnub::{Keyset, PubNubClientBuilder};
-use serde::Serialize;
-use std::env;
 
-#[derive(Debug, Serialize)]
+#[derive(Debug, serde::Serialize)]
 struct State {
     is_doing: String,
+    flag: bool,
+}
+#[derive(Debug, serde::Serialize)]
+struct State2 {
+    is_doing: String,
+    business: String,
 }
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn snafu::Error>> {
-    let publish_key = env::var("SDK_PUB_KEY")?;
-    let subscribe_key = env::var("SDK_SUB_KEY")?;
+    // let publish_key = env::var("SDK_PUB_KEY")?;
+    // let subscribe_key = env::var("SDK_SUB_KEY")?;
+    let publish_key = "demo";
+    let subscribe_key = "demo";
 
     let client = PubNubClientBuilder::with_reqwest_transport()
         .with_keyset(Keyset {
@@ -23,9 +31,32 @@ async fn main() -> Result<(), Box<dyn snafu::Error>> {
 
     println!("running!");
 
+    client
+        .set_presence_state_with_heartbeat(HashMap::from([
+            (
+                "my_channel".to_string(),
+                State {
+                    is_doing: "Something".to_string(),
+                    flag: true,
+                },
+            ),
+            (
+                "other_channel".to_string(),
+                State {
+                    is_doing: "Oh no".to_string(),
+                    flag: false,
+                },
+            ),
+        ]))
+        .channels(["my_channel".into(), "other_channel".into()].to_vec())
+        .user_id("user_id")
+        .execute()
+        .await?;
+
     client
         .set_presence_state(State {
             is_doing: "Nothing... Just hanging around...".into(),
+            flag: false,
         })
         .channels(["my_channel".into(), "other_channel".into()].to_vec())
         .user_id("user_id")