Implement timeouts for LazyCachingCredentialsProvider (#595)

* Implement timeouts for LazyCachingCredentialsProvider

* Rename refresh to reload

* Update CHANGELOG

* Fix clippy

* CR feedback

* Add note about panic on `LazyCachedCredentialsProvider` builder

* Fix doc comment code reference

CHANGELOG.md

@@ -1,5 +1,6 @@
 ## vNext (Month Day Year)
 **New This Week**
+- :tada: Add LazyCachingCredentialsProvider to aws-auth for use with expiring credentials, such as STS AssumeRole. Update STS example to use this new provider (#578, #595)
 - :bug: Correctly encode HTTP Checksums using base64 instead of hex. Fixes aws-sdk-rust#164. (#615)
 - Update SDK gradle build logic to use gradle properties (#620)
 - (When complete) Add profile file provider for region (#594, #xyz)

aws/rust-runtime/aws-auth/Cargo.toml

@@ -5,8 +5,14 @@ authors = ["AWS Rust SDK Team <aws-sdk-rust@amazon.com>", "Russell Cohen <rcoh@a
 license = "Apache-2.0"
 edition = "2018"
 
+[features]
+rt-tokio = ["smithy-async/rt-tokio"]
+default = ["rt-tokio"]
+
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 [dependencies]
+pin-project = "1"
+smithy-async = { path = "../../../rust-runtime/smithy-async", default-features = false }
 smithy-http = { path = "../../../rust-runtime/smithy-http" }
 aws-types = { path = "../aws-types" }
 tokio = { version = "1", features = ["sync"] }
@@ -20,3 +26,4 @@ http = "0.2.3"
 test-env-log = { version = "0.2.7", features = ["trace"] }
 tokio = { version = "1", features = ["macros", "rt", "rt-multi-thread", "test-util"] }
 tracing-subscriber = { version = "0.2.16", features = ["fmt"] }
+smithy-async = { path = "../../../rust-runtime/smithy-async", features = ["rt-tokio"] }

aws/rust-runtime/aws-auth/src/provider.rs

@@ -3,6 +3,16 @@
  * SPDX-License-Identifier: Apache-2.0.
  */
 
+//! AWS credential providers, generic caching provider implementations, and traits to implement custom providers.
+//!
+//! Credentials providers acquire AWS credentials from environment variables, files,
+//! or calls to AWS services such as STS. Custom credential provider implementations can
+//! be provided by implementing [`ProvideCredentials`] for synchronous use-cases, or
+//! [`AsyncProvideCredentials`] for async use-cases. Generic credential caching implementations,
+//! for example,
+//! [`LazyCachingCredentialsProvider`](crate::provider::lazy_caching::LazyCachingCredentialsProvider),
+//! are also provided as part of this module.
+
 mod cache;
 pub mod env;
 pub mod lazy_caching;
@@ -16,18 +26,25 @@ use std::fmt::{Debug, Display, Formatter};
 use std::future::{self, Future};
 use std::pin::Pin;
 use std::sync::Arc;
+use std::time::Duration;
 
 #[derive(Debug)]
 #[non_exhaustive]
 pub enum CredentialsError {
     CredentialsNotLoaded,
+    ProviderTimedOut(Duration),
     Unhandled(Box<dyn Error + Send + Sync + 'static>),
 }
 
 impl Display for CredentialsError {
     fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
         match self {
             CredentialsError::CredentialsNotLoaded => write!(f, "CredentialsNotLoaded"),
+            CredentialsError::ProviderTimedOut(d) => write!(
+                f,
+                "Credentials provider timed out after {} seconds",
+                d.as_secs()
+            ),
             CredentialsError::Unhandled(err) => write!(f, "{}", err),
         }
     }

aws/rust-runtime/aws-auth/src/provider/env.rs

@@ -3,6 +3,8 @@
  * SPDX-License-Identifier: Apache-2.0.
  */
 
+//! Credential provider implementation that pulls from environment variables
+
 use crate::provider::{CredentialsError, ProvideCredentials};
 use crate::Credentials;
 use aws_types::os_shim_internal::Env;