Keys api (#20)

* Introduced actions, and changed to Arc<String>

* Updated documentation

Author: emmanuelantony2000

Cargo.toml

@@ -13,8 +13,12 @@ crate-type = ["cdylib", "rlib"]
 
 [dependencies]
 async-trait = "0.1.50"
-bytes = "1.0.1"
+base64 = "0.13.0"
+hmac = "0.11.0"
 http = "0.2.4"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+sha2 = "0.9.5"
 thiserror = "1.0.24"
 
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]

src/client/builder.rs

@@ -1,3 +1,5 @@
+use std::sync::Arc;
+
 use super::Client;
 use crate::transport::Transport;
 
@@ -6,16 +8,16 @@ use crate::transport::WasmClient;
 
 use crate::{Result, TypesenseError};
 /// Builder for the Typesense [`Client`]
-pub struct ClientBuilder<'a, T> {
+pub struct ClientBuilder<T> {
     transport: Option<Transport<T>>,
-    host: Option<&'a str>,
-    api_key: Option<&'a str>,
+    host: Option<Arc<String>>,
+    api_key: Option<Arc<String>>,
 }
 
-impl<'a, T> ClientBuilder<'a, T> {
+impl<T> ClientBuilder<T> {
     /// build [`Client`] with the current configurations. Return [`typesense::TypesenseError::ConfigError`]
     /// if a configuration is missing.
-    pub fn build(self) -> Result<Client<'a, T>> {
+    pub fn build(self) -> Result<Client<T>> {
         Ok(Client {
             transport: self.transport.ok_or_else(|| {
                 TypesenseError::ConfigError("missing client transport".to_string())
@@ -30,14 +32,14 @@ impl<'a, T> ClientBuilder<'a, T> {
     }
 
     /// Set host
-    pub fn host(mut self, host: &'a str) -> Self {
-        self.host = Some(host);
+    pub fn host(mut self, host: impl AsRef<str>) -> Self {
+        self.host = Some(Arc::new(host.as_ref().to_string()));
         self
     }
 
     /// Set api key
-    pub fn api_key(mut self, api_key: &'a str) -> Self {
-        self.api_key = Some(api_key);
+    pub fn api_key(mut self, api_key: impl AsRef<str>) -> Self {
+        self.api_key = Some(Arc::new(api_key.as_ref().to_string()));
         self
     }
 
@@ -48,7 +50,7 @@ impl<'a, T> ClientBuilder<'a, T> {
     }
 }
 
-impl<'a, T> Default for ClientBuilder<'a, T> {
+impl<T> Default for ClientBuilder<T> {
     fn default() -> Self {
         Self {
             transport: None,
@@ -63,7 +65,7 @@ impl<'a, T> Default for ClientBuilder<'a, T> {
     docsrs,
     doc(cfg(all(feature = "tokio-rt", not(target_arch = "wasm32"))))
 )]
-impl<'a> ClientBuilder<'a, crate::transport::HyperHttpsClient> {
+impl ClientBuilder<crate::transport::HyperHttpsClient> {
     /// Create client builder with a [`hyper`](https://docs.rs/hyper) client.
     /// The connector used is [`HttpsConnector`](hyper_tls::HttpsConnector).
     pub fn new_hyper() -> Self {
@@ -78,7 +80,7 @@ impl<'a> ClientBuilder<'a, crate::transport::HyperHttpsClient> {
 
 #[cfg(target_arch = "wasm32")]
 #[cfg_attr(docsrs, doc(cfg(target_arch = "wasm32")))]
-impl<'a> ClientBuilder<'a, WasmClient> {
+impl ClientBuilder<WasmClient> {
     /// Create client builder using default wasm client
     pub fn new_wasm() -> Self {
         let transport = Some(crate::transport::TransportBuilder::new_wasm().build());

src/client/keys.rs

@@ -0,0 +1,201 @@
+//! Module containing everything related to Keys API.
+//!
+//! More info [here](https://typesense.org/docs/0.20.0/api/api-keys.html).
+
+use hmac::{Hmac, Mac, NewMac};
+use serde::{Deserialize, Serialize};
+use sha2::Sha256;
+
+use super::Client;
+use crate::transport::HttpLowLevel;
+
+/// To interact with the Keys API.
+pub struct ClientKeys<T> {
+    pub(super) client: Client<T>,
+}
+
+impl<T> ClientKeys<T>
+where
+    T: HttpLowLevel,
+{
+    /// Create an API Key.
+    ///
+    /// More info [here](https://typesense.org/docs/0.20.0/api/api-keys.html#create-an-api-key).
+    pub async fn create(
+        &self,
+        actions: Vec<Actions>,
+        collections: Vec<String>,
+        description: impl Into<Option<String>>,
+        expires_at: impl Into<Option<usize>>,
+    ) -> crate::Result<ClientKeyCreate> {
+        let create = Create {
+            actions,
+            collections,
+            description: description.into(),
+            expires_at: expires_at.into(),
+        };
+
+        let response = self
+            .client
+            .post("/keys", serde_json::to_vec(&create)?)
+            .await?;
+
+        let body = response.into_body();
+        Ok(serde_json::from_slice(&body)?)
+    }
+
+    /// Retrieve (metadata about) a key.
+    ///
+    /// More info [here](https://typesense.org/docs/0.20.0/api/api-keys.html#retrieve-an-api-key).
+    pub async fn retrieve(&self, n: usize) -> crate::Result<ClientKeyRetrieve> {
+        let response = self.client.get(format!("/keys/{}", n).as_str()).await?;
+
+        let body = response.into_body();
+        Ok(serde_json::from_slice(&body)?)
+    }
+
+    /// Retrieve (metadata about) all keys.
+    ///
+    /// More info [here](https://typesense.org/docs/0.20.0/api/api-keys.html#list-all-keys).
+    pub async fn retrieve_all(&self) -> crate::Result<ClientKeyRetrieveAll> {
+        let response = self.client.get("/keys").await?;
+
+        let body = response.into_body();
+        Ok(serde_json::from_slice(&body)?)
+    }
+
+    /// Delete an API key given its ID.
+    ///
+    /// More info [here](https://typesense.org/docs/0.20.0/api/api-keys.html#delete-api-key).
+    pub async fn delete(&self, n: usize) -> crate::Result<ClientKeyDelete> {
+        let response = self.client.delete(format!("/keys/{}", n).as_str()).await?;
+
+        let body = response.into_body();
+        Ok(serde_json::from_slice(&body)?)
+    }
+
+    /// Generate a scoped search API key that can have embedded search parameters in them.
+    ///
+    /// More info [here](https://typesense.org/docs/0.20.0/api/api-keys.html#generate-scoped-search-key).
+    pub async fn generate_scoped_search_key(
+        key: impl AsRef<str>,
+        filter_by: impl AsRef<str>,
+        expires_at: usize,
+    ) -> crate::Result<String> {
+        let generate_scoped_search_key = GenerateScopedSearchKey {
+            filter_by: filter_by.as_ref().to_string(),
+            expires_at,
+        };
+        let params = serde_json::to_string(&generate_scoped_search_key)?;
+
+        let mut mac = Hmac::<Sha256>::new_from_slice(key.as_ref().as_bytes()).unwrap();
+        mac.update(params.as_bytes());
+        let result = mac.finalize();
+        let digest = base64::encode(result.into_bytes());
+
+        let key_prefix = &key.as_ref()[0..4];
+        let raw_scoped_key = format!("{}{}{}", digest, key_prefix, params);
+
+        Ok(base64::encode(raw_scoped_key.as_bytes()))
+    }
+}
+
+/// Enum over the possible list of Actions.
+///
+/// More info [here](https://typesense.org/docs/0.19.0/api/api-keys.html#sample-actions).
+#[derive(Serialize, Deserialize)]
+pub enum Actions {
+    /// Allows only search requests.
+    #[serde(rename = "documents:search")]
+    DocumentsSearch,
+
+    /// Allows fetching a single document.
+    #[serde(rename = "documents:get")]
+    DocumentsGet,
+
+    /// Allow all kinds of collection related operations.
+    #[serde(rename = "documents:*")]
+    DocumentsAll,
+
+    /// Allows a collection to be deleted.
+    #[serde(rename = "collections:delete")]
+    CollectionsDelete,
+
+    /// Allows a collection to be created.
+    #[serde(rename = "collections:create")]
+    CollectionsCreate,
+
+    /// Allow all kinds of collection related operations.
+    #[serde(rename = "collections:*")]
+    CollectionsAll,
+
+    /// Allows all operations.
+    #[serde(rename = "*")]
+    All,
+}
+
+/// Structure returned by [`ClientKeys::create`] function.
+#[derive(Serialize, Deserialize)]
+pub struct ClientKeyCreate {
+    /// Key ID
+    pub id: usize,
+
+    /// Key Actions
+    pub actions: Vec<Actions>,
+
+    /// Key Collections
+    pub collections: Vec<String>,
+
+    /// Key Value
+    pub value: String,
+
+    /// Key Description
+    pub description: String,
+}
+
+/// Structure returned by [`ClientKeys::retrieve`] function.
+#[derive(Serialize, Deserialize)]
+pub struct ClientKeyRetrieve {
+    /// Key Actions
+    pub actions: Vec<Actions>,
+
+    /// Key Collections
+    pub collections: Vec<String>,
+
+    /// Key Description
+    pub description: String,
+
+    /// Key ID
+    pub id: usize,
+
+    /// Key Value Prefix
+    pub value_prefix: String,
+}
+
+/// Structure returned by [`ClientKeys::retrieve_all`] function.
+#[derive(Serialize, Deserialize)]
+pub struct ClientKeyRetrieveAll {
+    /// Vector of all the Keys
+    pub keys: Vec<ClientKeyRetrieve>,
+}
+
+/// Structure returned by [`ClientKeys::delete`] function.
+#[derive(Serialize, Deserialize)]
+pub struct ClientKeyDelete {
+    /// ID of the deleted Key
+    pub id: usize,
+}
+
+#[derive(Serialize)]
+struct Create {
+    actions: Vec<Actions>,
+    collections: Vec<String>,
+    description: Option<String>,
+    expires_at: Option<usize>,
+}
+
+#[derive(Serialize)]
+struct GenerateScopedSearchKey {
+    filter_by: String,
+    expires_at: usize,
+}

src/client/mod.rs

@@ -1,53 +1,75 @@
-use bytes::Bytes;
+use std::sync::Arc;
+
+use http::Response;
 
 use crate::transport::HttpLowLevel;
 use crate::transport::Transport;
 use crate::Result;
 
 mod builder;
+pub mod keys;
+
 pub use builder::ClientBuilder;
+pub use keys::ClientKeys;
 
 #[allow(dead_code)]
 pub const TYPESENSE_API_KEY_HEADER_NAME: &str = "X-TYPESENSE-API-KEY";
 
 /// Root client for top level APIs
-pub struct Client<'a, T> {
+#[derive(Clone)]
+pub struct Client<T> {
     transport: Transport<T>,
-    host: &'a str,
-    api_key: &'a str,
+    host: Arc<String>,
+    api_key: Arc<String>,
 }
 
-impl<'a, T> Client<'a, T> {
+impl<T> Client<T> {
     /// Gets the transport of the client
     pub fn transport(&self) -> &Transport<T> {
         &self.transport
     }
 }
 
+impl<T> Client<T>
+where
+    T: Clone,
+{
+    /// Make the ClientKeys struct, to interact with the Keys API.
+    pub fn keys(&self) -> ClientKeys<T> {
+        ClientKeys {
+            client: self.clone(),
+        }
+    }
+}
+
 #[allow(dead_code)]
-impl<'a, C> Client<'a, C>
+impl<C> Client<C>
 where
     C: HttpLowLevel,
 {
     pub(crate) async fn send(
         &self,
         method: http::Method,
         path: &str,
-        body: Bytes,
-    ) -> Result<C::Response> {
+        body: Vec<u8>,
+    ) -> Result<Response<Vec<u8>>> {
         let uri = format!("{}{}", self.host, path);
         let mut headers = http::HeaderMap::default();
         headers.insert(TYPESENSE_API_KEY_HEADER_NAME, self.api_key.parse().unwrap());
         self.transport.send(method, &uri, headers, body).await
     }
 
-    pub(crate) async fn get(&self, path: &str) -> Result<C::Response> {
-        self.send(http::Method::GET, path, Bytes::new()).await
+    pub(crate) async fn get(&self, path: &str) -> Result<Response<Vec<u8>>> {
+        self.send(http::Method::GET, path, Vec::new()).await
     }
 
-    pub(crate) async fn post(&self, path: &str, body: Bytes) -> Result<C::Response> {
+    pub(crate) async fn post(&self, path: &str, body: Vec<u8>) -> Result<Response<Vec<u8>>> {
         self.send(http::Method::POST, path, body).await
     }
+
+    pub(crate) async fn delete(&self, path: &str) -> Result<Response<Vec<u8>>> {
+        self.send(http::Method::DELETE, path, Vec::new()).await
+    }
 }
 
 #[cfg(all(test, feature = "tokio-rt", not(target_arch = "wasm32")))]
@@ -71,14 +93,12 @@ mod hyper_tests {
         let response = client.get("/test_api_key").await?;
 
         assert_eq!(response.status(), StatusCode::OK);
-        let bytes = hyper::body::to_bytes(response).await?;
-        assert_eq!(bytes, body.as_bytes());
+        assert_eq!(response.into_body(), body.as_bytes());
 
         let response = client.post("/test_api_key", body.clone().into()).await?;
 
         assert_eq!(response.status(), StatusCode::OK);
-        let bytes = hyper::body::to_bytes(response).await?;
-        assert_eq!(bytes, body.as_bytes());
+        assert_eq!(response.into_body(), body.as_bytes());
 
         Ok(())
     }