Add caching library README and associated constructors (#13)

*Issue #, if available:*

*Description of changes:*


By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache 2.0 license.

Author: simonmarty

.gitignore

@@ -62,7 +62,6 @@ fabric.properties
 
 # Visual Studio Code
 .vscode/*
-!.vscode/settings.json
 !.vscode/tasks.json
 !.vscode/launch.json
 !.vscode/extensions.json

Cargo.lock

@@ -17,10 +17,12 @@ serde = { version = "1", features = ["derive"] }
 thiserror = "1"
 tokio = { version = "1", features = ["rt", "sync"] }
 linked-hash-map = "0.5.6"
+aws-config = "1"
 
 [dev-dependencies]
 aws-smithy-mocks-experimental = "0"
 aws-smithy-runtime = { version = "1", features = ["test-util"] }
 aws-sdk-secretsmanager = { version = "1", features = ["test-util"] }
-tokio = { version = "1", features = ["macros", "rt", "sync"] }
+tokio = { version = "1", features = ["macros", "rt", "sync", "test-util"] }
 http = "0"
+tokio-test = "0.4.4"

aws_secretsmanager_caching/Cargo.toml

@@ -0,0 +1,99 @@
+# AWS Secrets Manager Rust Caching Client
+
+The AWS Secrets Manager Rust Caching Client enables in-process caching of secrets for Rust applications.
+
+## Getting Started
+
+### Required Prerequisites
+
+To use this client you must have:
+
+* A Rust 2021 development environment. If you do not have one, go to [Rust Getting Started](https://www.rust-lang.org/learn/get-started) on the Rust Programming Language website, then download and install Rust.
+* An Amazon Web Services (AWS) account to access secrets stored in AWS Secrets Manager.
+  * **To create an AWS account**, go to [Sign In or Create an AWS Account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) and then choose **I am a new user.** Follow the instructions to create an AWS account.
+  * **To create a secret in AWS Secrets Manager**, go to [Creating Secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) and follow the instructions on that page.
+
+### Get Started
+
+The following code sample demonstrates how to get started:
+
+1. Instantiate the caching client.
+2. Request secret.
+
+```sh
+cargo add tokio -F rt-multi-thread,net,macros
+cargo add aws_secretsmanager_caching
+```
+
+```rust
+use aws_secretsmanager_caching::SecretsManagerCachingClient;
+use std::num::NonZeroUsize;
+use std::time::Duration;
+
+let client = match SecretsManagerCachingClient::default(
+    NonZeroUsize::new(1000).unwrap(),
+    Duration::from_secs(300),
+)
+.await
+{
+    Ok(c) => c,
+    Err(_) => panic!("Handle this error"),
+};
+
+let secret_string = match client.get_secret_value("MyTest", None, None).await {
+    Ok(s) => s.secret_string.unwrap(),
+    Err(_) => panic!("Handle this error"),
+};
+
+// Your code here
+```
+
+### Cache Configuration
+
+* `max_size: NonZeroUsize`: The maximum number of cached secrets to maintain before evicting secrets that have not been accessed recently.
+* `ttl: Duration`: The duration a cached item is considered valid before requiring a refresh of the secret state.
+
+### Instantiating Cache with a custom Config and a custom Client
+
+```sh
+cargo add aws_sdk_secretsmanager aws_config
+```
+
+```rust
+let config = aws_config::load_defaults(BehaviorVersion::latest())
+    .await
+    .into_builder()
+    .region(Region::from_static("us-west-2"))
+    .build();
+
+let asm_builder = aws_sdk_secretsmanager::config::Builder::from(&config);
+
+let client = match SecretsManagerCachingClient::from_builder(
+    asm_builder,
+    NonZeroUsize::new(1000).unwrap(),
+    Duration::from_secs(300),
+)
+.await
+{
+    Ok(c) => c,
+    Err(_) => panic!("Handle this error"),
+};
+
+let secret_string = client
+    .get_secret_value("MyTest", None, None)
+    .await 
+    {
+        Ok(c) => c.secret_string.unwrap(),
+        Err(_) => panic!("Handle this error"),
+    };
+
+// Your code here
+```
+
+### Getting Help
+
+Please use these community resources for getting help:
+
+* Ask a question on [Stack Overflow](https://stackoverflow.com/) and tag it with [aws-secrets-manager](https://stackoverflow.com/questions/tagged/aws-secrets-manager).
+* Open a support ticket with [AWS Support](https://console.aws.amazon.com/support/home#/)
+* If it turns out that you may have found a bug, or have a feature request, please [open an issue](https://github.com/aws/aws-secretsmanager-agent/issues/new/choose).

aws_secretsmanager_caching/README.md

@@ -11,14 +11,17 @@
 pub mod output;
 /// Manages the lifecycle of cached secrets
 pub mod secret_store;
+mod utils;
 
+use aws_config::BehaviorVersion;
 use aws_sdk_secretsmanager::Client as SecretsManagerClient;
 use secret_store::SecretStoreError;
 
 use output::GetSecretValueOutputDef;
 use secret_store::{MemoryStore, SecretStore};
 use std::{error::Error, num::NonZeroUsize, time::Duration};
 use tokio::sync::RwLock;
+use utils::CachingLibraryInterceptor;
 
 /// AWS Secrets Manager Caching client
 #[derive(Debug)]
@@ -37,6 +40,24 @@ impl SecretsManagerCachingClient {
     /// * `asm_client` - Initialized AWS SDK Secrets Manager client instance
     /// * `max_size` - Maximum size of the store.
     /// * `ttl` - Time-to-live of the secrets in the store.
+    /// ```rust
+    /// use aws_sdk_secretsmanager::Client as SecretsManagerClient;
+    /// use aws_sdk_secretsmanager::{config::Region, Config};
+    /// use aws_secretsmanager_caching::SecretsManagerCachingClient;
+    /// use std::num::NonZeroUsize;
+    /// use std::time::Duration;
+
+    /// let asm_client = SecretsManagerClient::from_conf(
+    /// Config::builder()
+    ///     .behavior_version_latest()
+    ///     .build(),
+    /// );
+    /// let client = SecretsManagerCachingClient::new(
+    ///     asm_client,
+    ///     NonZeroUsize::new(1000).unwrap(),
+    ///     Duration::from_secs(300),
+    /// );
+    /// ```
     pub fn new(
         asm_client: SecretsManagerClient,
         max_size: NonZeroUsize,
@@ -48,6 +69,75 @@ impl SecretsManagerCachingClient {
         })
     }
 
+    /// Create a new caching client with in-memory store and the default AWS SDK client configuration
+    ///
+    /// # Arguments
+    ///
+    /// * `max_size` - Maximum size of the store.
+    /// * `ttl` - Time-to-live of the secrets in the store.
+    /// ```rust
+    /// tokio_test::block_on(async {
+    /// use aws_secretsmanager_caching::SecretsManagerCachingClient;
+    /// use std::num::NonZeroUsize;
+    /// use std::time::Duration;
+    ///
+    /// let client = SecretsManagerCachingClient::default(
+    /// NonZeroUsize::new(1000).unwrap(),
+    /// Duration::from_secs(300),
+    /// ).await.unwrap();
+    /// })
+    /// ```
+    pub async fn default(max_size: NonZeroUsize, ttl: Duration) -> Result<Self, SecretStoreError> {
+        let default_config = &aws_config::load_defaults(BehaviorVersion::latest()).await;
+        let asm_builder = aws_sdk_secretsmanager::config::Builder::from(default_config)
+            .interceptor(CachingLibraryInterceptor);
+
+        let asm_client = SecretsManagerClient::from_conf(asm_builder.build());
+        Self::new(asm_client, max_size, ttl)
+    }
+
+    /// Create a new caching client with in-memory store from an AWS SDK client builder
+    ///
+    /// # Arguments
+    ///
+    /// * `asm_builder` - AWS Secrets Manager SDK client builder.
+    /// * `max_size` - Maximum size of the store.
+    /// * `ttl` - Time-to-live of the secrets in the store.
+    ///
+    /// ```rust
+    /// tokio_test::block_on(async {
+    /// use aws_secretsmanager_caching::SecretsManagerCachingClient;
+    /// use std::num::NonZeroUsize;
+    /// use std::time::Duration;
+    /// use aws_config::{BehaviorVersion, Region};
+
+    /// let config = aws_config::load_defaults(BehaviorVersion::latest())
+    /// .await
+    /// .into_builder()
+    /// .region(Region::from_static("us-west-2"))
+    /// .build();
+
+    /// let asm_builder = aws_sdk_secretsmanager::config::Builder::from(&config);
+
+    /// let client = SecretsManagerCachingClient::from_builder(
+    /// asm_builder,
+    /// NonZeroUsize::new(1000).unwrap(),
+    /// Duration::from_secs(300),
+    /// )
+    /// .await.unwrap();
+    /// })
+    /// ```
+    pub async fn from_builder(
+        asm_builder: aws_sdk_secretsmanager::config::Builder,
+        max_size: NonZeroUsize,
+        ttl: Duration,
+    ) -> Result<Self, SecretStoreError> {
+        let asm_client = SecretsManagerClient::from_conf(
+            asm_builder.interceptor(CachingLibraryInterceptor).build(),
+        );
+        Self::new(asm_client, max_size, ttl)
+    }
+
     /// Retrieves the value of the secret from the specified version.
     ///
     /// # Arguments

aws_secretsmanager_caching/src/lib.rs

@@ -0,0 +1,35 @@
+use aws_sdk_secretsmanager::config::{
+    interceptors::BeforeTransmitInterceptorContextMut, Intercept, RuntimeComponents,
+};
+use aws_smithy_types::config_bag::ConfigBag;
+
+/// SDK interceptor to append the agent name and version to the User-Agent header for CloudTrail records.
+#[derive(Debug)]
+pub(crate) struct CachingLibraryInterceptor;
+
+/// SDK interceptor to append the agent name and version to the User-Agent header for CloudTrail records.
+///
+/// This interceptor adds the agent name and version to the User-Agent header
+/// of outbound Secrets Manager SDK requests.
+impl Intercept for CachingLibraryInterceptor {
+    fn name(&self) -> &'static str {
+        "CachingLibraryInterceptor"
+    }
+
+    fn modify_before_signing(
+        &self,
+        context: &mut BeforeTransmitInterceptorContextMut<'_>,
+        _runtime_components: &RuntimeComponents,
+        _cfg: &mut ConfigBag,
+    ) -> Result<(), aws_sdk_secretsmanager::error::BoxError> {
+        let request = context.request_mut();
+        let agent = request.headers().get("user-agent").unwrap_or_default(); // Get current agent
+        let full_agent = format!(
+            "{agent} AWSSecretsManagerCachingRust/{}",
+            option_env!("CARGO_PKG_VERSION").unwrap_or("0.0.0")
+        );
+        request.headers_mut().insert("user-agent", full_agent); // Overwrite header.
+
+        Ok(())
+    }
+}