Module http

HTTP clients and connectors

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. In hyper 0.x, the connector is a tower Service that takes a Uri and returns a future with something that implements AsyncRead + AsyncWrite.

The 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 available in aws-smithy-runtime with the test-util feature enabled.

Responsibilities of a connector

A connector primarily makes HTTP requests, but is also the place where connect and read timeouts are implemented. The HyperConnector in 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.

The HttpClient trait

Connectors allow us to make requests, but we need a layer on top of connectors so that we can handle varying connector settings. For example, say we configure some default HTTP connect/read timeouts on Client, and then configure some override connect/read timeouts for a specific operation. These timeouts ultimately are part of the connector, so the same connector can’t be reused for the two different sets of timeouts. Thus, the HttpClient implementation is responsible for managing multiple connectors with varying config. Some example configs that can impact which connector is used:

• HTTP protocol versions
• TLS settings
• Timeouts

Some of these aren’t implemented yet, but they will appear in the HttpConnectorSettings struct once they are.

Structs

• HttpConnectorFuture
  Future for HttpConnector::call.
• HttpConnectorSettings
  Settings for HTTP Connectors
• HttpConnectorSettingsBuilder
  Builder for HttpConnectorSettings.
• SharedHttpClient
  Shared HTTP client for use across multiple clients and requests.
• SharedHttpConnector
  A shared HttpConnector implementation.

Traits

• HttpClient
  HTTP client abstraction.
• HttpConnector
  Trait with a call function that asynchronously converts a request into a response.

Functions

• http_client_fn
  Returns a SharedHttpClient that calls the given connector function to select a HTTP connector.