Adding cache refresh logic with new URL RefreshNow parameter (#65)

*Issue #, if available:* Closes 12

*Description of changes:*
Supports new refreshNow parameter in URL requests to the agent, setting
this parameter to true will call Secrets Manger to get latest value of
secret

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

---------

Co-authored-by: Caitlin Russell <caitarus@amazon.com>

Author: crus-umich

README.md

@@ -345,7 +345,95 @@ def get_secret():
         # Handle network errors
         raise Exception(f"Error: {e}")
 ```
+------
+
+**Force-refresh secrets with `RefreshNow`**
+
+Learn how to use the refreshNow parameter to force the Secrets Manager Agent (SMA) to refresh secret values.
+
+Secrets Manager Agent uses an in-memory cache to store secret values, which it refreshes periodically. By default, this refresh occurs when you request a secret after the Time to Live (TTL) has expired, typically every 300 seconds. However, this approach can sometimes result in stale secret values, especially if a secret rotates before the cache entry expires.
+
+To address this limitation, Secrets Manager Agent supports a parameter called `refreshNow` in the URL. You can use this parameter to force an immediate refresh of a secret's value, bypassing the cache and ensuring you have the most up-to-date information.
+
+Default behavior (without `refreshNow`):
+- Uses cached values until TTL expires
+- Refreshes secrets only after TTL (default 300 seconds)
+- May return stale values if secrets rotate before the cache expires
+
+Behavior with `refreshNow=true`:
+- Bypasses the cache entirely
+- Retrieves the latest secret value directly from Secrets Manager
+- Updates the cache with the fresh value and resets the TTL
+- Ensures you always get the most current secret value
+
+By using the `refreshNow` parameter, you can ensure that you're always working with the most current secret values, even in scenarios where frequent secret rotation is necessary.
+
+## `refreshNow` parameter behavior
+
+`refreshNow` set to `true`:
+- If Secrets Manager Agent can't retrieve the secret from Secrets Manager, it returns an error and does not update the cache.
+
+`refreshNow` set to `false` or not specified:
+- Secrets Manager Agent follows its default behavior:
+  - If the cached value is fresher than the TTL, Secrets Manager Agent returns the cached value.
+  - If the cached value is older than the TTL, Secrets Manager Agent makes a call to Secrets Manager.
+
+## Using the refreshNow parameter
+
+To use the `refreshNow` parameter, include it in the URL for the Secrets Manager Agent GET request.
+
+### Example - Secrets Manager Agent GET request with refreshNow parameter
+
+> **Important**: The default value of `refreshNow` is `false`. When set to `true`, it overrides the TTL specified in the Secrets Manager Agent configuration file and makes an API call to Secrets Manager.
+
+#### [ curl ]
+
+The following curl example shows how force Secrets Manager Agent to refresh the secret. The example relies on the SSRF being present in a file, which is where it is stored by the install script.
+
+```bash
+curl -v -H \
+"X-Aws-Parameters-Secrets-Token: $(</var/run/awssmatoken)" \
+'http://localhost:2773/secretsmanager/get?secretId=<YOUR_SECRET_ID>&refreshNow=true' \
+echo
+```
+
+#### [ Python ]
+
+The following Python example shows how to get a secret from the Secrets Manager Agent. The example relies on the SSRF being present in a file, which is where it is stored by the install script.
+
+```python
+import requests
+import json
 
+# Function that fetches the secret from Secrets Manager Agent for the provided secret id. 
+def get_secret():
+    # Construct the URL for the GET request
+    url = f"http://localhost:2773/secretsmanager/get?secretId=<YOUR_SECRET_ID>&refreshNow=true"
+
+    # Get the SSRF token from the token file
+    with open('/var/run/awssmatoken') as fp:
+        token = fp.read() 
+
+    headers = {
+        "X-Aws-Parameters-Secrets-Token": token.strip()
+    }
+
+    try:
+        # Send the GET request with headers
+        response = requests.get(url, headers=headers)
+
+        # Check if the request was successful
+        if response.status_code == 200:
+            # Return the secret value
+            return response.text
+        else:
+            # Handle error cases
+            raise Exception(f"Status code {response.status_code} - {response.text}")
+
+    except Exception as e:
+        # Handle network errors
+        raise Exception(f"Error: {e}")
+```
 ------
 
 ## Configure the Secrets Manager Agent<a name="secrets-manager-agent-config"></a>

aws_secretsmanager_agent/src/cache_manager.rs

@@ -44,6 +44,7 @@ impl CacheManager {
     /// * `name` - The name of the secret to fetch.
     /// * `version` - The version of the secret to fetch.
     /// * `label` - The label of the secret to fetch.
+    /// * `refresh_now` - Whether to serve from the cache or fetch from ASM.
     ///
     /// # Returns
     ///
@@ -65,9 +66,14 @@ impl CacheManager {
         secret_id: &str,
         version: Option<&str>,
         label: Option<&str>,
+        refresh_now: bool,
     ) -> Result<String, HttpError> {
         // Read the secret from the cache or fetch it over the network.
-        let found = match self.0.get_secret_value(secret_id, version, label).await {
+        let found = match self
+            .0
+            .get_secret_value(secret_id, version, label, refresh_now)
+            .await
+        {
             Ok(value) => value,
             Err(e) if e.is::<SdkError<GetSecretValueError, HttpResponse>>() => {
                 let (code, msg, status) = svc_err::<GetSecretValueError>(e)?;
@@ -154,10 +160,10 @@ pub mod tests {
     use aws_sdk_secretsmanager as secretsmanager;
     use aws_smithy_runtime::client::http::test_util::{infallible_client_fn, NeverClient};
     use aws_smithy_types::body::SdkBody;
-    use core::time::Duration;
     use http::{Request, Response};
     use serde_json::Value;
     use std::thread::sleep;
+    use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
     use std::cell::RefCell;
     use std::thread_local;
@@ -166,13 +172,14 @@ pub mod tests {
         "arn:aws:secretsmanager:us-west-2:123456789012:secret:{{name}}-NhBWsc";
     pub const DEFAULT_VERSION: &str = "5767290c-d089-49ed-b97c-17086f8c9d79";
     pub const DEFAULT_LABEL: &str = "AWSCURRENT";
+    pub const DEFAULT_SECRET_STRING: &str = "hunter2";
 
     // Template GetSecretValue responses for testing
     const GSV_BODY: &str = r###"{
         "ARN": "{{arn}}",
         "Name": "{{name}}",
         "VersionId": "{{version}}",
-        "SecretString": "hunter2",
+        "SecretString": "{{secret}}",
         "VersionStages": [
             "{{label}}"
         ],
@@ -248,6 +255,15 @@ pub mod tests {
             .map_or(DEFAULT_LABEL, |x| x.as_str().unwrap());
         let name = req_map.get("SecretId").unwrap().as_str().unwrap(); // Does not handle full ARN case.
 
+        let secret_string = match name {
+            secret if secret.starts_with("REFRESHNOW") => SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap()
+                .as_millis()
+                .to_string(),
+            _ => DEFAULT_SECRET_STRING.to_string(),
+        };
+
         let (code, template) = match parts.headers["x-amz-target"].to_str().unwrap() {
             "secretsmanager.GetSecretValue" if name.starts_with("KMSACCESSDENIED") => {
                 (400, KMS_ACCESS_DENIED_BODY)
@@ -276,6 +292,7 @@ pub mod tests {
             .replace("{{arn}}", FAKE_ARN)
             .replace("{{name}}", name)
             .replace("{{version}}", version)
+            .replace("{{secret}}", &secret_string)
             .replace("{{label}}", label);
         (code, rsp)
     }

aws_secretsmanager_agent/src/main.rs

@@ -428,7 +428,9 @@ mod tests {
         assert_eq!(map.get("Name").unwrap(), name);
         assert_eq!(map.get("ARN").unwrap(), &fake_arn);
         assert_eq!(map.get("VersionId").unwrap(), version);
-        assert_eq!(map.get("SecretString").unwrap(), "hunter2");
+        if !name.contains("REFRESHNOW") {
+            assert_eq!(map.get("SecretString").unwrap(), "hunter2");
+        }
         assert_eq!(map.get("CreatedDate").unwrap(), "1569534789.046");
         assert_eq!(
             map.get("VersionStages").unwrap().as_array().unwrap(),
@@ -622,6 +624,14 @@ mod tests {
         validate_response("MyTest", body);
     }
 
+    // Verify a query using the refreshNow parameter
+    #[tokio::test]
+    async fn basic_refresh_success() {
+        let (status, body) = run_request("/secretsmanager/get?secretId=MyTest&refreshNow=1").await;
+        assert_eq!(status, StatusCode::OK);
+        validate_response("MyTest", body);
+    }
+
     // Verify a query using the pending label
     #[tokio::test]
     async fn pending_success() {
@@ -646,7 +656,7 @@ mod tests {
     async fn all_args_success() {
         let ver = "000000000000";
         let req =
-            format!("/secretsmanager/get?secretId=MyTest&versionStage=AWSPENDING&versionId={ver}");
+            format!("/secretsmanager/get?secretId=MyTest&versionStage=AWSPENDING&versionId={ver}&refreshNow=true");
         let (status, body) = run_request(&req).await;
         assert_eq!(status, StatusCode::OK);
         validate_response_extra("MyTest", ver, vec!["AWSPENDING"], body);
@@ -676,6 +686,38 @@ mod tests {
         );
     }
 
+    // Verify refreshNow behavior
+    #[tokio::test]
+    async fn refresh_now_test() {
+        let responses = run_requests_with_client(
+            vec![
+                ("GET", "/secretsmanager/get?secretId=REFRESHNOWtestsecret"),
+                ("GET", "/secretsmanager/get?secretId=REFRESHNOWtestsecret"),
+                (
+                    "GET",
+                    "/secretsmanager/get?secretId=REFRESHNOWtestsecret&refreshNow=true",
+                ),
+            ],
+            vec![("X-Aws-Parameters-Secrets-Token", "xyzzy")],
+            None,
+        )
+        .await
+        .unwrap();
+
+        let mut secret_strings = Vec::new();
+        for (status, body) in responses {
+            assert_eq!(status, StatusCode::OK);
+
+            let map: serde_json::Map<String, Value> = serde_json::from_slice(&body).unwrap();
+            let secret_string = map.get("SecretString").unwrap().to_string();
+
+            secret_strings.insert(0, secret_string)
+        }
+
+        assert_ne!(secret_strings[1], secret_strings[2]);
+        assert_eq!(secret_strings[0], secret_strings[1]);
+    }
+
     // Verify a basic path based request with an alternate header succeeds
     #[tokio::test]
     async fn path_success() {
@@ -700,6 +742,15 @@ mod tests {
         validate_response_extra("My/Test", DEFAULT_VERSION, vec!["AWSPENDING"], body);
     }
 
+    // Verify a query using the refreshNow parameter
+    #[tokio::test]
+    async fn path_refresh_success() {
+        let req = "/v1/My/Test?versionStage=AWSPENDING&refreshNow=0";
+        let (status, body) = run_request(&req).await;
+        assert_eq!(status, StatusCode::OK);
+        validate_response_extra("My/Test", DEFAULT_VERSION, vec!["AWSPENDING"], body);
+    }
+
     // Verify a query for a specific version.
     #[tokio::test]
     async fn path_version_success() {
@@ -714,7 +765,7 @@ mod tests {
     #[tokio::test]
     async fn path_all_args_success() {
         let ver = "000000000000";
-        let req = format!("/v1/My/Test?versionStage=AWSPENDING&versionId={ver}");
+        let req = format!("/v1/My/Test?versionStage=AWSPENDING&versionId={ver}&refreshNow=true");
         let (status, body) = run_request(&req).await;
         assert_eq!(status, StatusCode::OK);
         validate_response_extra("My/Test", ver, vec!["AWSPENDING"], body);

aws_secretsmanager_agent/src/parse.rs

@@ -9,9 +9,20 @@ pub(crate) struct GSVQuery {
     pub secret_id: String,
     pub version_id: Option<String>,
     pub version_stage: Option<String>,
+    pub refresh_now: bool,
 }
 
 impl GSVQuery {
+    fn parse_refresh_value(s: &str) -> Result<bool, HttpError> {
+        match s.to_lowercase().as_str() {
+            "true" => Ok(true),
+            "1" => Ok(true),
+            "false" => Ok(false),
+            "0" => Ok(false),
+            _ => Err(HttpError(400, "invalid refreshNow value".to_string())),
+        }
+    }
+
     pub(crate) fn try_from_query(s: &str) -> Result<Self, HttpError> {
         // url library can only parse complete URIs. The host/port/scheme used is irrelevant since it is not used
         let complete_uri = format!("http://localhost{}", s);
@@ -22,13 +33,15 @@ impl GSVQuery {
             secret_id: "".into(),
             version_id: None,
             version_stage: None,
+            refresh_now: false,
         };
 
         for (k, v) in url.query_pairs() {
             match k.borrow() {
                 "secretId" => query.secret_id = v.into(),
                 "versionId" => query.version_id = Some(v.into()),
                 "versionStage" => query.version_stage = Some(v.into()),
+                "refreshNow" => query.refresh_now = GSVQuery::parse_refresh_value(&v)?,
                 p => return Err(HttpError(400, format!("unknown parameter: {}", p))),
             }
         }
@@ -55,12 +68,14 @@ impl GSVQuery {
             secret_id,
             version_id: None,
             version_stage: None,
+            refresh_now: false,
         };
 
         for (k, v) in url.query_pairs() {
             match k.borrow() {
                 "versionId" => query.version_id = Some(v.into()),
                 "versionStage" => query.version_stage = Some(v.into()),
+                "refreshNow" => query.refresh_now = GSVQuery::parse_refresh_value(&v)?,
                 p => return Err(HttpError(400, format!("unknown parameter: {}", p))),
             }
         }
@@ -83,6 +98,69 @@ mod tests {
         assert_eq!(query.secret_id, secret_id);
         assert_eq!(query.version_id, None);
         assert_eq!(query.version_stage, None);
+        assert_eq!(query.refresh_now, false);
+    }
+
+    #[test]
+    fn parse_query_refresh() {
+        let secret_id = "MyTest".to_owned();
+        let query = GSVQuery::try_from_query(&format!(
+            "/secretsmanager/get?secretId={}&refreshNow={}",
+            secret_id, true
+        ))
+        .unwrap();
+
+        assert_eq!(query.secret_id, secret_id);
+        assert_eq!(query.version_id, None);
+        assert_eq!(query.version_stage, None);
+        assert_eq!(query.refresh_now, true);
+    }
+
+    #[test]
+    fn parse_query_refresh_false() {
+        let secret_id = "MyTest".to_owned();
+        let query = GSVQuery::try_from_query(&format!(
+            "/secretsmanager/get?secretId={}&refreshNow={}",
+            secret_id, "0"
+        ))
+        .unwrap();
+
+        assert_eq!(query.secret_id, secret_id);
+        assert_eq!(query.version_id, None);
+        assert_eq!(query.version_stage, None);
+        assert_eq!(query.refresh_now, false);
+    }
+
+    #[test]
+    fn parse_refresh_invalid_parameter() {
+        let secret_id = "MyTest".to_owned();
+        let version_id = "myversion".to_owned();
+        let version_stage = "dev".to_owned();
+        match GSVQuery::try_from_query(&format!(
+            "/secretsmanager/get?secretId={}&versionId={}&versionStage={}&refreshNow=123",
+            secret_id, version_id, version_stage
+        )) {
+            Ok(_) => panic!("should not parse"),
+            Err(e) => {
+                assert_eq!(e.0, 400);
+                assert_eq!(e.1, "invalid refreshNow value");
+            }
+        }
+    }
+
+    #[test]
+    fn parse_refresh_case_insensitive() {
+        let secret_id = "MyTest".to_owned();
+        let query = GSVQuery::try_from_query(&format!(
+            "/secretsmanager/get?secretId={}&refreshNow={}",
+            secret_id, "FALSE"
+        ))
+        .unwrap();
+
+        assert_eq!(query.secret_id, secret_id);
+        assert_eq!(query.version_id, None);
+        assert_eq!(query.version_stage, None);
+        assert_eq!(query.refresh_now, false);
     }
 
     #[test]