From 04aa4c815bf028af84fa9fdc676d1f564722916d Mon Sep 17 00:00:00 2001 From: John DiSanti Date: Tue, 5 Dec 2023 09:59:23 -0800 Subject: [PATCH] Fix docs in hyper_014 module (#3282) Moves the doc comments from HyperConnector to HyperClientBuilder where they're more relevant, and fixes the examples. This fix is for https://github.com/awslabs/aws-sdk-rust/issues/986. ---- _By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice._ --- CHANGELOG.next.toml | 12 +++ .../src/client/http/hyper_014.rs | 99 ++++++++++--------- 2 files changed, 64 insertions(+), 47 deletions(-) diff --git a/CHANGELOG.next.toml b/CHANGELOG.next.toml index 2c2289e1d4..5b27ca8c54 100644 --- a/CHANGELOG.next.toml +++ b/CHANGELOG.next.toml @@ -61,3 +61,15 @@ message = "Improve the error messages for when auth fails to select an auth sche references = ["smithy-rs#3277"] meta = { "breaking" = false, "tada" = false, "bug" = false, "target" = "client" } author = "jdisanti" + +[[aws-sdk-rust]] +message = "Fix documentation and examples on HyperConnector and HyperClientBuilder." +references = ["aws-sdk-rust#986", "smithy-rs#3282"] +meta = { "breaking" = false, "tada" = false, "bug" = false } +author = "jdisanti" + +[[smithy-rs]] +message = "Fix documentation and examples on HyperConnector and HyperClientBuilder." +references = ["smithy-rs#3282"] +meta = { "breaking" = false, "tada" = false, "bug" = false, "target" = "client" } +author = "jdisanti" diff --git a/rust-runtime/aws-smithy-runtime/src/client/http/hyper_014.rs b/rust-runtime/aws-smithy-runtime/src/client/http/hyper_014.rs index 1359beb4a3..ed29d067af 100644 --- a/rust-runtime/aws-smithy-runtime/src/client/http/hyper_014.rs +++ b/rust-runtime/aws-smithy-runtime/src/client/http/hyper_014.rs @@ -132,53 +132,9 @@ pub fn default_client() -> Option { /// /// This connector also implements socket connect and read timeouts. /// -/// # Examples -/// -/// Construct a `HyperConnector` with the default TLS implementation (rustls). -/// This can be useful when you want to share a Hyper connector between multiple -/// generated Smithy clients. -/// -/// ```no_run,ignore -/// use aws_smithy_runtime::client::connectors::hyper_connector::{DefaultHttpsTcpConnector, HyperConnector}; -/// -/// let hyper_connector = HyperConnector::builder().build(DefaultHttpsTcpConnector::new()); -/// -/// // This connector can then be given to a generated service Config -/// let config = my_service_client::Config::builder() -/// .endpoint_url("http://localhost:1234") -/// .http_connector(hyper_connector) -/// .build(); -/// let client = my_service_client::Client::from_conf(config); -/// ``` -/// -/// ## Use a Hyper client with WebPKI roots -/// -/// A use case for where you may want to use the [`HyperConnector`] is when setting Hyper client settings -/// that aren't otherwise exposed by the `Config` builder interface. Some examples include changing: -/// -/// - Hyper client settings -/// - Allowed TLS cipher suites -/// - Using an alternative TLS connector library (not the default, rustls) -/// - CA trust root certificates (illustrated using WebPKI below) -/// -/// ```no_run,ignore -/// use aws_smithy_runtime::client::connectors::hyper_connector::HyperConnector; -/// -/// let https_connector = hyper_rustls::HttpsConnectorBuilder::new() -/// .with_webpki_roots() -/// .https_only() -/// .enable_http1() -/// .enable_http2() -/// .build(); -/// let hyper_connector = HyperConnector::builder().build(https_connector); -/// -/// // This connector can then be given to a generated service Config -/// let config = my_service_client::Config::builder() -/// .endpoint_url("https://example.com") -/// .http_connector(hyper_connector) -/// .build(); -/// let client = my_service_client::Client::from_conf(config); -/// ``` +/// This shouldn't be used directly in most cases. +/// See the docs on [`HyperClientBuilder`] for examples of how +/// to customize the Hyper client. #[derive(Debug)] pub struct HyperConnector { adapter: Box, @@ -533,6 +489,55 @@ where /// /// This builder can be used to customize the underlying TCP connector used, as well as /// hyper client configuration. +/// +/// # Examples +/// +/// Construct a Hyper client with the default TLS implementation (rustls). +/// This can be useful when you want to share a Hyper connector between multiple +/// generated Smithy clients. +/// +/// ```no_run,ignore +/// use aws_smithy_runtime::client::http::hyper_014::HyperClientBuilder; +/// +/// let http_client = HyperClientBuilder::new().build_https(); +/// +/// // This connector can then be given to a generated service Config +/// let config = my_service_client::Config::builder() +/// .endpoint_url("http://localhost:1234") +/// .http_client(http_client) +/// .build(); +/// let client = my_service_client::Client::from_conf(config); +/// ``` +/// +/// ## Use a Hyper client with WebPKI roots +/// +/// A use case for where you may want to use the [`HyperClientBuilder`] is when +/// setting Hyper client settings that aren't otherwise exposed by the `Config` +/// builder interface. Some examples include changing: +/// +/// - Hyper client settings +/// - Allowed TLS cipher suites +/// - Using an alternative TLS connector library (not the default, rustls) +/// - CA trust root certificates (illustrated using WebPKI below) +/// +/// ```no_run,ignore +/// use aws_smithy_runtime::client::http::hyper_014::HyperClientBuilder; +/// +/// let https_connector = hyper_rustls::HttpsConnectorBuilder::new() +/// .with_webpki_roots() +/// .https_only() +/// .enable_http1() +/// .enable_http2() +/// .build(); +/// let http_client = HyperClientBuilder::new().build(https_connector); +/// +/// // This connector can then be given to a generated service Config +/// let config = my_service_client::Config::builder() +/// .endpoint_url("https://example.com") +/// .http_client(http_client) +/// .build(); +/// let client = my_service_client::Client::from_conf(config); +/// ``` #[derive(Clone, Default, Debug)] pub struct HyperClientBuilder { client_builder: Option,