SmokeHTTP 是由 async-http-client 提供的通用 HTTP 客户端的专门化版本，它提供了将服务操作从底层 HTTP 协议抽象出来所需的通用功能。该库主要由 SmokeFramework 和 SmokeAWS 使用。

此库在 async-http-client 提供的功能之上提供了一些额外的功能：

1. HTTPRequestInputProtocol 和 HTTPResponseOutputProtocol 协议提供了一种机制，分别将输入类型解构为 HTTP 请求的不同组成部分，并从 HTTP 响应的组成部分构造输出类型。
2. 基于协议的策略，用于确定异步完成处理的线程模型。
3. 支持指数退避重试。
4. 日志记录和调用指标的发布。
5. 用于处理请求级别跟踪的扩展点。

要使用 SmokeHTTPClient，用户可以使用实例化的委托 (HTTPClientDelegate, HTTPClientInvocationDelegate) 在其特定客户端的构造函数中实例化一个 HTTPOperationsClient，这些委托用于定义客户端特定的逻辑。

SmokeHTTP 遵循与 SmokeAWS 相同的支持策略，请点击此处查看。

SmokeHTTP 使用 Swift Package Manager。要使用该框架，请将以下依赖项添加到您的 Package.swift 中。

对于 swift-tools 版本 5.2 及更高版本

dependencies: [
    .package(url: "https://github.com/amzn/smoke-http.git", from: "2.0.0")
]

.target(name: ..., dependencies: [
    ..., 
    .product(name: "SmokeHTTPClient", package: "smoke-http"),
]),

对于 swift-tools 版本 5.1 及更早版本

dependencies: [
    .package(url: "https://github.com/amzn/smoke-http.git", from: "2.0.0")
]

.target(
    name: ...,
    dependencies: [..., "SmokeHTTPClient"]),

使用以下代码构造一个 HTTPClient

import SmokeHTTPClient

let httpOperationsClient = HTTPOperationsClient(endpointHostName: endpointHostName,
                                                endpointPort: endpointPort,
                                                contentType: contentType,
                                                clientDelegate: clientDelegate,
                                                connectionTimeoutSeconds: connectionTimeoutSeconds,
                                                eventLoopProvider: = .createNew)

此构造函数的输入是

1. endpointHostName：此客户端发起的调用要联系的主机名。不包括 scheme 或端口。

• 例如 dynamodb.us-west-2.amazonaws.com。

2. endpointPort：此客户端发起的调用要联系的端口。

• 例如 443。

3. contentType：此客户端发起的调用的请求正文的内容类型。

• 例如 application/json。

4. clientDelegate：符合 HTTPClientDelegate 协议的类型的实例。
5. connectionTimeoutSeconds：此客户端发起的请求的超时时间（以秒为单位）。
6. eventLoopProvider：此客户端的事件循环提供程序。默认为创建新的事件循环。

HTTPOperationsClient 上有多个 execute 调用的变体。 下面描述了一个变体，但所有变体都大致相似 -

try httpOperationsClient.executeAsyncRetriableWithOutput(
            endpointOverride: nil,
            endpointPath = endpointPath,
            httpMethod: .GET,
            input: InputType,
            completion: completion,
            asyncResponseInvocationStrategy: asyncResponseInvocationStrategy,
            invocationContext: invocationContext,
            retryConfiguration: retryConfiguration,
            retryOnError: retryOnError)

此函数的输入是

1. endpointOverride：覆盖用于此调用的主机名。 默认为 nil，使用客户端初始化期间提供的端点。
2. endpointPath：此调用要联系的路径。
3. httpMethod：此调用的 HTTPMethod。
4. input：符合 HTTPRequestInputProtocol 协议的类型的实例。
5. completion：类型为 (Result<OutputType, HTTPClientError>) -> () 的闭包，用于处理调用的结果。 OutputType 必须是符合 HTTPResponseOutputProtocol 协议的类型。
6. asyncResponseInvocationStrategy：用于执行完成处理程序的调用策略。

• GlobalDispatchQueueAsyncResponseInvocationStrategy 作为默认值提供，它将在全局 Dispatch Queue 上执行完成处理程序。
• SameThreadAsyncResponseInvocationStrategy 也提供了在客户端的事件循环内的 SwiftNIO 回调线程上执行完成处理程序。

7. invocationContext：类型为 HTTPClientInvocationContext 的实例。
8. retryConfiguration：类型为 HTTPClientRetryConfiguration 的实例，指示客户端应如何处理故障时的自动重试。
9. . retryOnError：类型为 (HTTPClientError) -> Bool 的闭包，可用于确定当请求因提供的错误而失败时是否应进行自动重试。

HTTPOperationsClient.execute* 函数的完整变体列表是

1. executeAsyncRetriableWithOutput：异步地执行 HTTP 请求，内置支持自动重试，并且产生输出。
2. executeAsyncRetriableWithoutOutput：同步地执行 HTTP 请求，内置支持自动重试，并且不产生输出。
3. executeAsyncWithoutOutput：异步地执行 HTTP 请求，没有内置支持自动重试，并且不产生输出。
4. executeAsyncWithOutput：异步地执行 HTTP 请求，没有内置支持自动重试，并且产生输出。
5. executeSyncRetriableWithoutOutput：同步地执行 HTTP 请求，内置支持自动重试，并且不产生输出。
6. executeSyncRetriableWithOutput：同步地执行 HTTP 请求，内置支持自动重试，并且产生输出。
7. executeSyncWithoutOutput：同步地执行 HTTP 请求，没有内置支持自动重试，并且不产生输出。
8. executeSyncWithOutput：同步地执行 HTTP 请求，没有内置支持自动重试，并且产生输出。

HTTPClientDelegate 协议提供了多个扩展点，可用于自定义客户端。

协议函数要求

1. getResponseError：根据客户端的 HTTP 响应确定特定于客户端的错误。
2. encodeInputAndQueryString：根据调用的输入确定用于 HTTP 请求的组件。
3. decodeOutput：根据客户端的 HTTP 响应创建输出类型的实例。
4. getTLSConfiguration：检索客户端要使用的 TLS 配置。

HTTPClientDelegate 协议提供了多个扩展点，可用于自定义客户端的调用。

协议属性要求

1. specifyContentHeadersForZeroLengthBody：即使没有请求正文，是否也应在请求中发送 Content-Length 和 Content-Type 标头。

协议函数要求

1. addClientSpecificHeaders：确定要添加到 HTTP 请求的任何其他标头。
2. handleErrorResponses：根据客户端的 HTTP 响应确定特定于客户端的错误。如果返回非 nil 错误，则覆盖 HTTPClientDelegate.getResponseError。

HTTPRequestInputProtocol 提供了一种机制，用于将输入转换为 HTTP 请求的不同部分。有关如何使用此协议将输入类型解构为 HTTP 请求的示例，请参见JSONAWSHttpClientDelegate.encodeInputAndQueryString()。

协议属性要求

1. queryEncodable：可选地，提供一个符合 Encodable 的类型的实例，该实例将用于生成 HTTP 请求的查询。
2. pathEncodable：可选地，提供一个符合 Encodable 的类型的实例，该实例将用于为 HTTP 请求的路径提供任何标记化的值。
3. bodyEncodable：可选地，提供一个符合 Encodable 的类型的实例，该实例将用于生成 HTTP 请求的正文。
4. additionalHeadersEncodable：可选地，提供一个符合 Encodable 的类型的实例，该实例将用于生成 HTTP 请求的其他标头。
5. pathPostfix：可选地，提供一个字符串，该字符串将在任何 token 被来自 pathEncodable 的值替换之前，添加到路径模板的末尾。

HTTPResponseOutputProtocol 提供了一种从 HTTP 响应的组成部分构造输出类型的机制。 有关如何实现此目的的示例，请参见JSONAWSHttpClientDelegate.decodeOutput()。

协议函数要求

1. compose：一个接受 bodyDecodableProvider 和 headersDecodableProvider 闭包的函数，可用于从 HTTP 响应的各个部分构造预期输出类型的部分。

HTTPClientInvocationContext 类型可用于自定义客户端的调用。

HTTPClientInvocationContext 构造函数的输入是

1. reporting：符合 HTTPClientInvocationReporting 协议的类型的实例。
2. handlerDelegate：符合 HTTPClientInvocationDelegate 协议的类型的实例。

HTTPClientInvocationReporting 协议提供了许多扩展点，重点是客户端调用的报告 -

协议属性要求

1. logger：用于与 HTTP 客户端调用相关的语句的记录器。
2. internalRequestId：向客户端发出调用的请求的内部标识。
3. traceContext：符合 InvocationTraceContext 协议的类型的实例。
4. successCounter：可选地，一个 Metrics.Counter，它将记录客户端的成功调用。
5. failure5XXCounter：可选地，一个 Metrics.Counter，它将记录客户端的不成功调用，这些调用返回 5xx 响应代码。
6. failure4XXCounter：可选地，一个 Metrics.Counter，它将记录客户端的不成功调用，这些调用返回 4xx 响应代码。
7. retryCountRecorder：可选地，一个 Metrics.Recorder，它将记录客户端调用的重试计数。
8. latencyTimer：可选地，一个 Metrics.Recorder，它将记录来自客户端的调用的延迟。

InvocationTraceContext 为请求级别跟踪提供了一个扩展点。

协议函数要求

1. handleOutwardsRequestStart：提供在请求发送之前处理客户端调用的能力，包括修改请求中发送的标头的能力。
2. handleOutwardsRequestSuccess：提供在收到响应后立即处理成功调用的能力。
3. handleOutwardsRequestFailure：提供在收到响应后立即处理不成功调用的能力。

此库在 Apache 2.0 许可证下获得许可。