where now presence API (#169)

Author: Xavrax

examples/where_now.rs

@@ -6,7 +6,7 @@ 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 _client = PubNubClientBuilder::with_reqwest_transport()
+    let client = PubNubClientBuilder::with_reqwest_transport()
         .with_keyset(Keyset {
             subscribe_key,
             publish_key: Some(publish_key),
@@ -17,13 +17,9 @@ async fn main() -> Result<(), Box<dyn snafu::Error>> {
 
     println!("running!");
 
-    //    let where_user = client
-    //        .where_now()
-    //        .user_id("user_id")
-    //        .execute()
-    //        .await?;
-    //
-    //    println!("All channels data: {:?}", where_user);
+    let where_user = client.where_now().user_id("user_id").execute().await?;
+
+    println!("User channels: {:?}", where_user);
 
     Ok(())
 }

examples/where_now_blocking.rs

@@ -5,7 +5,7 @@ fn main() -> Result<(), Box<dyn snafu::Error>> {
     let publish_key = env::var("SDK_PUB_KEY")?;
     let subscribe_key = env::var("SDK_SUB_KEY")?;
 
-    let _client = PubNubClientBuilder::with_reqwest_transport()
+    let client = PubNubClientBuilder::with_reqwest_blocking_transport()
         .with_keyset(Keyset {
             subscribe_key,
             publish_key: Some(publish_key),
@@ -16,12 +16,9 @@ fn main() -> Result<(), Box<dyn snafu::Error>> {
 
     println!("running!");
 
-    //    let where_user = client
-    //        .where_now()
-    //        .user_id("user_id")
-    //        .execute_blocking()?;
-    //
-    //    println!("All channels data: {:?}", where_user);
+    let where_user = client.where_now().user_id("user_id").execute_blocking()?;
+
+    println!("User channels: {:?}", where_user);
 
     Ok(())
 }

src/dx/presence/builders/mod.rs

@@ -21,6 +21,10 @@ pub(crate) mod leave;
 pub(crate) use here_now::HereNowRequestBuilder;
 pub(crate) mod here_now;
 
+#[doc(inline)]
+pub(crate) use where_now::WhereNowRequestBuilder;
+pub(crate) mod where_now;
+
 use crate::{dx::pubnub_client::PubNubClientInstance, lib::alloc::string::String};
 
 /// Validate [`PubNubClient`] configuration.

src/dx/presence/builders/where_now.rs

@@ -0,0 +1,128 @@
+//! PubNub Where Now module.
+//!
+//! The [`WhereNowRequestBuilder`] lets you make and execute a Here Now request
+//! that will associate a user with a channel.
+
+use derive_builder::Builder;
+
+use crate::{
+    core::{
+        utils::{
+            encoding::{url_encode_extended, UrlEncodeExtension},
+            headers::{APPLICATION_JSON, CONTENT_TYPE},
+        },
+        Deserializer, PubNubError, Transport, TransportMethod, TransportRequest,
+    },
+    dx::{presence::builders, pubnub_client::PubNubClientInstance},
+    lib::collections::HashMap,
+    presence::result::{WhereNowResponseBody, WhereNowResult},
+};
+
+/// The Here Now request builder.
+///
+/// Allows you to build a Here Now request that is sent to the [`PubNub`] network.
+///
+/// This struct is used by the [`here_now`] method of the [`PubNubClient`].
+/// The [`here_now`] method is used to acquire information about the current
+/// state of a channel.
+///
+/// [`PubNub`]: https://www.pubnub.com/
+#[derive(Builder, Debug)]
+#[builder(
+    pattern = "owned",
+    build_fn(vis = "pub(in crate::dx::presence)", validate = "Self::validate"),
+    no_std
+)]
+pub struct WhereNowRequest<T, D> {
+    /// Current client which can provide transportation to perform the request.
+    ///
+    /// This field is used to get [`Transport`] to perform the request.
+    #[builder(field(vis = "pub(in crate::dx::presence)"), setter(custom))]
+    pub(in crate::dx::presence) pubnub_client: PubNubClientInstance<T, D>,
+
+    #[builder(
+        field(vis = "pub(in crate::dx::presence)"),
+        setter(strip_option, into),
+        default
+    )]
+    /// Identifier for which `state` should be associated for provided list of
+    /// channels and groups.
+    pub(in crate::dx::presence) user_id: String,
+}
+
+impl<T, D> WhereNowRequestBuilder<T, D> {
+    /// Validate user-provided data for request builder.
+    ///
+    /// Validator ensure that list of provided data is enough to build valid
+    /// set state request instance.
+    fn validate(&self) -> Result<(), String> {
+        builders::validate_configuration(&self.pubnub_client)
+    }
+
+    /// Build [`SetStateRequest`] from builder.
+    fn request(self) -> Result<WhereNowRequest<T, D>, PubNubError> {
+        self.build()
+            .map_err(|err| PubNubError::general_api_error(err.to_string(), None, None))
+    }
+}
+
+impl<T, D> WhereNowRequest<T, D> {
+    /// Create transport request from the request builder.
+    pub(in crate::dx::presence) fn transport_request(
+        &self,
+    ) -> Result<TransportRequest, PubNubError> {
+        let sub_key = &self.pubnub_client.config.subscribe_key;
+
+        let user_id = if self.user_id.is_empty() {
+            &*self.pubnub_client.config.user_id
+        } else {
+            &self.user_id
+        };
+
+        Ok(TransportRequest {
+            path: format!(
+                "/v2/presence/sub-key/{sub_key}/uuid/{}",
+                url_encode_extended(user_id.as_bytes(), UrlEncodeExtension::NonChannelPath)
+            ),
+            query_parameters: HashMap::new(),
+            method: TransportMethod::Get,
+            headers: [(CONTENT_TYPE.into(), APPLICATION_JSON.into())].into(),
+            body: None,
+        })
+    }
+}
+
+impl<T, D> WhereNowRequestBuilder<T, D>
+where
+    T: Transport,
+    D: Deserializer + 'static,
+{
+    /// Build and call asynchronous request.
+    pub async fn execute(self) -> Result<WhereNowResult, PubNubError> {
+        let request = self.request()?;
+        let transport_request = request.transport_request()?;
+        let client = request.pubnub_client.clone();
+        let deserializer = client.deserializer.clone();
+
+        transport_request
+            .send::<WhereNowResponseBody, _, _, _>(&client.transport, deserializer)
+            .await
+    }
+}
+
+#[cfg(feature = "blocking")]
+impl<T, D> WhereNowRequestBuilder<T, D>
+where
+    T: crate::core::blocking::Transport,
+    D: Deserializer + 'static,
+{
+    /// Build and call synchronous request.
+    pub fn execute_blocking(self) -> Result<WhereNowResult, PubNubError> {
+        let request = self.request()?;
+        let transport_request = request.transport_request()?;
+        let client = request.pubnub_client.clone();
+        let deserializer = client.deserializer.clone();
+        transport_request
+            .send_blocking::<WhereNowResponseBody, _, _, _>(&client.transport, deserializer)
+    }
+}

src/dx/presence/mod.rs

@@ -213,6 +213,46 @@ impl<T, D> PubNubClientInstance<T, D> {
             ..Default::default()
         }
     }
+
+    /// Create a where now request builder.
+    ///
+    /// This method is used to get information about channels where `user_id`
+    /// is currently present.
+    ///
+    /// Instance of [`WhereNowRequestBuilder`] returned.
+    ///
+    /// # Example
+    /// ```rust
+    /// use pubnub::presence::*;
+    /// # use pubnub::{Keyset, PubNubClientBuilder};
+    /// # use std::collections::HashMap;
+    ///
+    /// # #[tokio::main]
+    /// # async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    /// # use std::sync::Arc;
+    /// let mut pubnub = // PubNubClient
+    /// #         PubNubClientBuilder::with_reqwest_transport()
+    /// #             .with_keyset(Keyset {
+    /// #                 subscribe_key: "demo",
+    /// #                 publish_key: None,
+    /// #                 secret_key: None,
+    /// #             })
+    /// #             .with_user_id("uuid")
+    /// #             .build()?;
+    /// let response = pubnub.where_now().user_id("user_id").execute().await?;
+
+    ///
+    /// println!("User channels: {:?}", response);
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn where_now(&self) -> WhereNowRequestBuilder<T, D> {
+        WhereNowRequestBuilder {
+            pubnub_client: Some(self.clone()),
+            ..Default::default()
+        }
+    }
 }
 
 impl<T, D> PubNubClientInstance<T, D>

src/dx/presence/result.rs

@@ -629,6 +629,104 @@ impl Deref for HereNowResult {
     }
 }
 
+/// The result of a here now operation.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WhereNowResult {
+    /// Here now channels.
+    pub channels: Vec<String>,
+}
+
+/// Where now service response body for where now.
+/// This is a success response body for a where now  operation in The
+/// Presence service.
+///
+/// It contains information about the success of the operation, the service that
+/// provided the response, and the result of the operation.
+///
+/// It also contains information about the channels that the user is currently
+/// subscribed to.
+///
+/// Additionally, it can provide error information if the operation failed.
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[cfg_attr(feature = "serde", derive(serde::Deserialize), serde(untagged))]
+pub enum WhereNowResponseBody {
+    /// This is a success response body for a where now operation in the
+    /// Presence service.
+    ///
+    /// It contains information about the success of the operation, the service
+    /// that provided the response, and the result of the operation.
+    SuccessResponse(APISuccessBodyWithPayload<WhereNowResponseSuccessBody>),
+
+    /// This is an error response body for a where now operation in the Presence
+    /// service.
+    ///
+    /// It contains information about the service that provided the response and
+    /// details of what exactly was wrong.
+    ///
+    /// # Example
+    /// ```json
+    /// {
+    ///     "error": {
+    ///         "message": "Invalid signature",
+    ///         "source": "grant",
+    ///         "details": [
+    ///             {
+    ///                 "message": "Client and server produced different signatures for the same inputs.",
+    ///                 "location": "signature",
+    ///                 "locationType": "query"
+    ///             }
+    ///         ]
+    ///     },
+    ///     "service": "Access Manager",
+    ///     "status": 403
+    /// }
+    /// ```
+    ErrorResponse(APIErrorBody),
+}
+
+/// The result of a where now operation.
+///
+/// # Example
+/// ```json
+/// {
+///   "status":200,
+///   "message":"OK",
+///   "payload":{
+///      "channels":[
+///         "my_channel"
+///      ]
+///   },
+///   "service":"Presence"
+/// }
+/// ```
+#[cfg_attr(feature = "serde", derive(serde::Deserialize))]
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct WhereNowResponseSuccessBody {
+    /// Channels that the user is currently subscribed to.
+    pub channels: Vec<String>,
+}
+
+impl TryFrom<WhereNowResponseBody> for WhereNowResult {
+    type Error = PubNubError;
+
+    fn try_from(value: WhereNowResponseBody) -> Result<Self, Self::Error> {
+        match value {
+            WhereNowResponseBody::SuccessResponse(resp) => Ok(Self {
+                channels: resp.payload.channels,
+            }),
+            WhereNowResponseBody::ErrorResponse(resp) => Err(resp.into()),
+        }
+    }
+}
+
+impl Deref for WhereNowResult {
+    type Target = Vec<String>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.channels
+    }
+}
+
 #[cfg(test)]
 mod it_should {
     use std::collections::HashMap;
@@ -1009,4 +1107,43 @@ mod it_should {
 
         assert!(result.is_err());
     }
+
+    #[test]
+    fn parse_where_now_response() {
+        use serde_json::json;
+
+        let input = json!({
+           "status":200,
+           "message":"OK",
+           "payload":{
+              "channels":[
+                 "my_channel"
+              ]
+           },
+           "service":"Presence"
+        });
+
+        let result: WhereNowResult = serde_json::from_value::<WhereNowResponseBody>(input)
+            .unwrap()
+            .try_into()
+            .unwrap();
+
+        result
+            .channels
+            .iter()
+            .any(|channel| channel == "my_channel");
+    }
+
+    #[test]
+    fn parse_where_now_error_response() {
+        let body = WhereNowResponseBody::ErrorResponse(APIErrorBody::AsObjectWithService {
+            status: 400,
+            error: true,
+            service: "service".into(),
+            message: "error".into(),
+        });
+        let result: Result<WhereNowResult, PubNubError> = body.try_into();
+
+        assert!(result.is_err());
+    }
 }