Unverified Commit 4615785c authored by 82marbag's avatar 82marbag Committed by GitHub
Browse files

Add TLS docs page (#2898) 



## Motivation and Context
The TLS connector page is missing

## Description
Render the TLS connector documentation page

## Checklist
<!--- If a checkbox below is not applicable, then please DELETE it
rather than leaving it unchecked -->
- [ ] I have updated `CHANGELOG.next.toml` if I made changes to the
smithy-rs codegen or runtime crates
- [ ] I have updated `CHANGELOG.next.toml` if I made changes to the AWS
SDK, generated SDK code, or SDK runtime crates

----

_By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice._

---------

Signed-off-by: default avatarDaniele Ahmed <ahmeddan@amazon.de>
Co-authored-by: default avatardavid-perez <d@vidp.dev>
parent c7fe610f

design/src/SUMMARY.md

+1 −0
Original line number Diff line number Diff line
@@ -6,6 +6,7 @@ 
- [Transport](transport/overview.md)

  - [HTTP Operations](transport/operation.md)

  - [HTTP Middleware](transport/middleware.md)

  - [TLS Connector](transport/connector.md)



- [Smithy](./smithy/overview.md)

  - [Simple Shapes](./smithy/simple_shapes.md)

design/src/transport/connector.md

+6 −38
Original line number Diff line number Diff line 
The Smithy client provides a default TLS connector, but a custom one can be plugged in.

`rustls` is enabled with the feature flag `rustls`.

The Smithy client provides a default TLS connector, but a custom one can be

plugged in. `rustls` is enabled with the feature flag `rustls`.



The client had previously supported `native-tls`. You can use your custom connector like this.



Create your connector:



```rust

/// A `hyper` connector that uses the `native-tls` crate for TLS. To use this in a smithy client,

/// wrap it in a [hyper_ext::Adapter](crate::hyper_ext::Adapter).

pub type NativeTls = hyper_tls::HttpsConnector<hyper::client::HttpConnector>;



pub fn native_tls() -> NativeTls {

    let mut tls = hyper_tls::native_tls::TlsConnector::builder();

    let tls = tls

        .min_protocol_version(Some(hyper_tls::native_tls::Protocol::Tlsv12))

        .build()

        .unwrap_or_else(|e| panic!("Error while creating TLS connector: {}", e));

    let mut http = hyper::client::HttpConnector::new();

    http.enforce_http(false);

    hyper_tls::HttpsConnector::from((http, tls.into()))

}

```



Plug the connector in the client:

```rust

let mut builder = hyper::client::Builder::default();

builder.pool_max_idle_per_host(70);

let connector = aws_smithy_client::erase::DynConnector::new(

    aws_smithy_client::hyper_ext::Adapter::builder()

        .hyper_builder(builder)

        .connector_settings(std::default::Default::default())

        .build(native_tls()),

);

let raw_client = aws_smithy_client::builder::Builder::new()

    .connector(connector)

    .middleware_fn(...)

    .build_dyn();

```
 
The client had previously (prior to version 0.56.0) supported `native-tls`. You

can continue to use a client whose TLS implementation is backed by `native-tls`

by passing in a custom connector. Check out the `custom_connectors.rs` tests in

the `pokemon-service-tls` example crate.

examples/pokemon-service-tls/Cargo.toml

+2 −1
Original line number Diff line number Diff line
@@ -26,8 +26,9 @@ pokemon-service-common = { path = "../pokemon-service-common/" } 
assert_cmd = "2.0"

serial_test = "1.0.0"



# This dependency is only required for testing the `pokemon-service-tls` program.

# These dependencies are only required for testing the `pokemon-service-tls` program.

hyper-rustls = { version = "0.24", features = ["http2"] }

hyper-tls = { version = "0.5" }



# Local paths

aws-smithy-client = { path = "../../rust-runtime/aws-smithy-client/", features = ["rustls"] }

examples/pokemon-service-tls/tests/common/mod.rs

+30 −0
Original line number Diff line number Diff line
@@ -49,3 +49,33 @@ pub fn client_http2_only() -> Client { 
        .build();

    Client::from_conf(config)

}



/// A `hyper` connector that uses the `native-tls` crate for TLS. To use this in a smithy client,

/// wrap it in a [aws_smithy_client::hyper_ext::Adapter].

pub type NativeTlsConnector = hyper_tls::HttpsConnector<hyper::client::HttpConnector>;



fn native_tls_connector() -> NativeTlsConnector {

    let cert = hyper_tls::native_tls::Certificate::from_pem(

        std::fs::read_to_string(DEFAULT_TEST_CERT)

            .expect("could not open certificate")

            .as_bytes(),

    )

    .expect("could not parse certificate");



    let tls_connector = hyper_tls::native_tls::TlsConnector::builder()

        .min_protocol_version(Some(hyper_tls::native_tls::Protocol::Tlsv12))

        .add_root_certificate(cert)

        .build()

        .unwrap_or_else(|e| panic!("error while creating TLS connector: {}", e));

    let mut http_connector = hyper::client::HttpConnector::new();

    http_connector.enforce_http(false);

    hyper_tls::HttpsConnector::from((http_connector, tls_connector.into()))

}



pub fn native_tls_client() -> Client {

    let config = Config::builder()

        .http_connector(Adapter::builder().build(native_tls_connector()))

        .endpoint_url(format!("https://{DEFAULT_DOMAIN}:{DEFAULT_PORT}"))

        .build();

    Client::from_conf(config)

}

examples/pokemon-service-tls/tests/http2.rs→examples/pokemon-service-tls/tests/custom_connectors.rs

+29 −0
Original line number Diff line number Diff line
@@ -5,10 +5,25 @@ 


pub mod common;



use serial_test::serial;



#[tokio::test]

async fn test_check_health_http2() {

#[serial]

// This test invokes an operation with a client that can only send HTTP2 requests and whose TLS

// implementation is backed by `rustls`.

async fn test_check_health_http2_rustls_connector() {

    let _child = common::run_server().await;

    let client = common::client_http2_only();



    let _check_health = client.check_health().send().await.unwrap();

}



#[tokio::test]

#[serial]

// This test invokes an operation with a client whose TLS implementation is backed by `native_tls`.

async fn test_check_health_native_tls_connector() {

    let _child = common::run_server().await;

    let client = common::native_tls_client();



    let _check_health = client.check_health().send().await.unwrap();

}