Improve docs around connectors

rust-runtime/aws-smithy-runtime-api/src/client.rs

@@ -20,7 +20,6 @@ pub mod runtime_plugin;
 
 pub mod auth;
 
-/// Smithy connectors and related code.
 pub mod connectors;
 
 pub mod ser_de;

rust-runtime/aws-smithy-runtime-api/src/client/connectors.rs

@@ -3,6 +3,33 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+//! Smithy connectors and related code.
+//!
+//! # What is a connector?
+//!
+//! When we talk about connectors, we are referring to the [`HttpConnector`] trait, and implementations of
+//! that trait. This trait simply takes a HTTP request, and returns a future with the response for that
+//! request.
+//!
+//! This is slightly different from what a connector is in other libraries such as
+//! [`hyper`](https://crates.io/crates/hyper). In hyper 0.x, the connector is a
+//! [`tower`](https://crates.io/crates/tower) `Service` that takes a `Uri` and returns
+//! a future with something that implements `AsyncRead + AsyncWrite`.
+//!
+//! The [`HttpConnector`](crate::client::connectors::HttpConnector) is designed to be a layer on top of
+//! whole HTTP libraries, such as hyper, which allows Smithy clients to be agnostic to the underlying HTTP
+//! transport layer. This also makes it easy to write tests with a fake HTTP connector, and several
+//! such test connector implementations are availble in [`aws-smithy-runtime`](https://crates.io/crates/aws-smithy-runtime).
+//!
+//! # Responsibilities of a connector
+//!
+//! A connector primarily makes HTTP requests, but can also be used to implement connect and read
+//! timeouts. The `HyperConnector` in [`aws-smithy-runtime`](https://crates.io/crates/aws-smithy-runtime)
+//! is an example where timeouts are implemented as part of the connector.
+//!
+//! Connectors are also responsible for DNS lookup, TLS, connection reuse, pooling, and eviction.
+//! The Smithy clients have no knowledge of such concepts.
+
 use crate::client::orchestrator::{HttpRequest, HttpResponse};
 use aws_smithy_async::future::now_or_later::NowOrLater;
 use aws_smithy_http::result::ConnectorError;

rust-runtime/aws-smithy-runtime/src/client.rs

@@ -6,13 +6,10 @@
 /// Smithy auth scheme implementations.
 pub mod auth;
 
-/// Smithy code related to connectors and connections.
+/// Built-in Smithy connectors.
 ///
-/// A "connector" manages one or more "connections", handles connection timeouts, re-establishes
-/// connections, etc.
-///
-/// "Connections" refers to the actual transport layer implementation of the connector.
-/// By default, the orchestrator uses a connector provided by `hyper`.
+/// See the [module docs in `aws-smithy-runtime-api`](aws_smithy_runtime_api::client::connectors)
+/// for more information about connectors.
 pub mod connectors;
 
 /// Utility to simplify config building for config and config overrides.

rust-runtime/aws-smithy-runtime/src/client/connectors/test_util.rs

@@ -4,6 +4,26 @@
  */
 
 //! Module with client connectors useful for testing.
+//!
+//! Each test connector is useful for different test use cases:
+//! - [`capture_request`](capture_request::capture_request): If you don't care what the
+//! response is, but just want to check that the serialized request is what you expect,
+//! then use `capture_request`. Or, alternatively, if you don't care what the request
+//! is, but want to always respond with a given response, then capture request can also
+//! be useful since you can optionally give it a response to return.
+//! - [`dvr`]: If you want to record real-world traffic and then replay it later, then DVR's
+//! [`RecordingConnector`](dvr::RecordingConnector) and [`ReplayingConnector`](dvr::ReplayingConnector)
+//! can accomplish this, and the recorded traffic can be saved to JSON and checked in. Note: if
+//! the traffic recording has sensitive information in it, such as signatures or authorization,
+//! you will need to manually scrub this out if you intend to store the recording alongside
+//! your tests.
+//! - [`EventConnector`]: If you want to have a set list of requests and their responses in a test,
+//! then the event connector will be useful. On construction, it takes a list of tuples that represent
+//! each expected request and the response for that request. At the end of the test, you can ask the
+//! connector to verify that the requests matched the expectations.
+//! - [`infallible_connection_fn`]: Allows you to create a connector from an infallible function
+//! that takes a request and returns a response.
+//! - [`NeverConnector`]: Useful for testing timeouts, where you want the connector to never respond.
 
 mod capture_request;
 pub use capture_request::{capture_request, CaptureRequestHandler, CaptureRequestReceiver};