feature: make retry behavior user-configurable (#741)

=========================

**Breaking changes**

- :warning: MSRV increased from 1.52.1 to 1.53.0 per our 3-behind MSRV policy.

- :warning: `smithy_client::retry::Config` field `max_retries` is renamed to `max_attempts`

  - This also brings a change to the semantics of the field. In the old version, setting `max_retries` to 3 would mean

    that up to 4 requests could occur (1 initial request and 3 retries). In the new version, setting `max_attempts` to 3

    would mean that up to 3 requests could occur (1 initial request and 2 retries).

- :warning: `smithy_client::retry::Config::with_max_retries` method is renamed to `with_max_attempts`

- :warning: Several classes in the codegen module were renamed and/or refactored (smithy-rs#735):

  - `ProtocolConfig` became `CodegenContext` and moved to `software.amazon.smithy.rust.codegen.smithy`

  - `HttpProtocolGenerator` became `ProtocolGenerator` and was refactored

- The `DispatchError` variant of `SdkError` now contains `ConnectorError` instead of `Box<dyn Error>` (#744).

**New this week**

- :bug: Fix an issue where `smithy-xml` may have generated invalid XML (smithy-rs#719)

- Add `RetryConfig` struct for configuring retry behavior (smithy-rs#725)

- :bug: Fix error when receiving empty event stream messages (smithy-rs#736)

- :bug: Fix bug in event stream receiver that could cause the last events in the response stream to be lost (smithy-rs#736)

- Add connect & HTTP read timeouts to IMDS, defaulting to 1 second

=======================

**Breaking changes**

- :warning: MSRV increased from 1.52.1 to 1.53.0 per our 3-behind MSRV policy.

- `SmithyConnector` and `DynConnector` now return `ConnectorError` instead of `Box<dyn Error>`. If you have written a custom connector, it will need to be updated to return the new error type. (#744)

- The `DispatchError` variant of `SdkError` now contains `ConnectorError` instead of `Box<dyn Error>` (#744).

**Tasks to cut release**

- [ ] Bump MSRV on aws-sdk-rust, then delete this line.

**New This Week**

- :tada: Make retry behavior configurable

    - With env vars `AWS_MAX_ATTEMPTS` and `AWS_RETRY_MODE`

    - With `~/.aws/config` settings `max_attempts` and `retry_mode`

    - By calling the `with_retry_config` method on a `Config` and passing in a `RetryConfig`

    - Only the `Standard` retry mode is currently implemented. `Adaptive` retry mode will be implemented at a later

      date.

    - For more info, see the AWS Reference pages on configuring these settings:

        - [Setting global max attempts](https://docs.aws.amazon.com/sdkref/latest/guide/setting-global-max_attempts.html)

        - [Setting global retry mode](https://docs.aws.amazon.com/sdkref/latest/guide/setting-global-retry_mode.html)

- :tada: Add presigned request support and examples for S3 GetObject and PutObject (smithy-rs#731, aws-sdk-rust#139)

- :tada: Add presigned request support and example for Polly SynthesizeSpeech (smithy-rs#735, aws-sdk-rust#139)

- Add connect & HTTP read timeouts to IMDS, defaulting to 1 second

default-provider = ["profile", "imds", "meta", "sts", "environment"]

profile = ["sts", "web-identity-token", "meta", "environment", "imds"]

meta = ["tokio/sync"]

imds = ["profile", "smithy-http", "smithy-types", "smithy-http-tower", "smithy-json", "tower", "aws-http", "meta"]

imds = ["profile", "smithy-http", "smithy-http-tower", "smithy-json", "tower", "aws-http", "meta"]

environment = ["meta"]

sts = ["aws-sdk-sts", "aws-hyper"]

web-identity-token = ["sts", "profile"]

aws-types = { path = "../../sdk/build/aws-sdk/aws-types" }

smithy-async = { path = "../../sdk/build/aws-sdk/smithy-async" }

smithy-client = { path = "../../sdk/build/aws-sdk/smithy-client" }

smithy-types = { path = "../../sdk/build/aws-sdk/smithy-types" }

tracing = { version = "0.1" }

tokio = { version = "1", features = ["sync"], optional = true }

aws-sdk-sts = { path = "../../sdk/build/aws-sdk/sts", optional = true }

# imds

smithy-http = { path = "../../sdk/build/aws-sdk/smithy-http", optional = true }

smithy-types = { path = "../../sdk/build/aws-sdk/smithy-types", optional = true }

smithy-http-tower = { path = "../../sdk/build/aws-sdk/smithy-http-tower", optional = true }

tower = { version = "0.4.8", optional = true }

aws-http = { path = "../../sdk/build/aws-sdk/aws-http", optional = true }

//!

//! Unless specific configuration is required, these should be constructed via [`ConfigLoader`](crate::ConfigLoader).

//!

//!

/// Default region provider chain

pub mod region {

    use aws_types::region::Region;

    use crate::environment::region::EnvironmentVariableRegionProvider;

    use crate::meta::region::{ProvideRegion, RegionProviderChain};

    use crate::{imds, profile};

    use crate::provider_config::ProviderConfig;

    use aws_types::region::Region;

    use crate::{imds, profile};

    /// Default Region Provider chain

    ///

    }

}

/// Default retry behavior configuration provider chain

pub mod retry_config {

    use smithy_types::retry::RetryConfig;

    use crate::environment::retry_config::EnvironmentVariableRetryConfigProvider;

    use crate::profile;

    use crate::provider_config::ProviderConfig;

    /// Default RetryConfig Provider chain

    ///

    /// Unlike other "providers" `RetryConfig` has no related `RetryConfigProvider` trait. Instead,

    /// a builder struct is returned which has a similar API.

    ///

    /// This provider will check the following sources in order:

    /// 1. [Environment variables](EnvironmentVariableRetryConfigProvider)

    /// 2. [Profile file](crate::profile::retry_config::ProfileFileRetryConfigProvider)

    ///

    /// # Example

    ///

    /// ```rust

    /// # use std::error::Error;

    /// # #[tokio::main]

    /// # async fn main() -> Result<(), Box<dyn Error>> {

    /// use aws_config::default_provider::retry_config;

    /// // Creating a RetryConfig from the default_provider already happens when loading a config from_env

    /// // This is only for illustration purposes

    /// let retry_config = retry_config::default_provider().retry_config().await;

    /// let config = aws_config::from_env().retry_config(retry_config).load().await;

    /// // instantiate a service client:

    /// // <my_aws_service>::Client::new(&config);

    /// #     Ok(())

    /// # }

    /// ```

    pub fn default_provider() -> Builder {

        Builder::default()

    }

    /// Builder for RetryConfig that checks the environment and aws profile for configuration

    #[derive(Default)]

    pub struct Builder {

        env_provider: EnvironmentVariableRetryConfigProvider,

        profile_file: profile::retry_config::Builder,

    }

    impl Builder {

        #[doc(hidden)]

        /// Configure the default chain

        ///

        /// Exposed for overriding the environment when unit-testing providers

        pub fn configure(mut self, configuration: &ProviderConfig) -> Self {

            self.env_provider =

                EnvironmentVariableRetryConfigProvider::new_with_env(configuration.env());

            self.profile_file = self.profile_file.configure(configuration);

            self

        }

        /// Override the profile name used by this provider

        pub fn profile_name(mut self, name: &str) -> Self {

            self.profile_file = self.profile_file.profile_name(name);

            self

        }

        /// Attempt to create a [RetryConfig](smithy_types::retry::RetryConfig) from following sources in order:

        /// 1. [Environment variables](crate::environment::retry_config::EnvironmentVariableRetryConfigProvider)

        /// 2. [Profile file](crate::profile::retry_config::ProfileFileRetryConfigProvider)

        /// 3. [RetryConfig::default()](smithy_types::retry::RetryConfig::default)

        ///

        /// Precedence is considered on a per-field basis

        ///

        /// # Panics

        ///

        /// - Panics if the `AWS_MAX_ATTEMPTS` env var or `max_attempts` profile var is set to 0

        /// - Panics if the `AWS_RETRY_MODE` env var or `retry_mode` profile var is set to "adaptive" (it's not yet supported)

        pub async fn retry_config(self) -> RetryConfig {

            // Both of these can return errors due to invalid config settings and we want to surface those as early as possible

            // hence, we'll panic if any config values are invalid (missing values are OK though)

            // We match this instead of unwrapping so we can print the error with the `Display` impl instead of the `Debug` impl that unwrap uses

            let builder_from_env = match self.env_provider.retry_config_builder() {

                Ok(retry_config_builder) => retry_config_builder,

                Err(err) => panic!("{}", err),

            };

            let builder_from_profile = match self.profile_file.build().retry_config_builder().await

            {

                Ok(retry_config_builder) => retry_config_builder,

                Err(err) => panic!("{}", err),

            };

            builder_from_env.merge_with(builder_from_profile).build()

        }

    }

}

/// Default credentials provider chain

pub mod credentials {

    use std::borrow::Cow;

    use aws_types::credentials::{future, ProvideCredentials};

    use crate::environment::credentials::EnvironmentVariableCredentialsProvider;

    use crate::meta::credentials::{CredentialsProviderChain, LazyCachingCredentialsProvider};

    use crate::meta::region::ProvideRegion;

    use aws_types::credentials::{future, ProvideCredentials};

    use crate::provider_config::ProviderConfig;

    use std::borrow::Cow;

    #[cfg(any(feature = "rustls", feature = "native-tls"))]

    /// Default Credentials Provider chain

    ///

                Some(provider) => provider.region().await,

                None => self.region_chain.build().region().await,

            };

            let conf = self.conf.unwrap_or_default().with_region(region);

            let profile_provider = self.profile_file_builder.configure(&conf).build();

            let env_provider = EnvironmentVariableCredentialsProvider::new_with_env(conf.env());

            let profile_provider = self.profile_file_builder.configure(&conf).build();

            let web_identity_token_provider = self.web_identity_builder.configure(&conf).build();

            let imds_provider = self.imds_builder.configure(&conf).build();

                .or_else("WebIdentityToken", web_identity_token_provider)

                .or_else("Ec2InstanceMetadata", imds_provider);

            let cached_provider = self.credential_cache.configure(&conf).load(provider_chain);

            DefaultCredentialsChain(cached_provider.build())

        }

    }

    #[cfg(test)]

    mod test {

        use tracing_test::traced_test;

        use aws_types::credentials::ProvideCredentials;

        use aws_types::os_shim_internal::{Env, Fs};

        use smithy_types::retry::{RetryConfig, RetryMode};

        use crate::default_provider::credentials::DefaultCredentialsChain;

        use crate::default_provider::retry_config;

        use crate::provider_config::ProviderConfig;

        use crate::test_case::TestEnvironment;

        /// Test generation macro

        ///

            };

        }

        use crate::default_provider::credentials::DefaultCredentialsChain;

        use crate::test_case::TestEnvironment;

        use aws_types::credentials::ProvideCredentials;

        use tracing_test::traced_test;

        make_test!(prefer_environment);

        make_test!(profile_static_keys);

        make_test!(web_identity_token_env);

                .expect("creds should load");

            assert_eq!(creds.access_key_id(), "correct_key_secondary");

        }

        #[tokio::test]

        async fn test_returns_default_retry_config_from_empty_profile() {

            let env = Env::from_slice(&[("AWS_CONFIG_FILE", "config")]);

            let fs = Fs::from_slice(&[("config", "[default]\n")]);

            let provider_config = ProviderConfig::no_configuration().with_env(env).with_fs(fs);

            let actual_retry_config = retry_config::default_provider()

                .configure(&provider_config)

                .retry_config()

                .await;

            let expected_retry_config = RetryConfig::new();

            assert_eq!(actual_retry_config, expected_retry_config);

            // This is redundant but it's really important to make sure that

            // we're setting these exact values by default so we check twice

            assert_eq!(actual_retry_config.max_attempts(), 3);

            assert_eq!(actual_retry_config.mode(), RetryMode::Standard);

        }

        #[tokio::test]

        async fn test_no_retry_config_in_empty_profile() {

            let env = Env::from_slice(&[("AWS_CONFIG_FILE", "config")]);

            let fs = Fs::from_slice(&[("config", "[default]\n")]);

            let provider_config = ProviderConfig::no_configuration().with_env(env).with_fs(fs);

            let actual_retry_config = retry_config::default_provider()

                .configure(&provider_config)

                .retry_config()

                .await;

            let expected_retry_config = RetryConfig::new();

            assert_eq!(actual_retry_config, expected_retry_config)

        }

        #[tokio::test]

        async fn test_creation_of_retry_config_from_profile() {

            let env = Env::from_slice(&[("AWS_CONFIG_FILE", "config")]);

            // TODO standard is the default mode; this test would be better if it was setting it to adaptive mode

            // adaptive mode is currently unsupported so that would panic

            let fs = Fs::from_slice(&[(

                "config",

                // If the lines with the vars have preceding spaces, they don't get read

                r#"[default]

max_attempts = 1

retry_mode = standard

            "#,

            )]);

            let provider_config = ProviderConfig::no_configuration().with_env(env).with_fs(fs);

            let actual_retry_config = retry_config::default_provider()

                .configure(&provider_config)

                .retry_config()

                .await;

            let expected_retry_config = RetryConfig::new()

                .with_max_attempts(1)

                .with_retry_mode(RetryMode::Standard);

            assert_eq!(actual_retry_config, expected_retry_config)

        }

        #[tokio::test]

        async fn test_env_retry_config_takes_precedence_over_profile_retry_config() {

            let env = Env::from_slice(&[

                ("AWS_CONFIG_FILE", "config"),

                ("AWS_MAX_ATTEMPTS", "42"),

                ("AWS_RETRY_MODE", "standard"),

            ]);

            // TODO standard is the default mode; this test would be better if it was setting it to adaptive mode

            // adaptive mode is currently unsupported so that would panic

            let fs = Fs::from_slice(&[(

                "config",

                // If the lines with the vars have preceding spaces, they don't get read

                r#"[default]

max_attempts = 88

retry_mode = standard

            "#,

            )]);

            let provider_config = ProviderConfig::no_configuration().with_env(env).with_fs(fs);

            let actual_retry_config = retry_config::default_provider()

                .configure(&provider_config)

                .retry_config()

                .await;

            let expected_retry_config = RetryConfig::new()

                .with_max_attempts(42)

                .with_retry_mode(RetryMode::Standard);

            assert_eq!(actual_retry_config, expected_retry_config)

        }

        #[tokio::test]

        #[should_panic = "failed to parse max attempts set by aws profile: invalid digit found in string"]

        async fn test_invalid_profile_retry_config_panics() {

            let env = Env::from_slice(&[("AWS_CONFIG_FILE", "config")]);

            let fs = Fs::from_slice(&[(

                "config",

                // If the lines with the vars have preceding spaces, they don't get read

                r#"[default]

max_attempts = potato

            "#,

            )]);

            let provider_config = ProviderConfig::no_configuration().with_env(env).with_fs(fs);

            let _ = retry_config::default_provider()

                .configure(&provider_config)

                .retry_config()

                .await;

        }

    }

}

/// Load regions from the environment

pub mod region;

pub use region::EnvironmentVariableRegionProvider;

/// Load retry behavior configuration from the environment

pub mod retry_config;

pub use retry_config::EnvironmentVariableRetryConfigProvider;