HTTP connector upgrade guidance

[jdisanti]

If you don't currently call http_connector()/with_tcp_connector() on Config, SdkConfig, ConfigLoader, or ProviderConfig, then you can stop reading this guide now since you won't be impacted by these changes.

Previously, a HTTP connector was configurable on SdkConfig and Config via the http_connector() method, which took a DynConnector from the aws-smithy-client crate. However, a connector is tied to other configuration values, such as connect/read timeouts, and HTTP protocol version. The previous API didn't reflect these ties very well, and many connector creation methods, such as default_connector, took ConnectorSettings as an argument. This API made it impossible to change the read/connect timeouts or HTTP protocol version in operation-specific config overrides.

To remedy this problems, a new trait named HttpClient was introduced that will be configurable on SdkConfig and Config in place of DynConnector. This trait looks as follows:

/// HTTP client abstraction.  
///  
/// A HTTP client implementation must apply connect/read timeout settings,  
/// and must maintain a connection pool.  
pub trait HttpClient: Send + Sync + fmt::Debug {  
    /// Returns a HTTP connector based on the requested connector settings.  
    ///
    /// The settings include connect/read timeouts, which should be incorporated
    /// into the connector. The `HttpClient` is responsible for caching
    /// the connector across requests.
    ///
    /// In the future, the settings may have additional parameters added,
    /// such as HTTP version, or TLS certificate paths.
    fn http_connector(  
        &self,  
        settings: &HttpConnectorSettings,  
        components: &RuntimeComponents,  
    ) -> SharedHttpConnector;  
}

There is a built-in hyper client available in the aws-smithy-runtime crate, which can be constructed with HyperClientBuilder and given to config. For example, if you want to customize your TLS configuration, you can do the following:

use aws_smithy_runtime::client::http::hyper_014::HyperClientBuilder;

// Create a connector that will be used to establish TLS connections
let tls_connector = hyper_rustls::HttpsConnectorBuilder::new()
	.with_webpki_roots()
	.https_only()
	.enable_http1()
	.enable_http2()
	.build();

// Create a hyper-based HTTP client that uses this TLS connector.
let http_client = HyperClientBuilder::new().build(tls_connector)

// Example: Set the client on config for the AWS SDK:
let config = aws_config::from_env().http_client(http_client).load().await;

// Example: Set the client on the service `Config` for both the AWS SDK and smithy-rs:
let config = some_service::Config::builder()
	.http_client(http_client)
	.build();

If you used with_tcp_connector, then replacing that will be similar to the code above (there is a http_client function in ProviderConfig), but the tls_connector will be replaced with the connector you were passing to with_tcp_connector.

Test/mock connectors

If you were using any of the test/mock/fake connectors from aws_smithy_client, then they have all been renamed and moved into aws_smithy_runtime::client::http::test_util module behind the ["client", "test-util"] features. See the module overview
in the docs for more information. Below is a mapping of old to new names:

• TestConnection -> StaticReplayClient
• dvr::ReplayingConnection -> dvr::ReplayingClient
• dvr::RecordingConnection -> dvr::RecordingClient
• infallible_connection_fn -> infallible_client_fn

capture_request remains unchanged other than being moved and returning a HttpClient instance instead of a HttpConnector.

The constructor for TestConnection/StaticReplayClient has been changed to take a list of ReplayEvent types now. ReplayEvent implements From<(HttpRequest, HttpResponse)>, and also has a new method that takes a request/response.

Other smaller changes

• aws_smithy_runtime_api::client::connectors was renamed to aws_smithy_runtime_api::client::http
• The builder for LazyCredentialsCache had its sleep/set_sleep methods renamed to sleep_impl/set_sleep_impl for consistency.

In general, you should not need to depend on aws-smithy-client anymore if you do currently.

[DavidSouther]

Examples update in awsdocs/aws-doc-sdk-examples#5483