chore: Preparation for publishing SDK (#31)

Author: poppoerika

.github/workflows/ci.yaml

@@ -8,6 +8,15 @@ env:
   CARGO_TERM_COLOR: always
 
 jobs:
+  rustfmt:
+    name: Style & Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: rustfmt
+        run: cargo fmt -- --check
+      - name: Rigorous lint via Clippy
+        run: cargo clippy --all-targets --all-features -- -D warnings
   build_rust:
     runs-on: ubuntu-latest
     env:
@@ -19,8 +28,6 @@ jobs:
         run: cargo build --verbose
       - name: Cargo Check
         run: cargo check
-      - name: Rustfmt
-        run: cargo fmt -- --check
       - name: Unit Tests
         run: cargo test --lib
       - name: Doc Tests

Cargo.toml

@@ -1,8 +1,13 @@
 [package]
 name = "momento"
 version = "0.1.0"
-authors = ["Matt Straathof <[email protected]>"]
+authors = ["momento"]
 edition = "2018"
+description = "Client SDK for Momento services"
+readme = "README.md"
+license = "Apache-2.0"
+license-file = "LICENSE"
+repository = "https://github.com/momentohq/client-sdk-rust"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 

README.md

@@ -0,0 +1,77 @@
+# Momento client-sdk-rust
+
+:warning: Experimental SDK :warning:
+
+Rust SDK for Momento is experimental and under active development.
+There could be non-backward compatible changes or removal in the future.
+Please be aware that you may need to update your source code with the current version of the SDK when its version gets upgraded.
+
+---
+
+<br/>
+
+Rust SDK for Momento, a serverless cache that automatically scales without any of the operational overhead required by traditional caching solutions.
+
+<br/>
+
+## Getting Started :running:
+
+### Requirements
+
+- A Momento Auth Token is required, you can generate one using the [Momento CLI](https://github.com/momentohq/momento-cli)
+
+<br/>
+
+### Using Momento
+
+```rust
+use std::env;
+use momento::simple_cache_client::SimpleCacheClient;
+
+// Initializing Momento
+let auth_token = env::var("TEST_AUTH_TOKEN").expect("env var TEST_AUTH_TOKEN must be set");
+let item_default_ttl_seconds = 60
+let mut cache_client = SimpleCacheClient::new(auth_token, item_default_ttl_seconds).await.unwrap();
+
+// Creating a cache named "cache"
+let cache_name = String::from("cache");
+cache_client.create_cache(&cache_name).await.unwrap()
+
+// Sets key with default TTL and get value with that key
+let key = String::from("my_key");
+let value = String::from("my_value");
+cache_client.set(&cache_name, key.clone(), value.clone(), None).await.unwrap();
+let result = cache_client.get(&cache_name, key.clone()).await.unwrap();
+println!("Looked up value: {}", result.value);
+
+// Sets key with TTL of 5 seconds
+cache_client.set(&cache_name, key.clone(), value.clone(), 5).await.unwrap();
+
+// Permanently deletes cache
+cache_client.delete_cache(&cache_name).await.unwrap();
+```
+
+<br/>
+
+## Running Tests :zap:
+
+Doc and integration tests require an auth token for testing. Set the env var `TEST_AUTH_TOKEN` to
+provide it.
+
+Running unit tests:
+
+```
+cargo test --lib
+```
+
+Running doc tests:
+
+```
+TEST_AUTH_TOKEN=<auth token> cargo test --doc
+```
+
+Running integration tests:
+
+```
+TEST_AUTH_TOKEN=<auth token> cargo test --tests
+```

src/endpoint_resolver.rs

@@ -16,20 +16,20 @@ impl MomentoEndpointsResolver {
         let claims = utils::get_claims(auth_token);
         let control_endpoint = MomentoEndpointsResolver::get_control_endpoint(&claims, hosted_zone);
         let data_endpoint = MomentoEndpointsResolver::get_data_endpoint(&claims, hosted_zone);
-        return MomentoEndpoints {
+        MomentoEndpoints {
             control_endpoint,
             data_endpoint,
-        };
+        }
     }
 
     fn get_control_endpoint(claims: &Claims, hosted_zone: &Option<String>) -> String {
-        return MomentoEndpointsResolver::get_control_endpoint_from_hosted_zone(hosted_zone)
-            .unwrap_or_else(|| format!("https://{}:443", claims.cp));
+        MomentoEndpointsResolver::get_control_endpoint_from_hosted_zone(hosted_zone)
+            .unwrap_or_else(|| format!("https://{}:443", claims.cp))
     }
 
     fn get_data_endpoint(claims: &Claims, hosted_zone: &Option<String>) -> String {
-        return MomentoEndpointsResolver::get_data_endpoint_from_hosted_zone(hosted_zone)
-            .unwrap_or_else(|| format!("https://{}:443", claims.c));
+        MomentoEndpointsResolver::get_data_endpoint_from_hosted_zone(hosted_zone)
+            .unwrap_or_else(|| format!("https://{}:443", claims.c))
     }
 
     fn get_control_endpoint_from_hosted_zone(hosted_zone: &Option<String>) -> Option<String> {

src/grpc/cache_header_interceptor.rs

@@ -6,7 +6,10 @@ pub struct CacheHeaderInterceptor {
 impl tonic::service::Interceptor for CacheHeaderInterceptor {
     fn call(&mut self, request: tonic::Request<()>) -> Result<tonic::Request<()>, tonic::Status> {
         let request_metadata = request.metadata().clone();
-        let mut result = tonic::Request::new(request.into_inner());
+        let mut result = {
+            let message = request.into_inner();
+            tonic::Request::new(message)
+        };
         result.metadata_mut().insert(
             "authorization",
             tonic::metadata::AsciiMetadataValue::from_str(self.auth_key.as_str()).unwrap(),

src/response/cache_get_response.rs

@@ -1,17 +1,24 @@
+/// Encapsulates the status of a cache get operation.
 #[derive(Debug)]
 pub enum MomentoGetStatus {
+    /// Status if an item was found in cache.
     HIT,
+    /// Status if an item was not found in cache.
     MISS,
     ERROR,
 }
 
+/// Response for a cache get operation.
 #[derive(Debug)]
 pub struct MomentoGetResponse {
+    /// The result of a cache get operation.
     pub result: MomentoGetStatus,
+    /// Value stored in the cache as u8 vector.
     pub value: Vec<u8>,
 }
 
 impl MomentoGetResponse {
+    /// Returns a value stored in the cache as a UTF-8.
     pub fn as_string(&self) -> &str {
         return std::str::from_utf8(self.value.as_slice()).unwrap_or_default();
     }

src/response/cache_set_response.rs

@@ -1,9 +1,13 @@
+/// Encapsulates the status of a cache set operation
 #[derive(Debug)]
 pub enum MomentoSetStatus {
     OK,
     ERROR,
 }
+
+/// Response for a cache set operation.
 #[derive(Debug)]
 pub struct MomentoSetResponse {
+    /// The result of a cache set operation.
     pub result: MomentoSetStatus,
 }

src/response/create_signing_key_response.rs

@@ -1,9 +1,14 @@
 use serde::{Deserialize, Serialize};
 
+/// The results of a singing key operation.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct MomentoCreateSigningKeyResponse {
+    /// The ID of the key
     pub key_id: String,
+    /// Key itself
     pub key: String,
+    /// When the key expires
     pub expires_at: u64,
+    /// Endpoint for creating a pre-signed url
     pub endpoint: String,
 }

src/response/error.rs

@@ -1,17 +1,31 @@
 use tonic::codegen::http;
 
+/// Exception type for resulting from invalid interactions with Momento Services.
 #[derive(Debug)]
 pub enum MomentoError {
+    /// Momento Service encountered an unexpected exception while trying to fulfill the request.
     InternalServerError(String),
+    /// Invalid parameters sent to Momento Services.
     BadRequest(String),
+    /// Insufficient permissions to execute an operation.
     PermissionDenied(String),
+    /// Authentication token is not provided or is invalid.
     Unauthenticated(String),
+    /// Requested resource or the resource on which an operation was requested doesn't exist.
     NotFound(String),
+    /// A resource already exists.
     AlreadyExists(String),
+    /// Operation was cancelled.
     Cancelled(String),
+    /// Requested operation did not complete in allotted time.
     Timeout(String),
+    /// Requested operation couldn't be completed because system limits were hit.
     LimitExceeded(String),
+    /// Represents all client side exceptions thrown by the SDK.
+    /// his exception typically implies that the request wasn't sent to the service successfully or if the service responded, the sdk couldn't interpret the response.
+    /// An example would be SDK client was unable to convert the user provided data into a valid request that was expected by the service.
     ClientSdkError(String),
+    /// SDK client side validation fails.
     InvalidArgument(String),
 }
 
@@ -86,7 +100,7 @@ fn status_to_error(status: tonic::Status) -> MomentoError {
         | tonic::Code::Aborted
         | tonic::Code::Internal
         | tonic::Code::Unavailable
-        | tonic::Code::DataLoss
-        | _ => MomentoError::InternalServerError(status.message().to_string()),
+        | tonic::Code::DataLoss => MomentoError::InternalServerError(status.message().to_string()),
+        _ => MomentoError::InternalServerError(status.message().to_string()),
     }
 }

src/response/list_cache_response.rs

@@ -1,10 +1,15 @@
+/// Response cache object for list of caches.
 #[derive(Debug)]
 pub struct MomentoCache {
+    /// Name of the cache associated with a specific client.
     pub cache_name: String,
 }
 
+/// The result of a cache list operation.
 #[derive(Debug)]
 pub struct MomentoListCacheResult {
+    /// Vector of cache information defined in MomentoCache.
     pub caches: Vec<MomentoCache>,
+    /// Next Page Token returned by Simple Cache Service along with the list of caches.
     pub next_token: String,
 }

src/simple_cache_client.rs

@@ -165,7 +165,7 @@ impl SimpleCacheClient {
             data_client: data_client.unwrap(),
             item_default_ttl_seconds: default_ttl_seconds,
         };
-        return Ok(simple_cache_client);
+        Ok(simple_cache_client)
     }
 
     async fn build_control_client(
@@ -186,7 +186,7 @@ impl SimpleCacheClient {
             },
         );
         let client = ScsControlClient::new(interceptor);
-        return Ok(client);
+        Ok(client)
     }
 
     async fn build_data_client(
@@ -206,7 +206,7 @@ impl SimpleCacheClient {
             },
         );
         let client = ScsClient::new(interceptor);
-        return Ok(client);
+        Ok(client)
     }
 
     /// Creates a new Momento cache
@@ -215,7 +215,7 @@ impl SimpleCacheClient {
     ///
     /// * `name` - name of cache to create
     pub async fn create_cache(&mut self, name: &str) -> Result<(), MomentoError> {
-        utils::is_cache_name_valid(&name)?;
+        utils::is_cache_name_valid(name)?;
         let request = Request::new(CreateCacheRequest {
             cache_name: name.to_string(),
         });
@@ -245,7 +245,7 @@ impl SimpleCacheClient {
     /// # })
     /// ```
     pub async fn delete_cache(&mut self, name: &str) -> Result<(), MomentoError> {
-        utils::is_cache_name_valid(&name)?;
+        utils::is_cache_name_valid(name)?;
         let request = Request::new(DeleteCacheRequest {
             cache_name: name.to_string(),
         });
@@ -287,7 +287,7 @@ impl SimpleCacheClient {
             .collect();
         let response = MomentoListCacheResult {
             caches,
-            next_token: res.next_token.to_string(),
+            next_token: res.next_token,
         };
         Ok(response)
     }
@@ -301,9 +301,7 @@ impl SimpleCacheClient {
         &mut self,
         ttl_minutes: u32,
     ) -> Result<MomentoCreateSigningKeyResponse, MomentoError> {
-        let request = Request::new(CreateSigningKeyRequest {
-            ttl_minutes: ttl_minutes,
-        });
+        let request = Request::new(CreateSigningKeyRequest { ttl_minutes });
         let res = self
             .control_client
             .create_signing_key(request)
@@ -327,7 +325,7 @@ impl SimpleCacheClient {
     ///
     /// * `key_id` - the ID of the key to revoke
     pub async fn revoke_signing_key(&mut self, key_id: &str) -> Result<(), MomentoError> {
-        utils::is_key_id_valid(&key_id)?;
+        utils::is_key_id_valid(key_id)?;
         let request = Request::new(RevokeSigningKeyRequest {
             key_id: key_id.to_string(),
         });
@@ -369,10 +367,10 @@ impl SimpleCacheClient {
         body: I,
         ttl_seconds: Option<u64>,
     ) -> Result<MomentoSetResponse, MomentoError> {
-        utils::is_cache_name_valid(&cache_name)?;
+        utils::is_cache_name_valid(cache_name)?;
         let temp_ttl = ttl_seconds.unwrap_or(self.item_default_ttl_seconds);
         let ttl_to_use = match utils::is_ttl_valid(&temp_ttl) {
-            Ok(_) => temp_ttl * 1000 as u64,
+            Ok(_) => temp_ttl * 1000_u64,
             Err(e) => return Err(e),
         };
         let mut request = tonic::Request::new(SetRequest {
@@ -382,7 +380,7 @@ impl SimpleCacheClient {
         });
         request.metadata_mut().append(
             "cache",
-            tonic::metadata::AsciiMetadataValue::from_str(&cache_name).unwrap(),
+            tonic::metadata::AsciiMetadataValue::from_str(cache_name).unwrap(),
         );
         let _ = self.data_client.set(request).await?;
         Ok(MomentoSetResponse {
@@ -424,16 +422,16 @@ impl SimpleCacheClient {
         cache_name: &str,
         key: I,
     ) -> Result<MomentoGetResponse, MomentoError> {
-        utils::is_cache_name_valid(&cache_name)?;
+        utils::is_cache_name_valid(cache_name)?;
         let mut request = tonic::Request::new(GetRequest {
             cache_key: key.into_bytes(),
         });
         request.metadata_mut().append(
             "cache",
-            tonic::metadata::AsciiMetadataValue::from_str(&cache_name).unwrap(),
+            tonic::metadata::AsciiMetadataValue::from_str(cache_name).unwrap(),
         );
         let response = self.data_client.get(request).await?.into_inner();
-        return match response.result() {
+        match response.result() {
             ECacheResult::Hit => Ok(MomentoGetResponse {
                 result: MomentoGetStatus::HIT,
                 value: response.cache_body,
@@ -443,6 +441,6 @@ impl SimpleCacheClient {
                 value: response.cache_body,
             }),
             _ => todo!(),
-        };
+        }
     }
 }