Upgrade guidance for smithy-rs#1740

[jdisanti]

This is an upgrade guide and summary of changes for the SDK changes made in smithy-rs#1740 that added default socket connect and read timeouts. This issue will be linked in the release notes.

The SDK now defaults socket connect and read timeouts to 3.1 seconds when loading config with aws_config::load_from_env() or aws_config::from_env(). In the future, a more robust timeout default resolution scheme will be implemented that is consistent with the SDK in other languages.

How to configure timeouts

If the default timeout values don't work for your use-case, they can be changed in two ways:

Example: Changing timeouts with `aws-config`

The following loads all the defaults:

let sdk_config = aws_config::load_from_env().await;

To override the timeout config on those defaults instead, use:

let sdk_config = aws_config::from_env()
    .timeout_config(
        TimeoutConfig::builder()
            .connect_timeout(Duration::from_millis(5000))
            .read_timeout(Duration::from_millis(5000))
            .build()
	)
    .load()
    .await;

Example: Changing timeouts for an individual client

Sometimes it is useful to override the SdkConfig for just one client:

let sdk_config = aws_config::load_from_env().await;

// Create a Dynamo client using the defaults from `aws-config`
let dynamo_client = aws_sdk_dynamodb::Client::new(&sdk_config);

// Create a S3 client with the default timeouts overridden
let config = aws_sdk_s3::config::Builder::from(&sdk_config)
    .timeout_config(
        TimeoutConfig::builder()
            .connect_timeout(Duration::from_millis(5000))
            .read_timeout(Duration::from_millis(5000))
            .build(),
    )
    .build();
let s3_client = aws_sdk_s3::Client::from_conf(config);

General changes

• ⚠️ aws_smithy_client::http_connector::HttpSettings was renamed to ConnectorSettings, and it now has a builder
• ⚠️ The generated customizable_operation module was moved to operation::customize
• 🎉 RetryConfig, TimeoutConfig, and their associated structs, are now re-exported in the generated crates in the config module so that a separate dependency on aws-smithy-types is no longer needed to configure retries and timeouts.
• 🎉 Types required to customize operations are now re-exported in the generated crates under operation::customize.

Changes to timeout config

• ⚠️ aws_smithy_types::timeout::config::Config was renamed to TimeoutConfig
• ⚠️ Previously, timeout configuration was split across three structs named Api, Http, and Tcp. These structs have been flattened into TimeoutConfig, and the call timeouts were renamed to operation timeouts. The following illustrates the before and after:
  • Api::call_timeout -> TimeoutConfig::operation_timeout
  • Api::call_attempt_timeout -> TimeoutConfig::operation_attempt_timeout
  • Http::connect_timeout -> TimeoutConfig::connect_timeout
  • Http::read_timeout -> TimeoutConfig::read_timeout
• ⚠️ aws_smithy_types::tristate::TriState was removed since it's no longer needed by TimeoutConfig
• TimeoutConfig now has a disabled method to quickly construct a config with no timeouts set.

Example: Configuring an operation timeout

Before:

use aws_smithy_types::timeout;
use aws_smithy_types::tristate::TriState;

let api_timeouts = timeout::Api::new()
    .with_call_timeout(TriState::Set(Duration::from_secs(5)));
let timeout_config = timeout::Config::new().with_api_timeouts(api_timeouts);

After:

use aws_smithy_types::timeout::TimeoutConfig;

let timeout_config = TimeoutConfig::builder()
    .operation_timeout(Duration::from_secs(5))
    .build();

Example: Configuring a socket connect timeout

Before:

use aws_smithy_types::timeout;
use aws_smithy_types::tristate::TriState;

let http_timeouts = timeout::Http::new()
    .with_connect_timeout(TriState::Set(Duration::from_secs(5)));
let timeout_config = timeout::Config::new().with_http_timeouts(http_timeouts);

After:

use aws_smithy_types::timeout::TimeoutConfig;

let timeout_config = TimeoutConfig::builder()
    .connect_timeout(Duration::from_secs(5))
    .build();

Breaking changes in aws-config

• ⚠️ aws_config::load_from_env() no longer reads timeout values from environment variables or from the SDK profile or config files since this was inconsistent with the other language SDKs and would have made standardizing more difficult in the future.
  • Env vars removed:
    • AWS_API_CALL_ATTEMPT_TIMEOUT
    • AWS_API_CALL_TIMEOUT
    • AWS_READ_TIMEOUT
    • AWS_CONNECT_TIMEOUT
    • AWS_TLS_NEGOTIATION_TIMEOUT
  • Profile keys removed:
    • connect_timeout
    • tls_negotiation_timeout
    • read_timeout
    • api_call_attempt_timeout
    • api_call_timeout
• ⚠️ The HttpCredentialProvider's builder had its read_timeout and connect_timeout methods replaced with connector_settings

Changes for advanced use cases

If you're overriding the HTTP connector used by the SDK, then take a look at the smithy-rs client upgrade notes for details on how aws-smithy-client changed.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.