0
# AWS HTTP Client SPI
1
2
The AWS HTTP Client SPI (Service Provider Interface) provides a comprehensive set of interfaces and abstractions for implementing HTTP clients that integrate with the AWS SDK for Java v2. This SPI enables pluggable HTTP implementations while maintaining thread safety, immutability, and comprehensive configuration capabilities.
3
4
## Package Information
5
6
- **Package Name**: software.amazon.awssdk:http-client-spi
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add dependency to your Maven project
10
11
```xml
12
<dependency>
13
<groupId>software.amazon.awssdk</groupId>
14
<artifactId>http-client-spi</artifactId>
15
<version>2.32.31</version>
16
</dependency>
17
```
18
19
## Core Imports
20
21
```java
22
import software.amazon.awssdk.http.SdkHttpClient;
23
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
24
import software.amazon.awssdk.http.SdkHttpService;
25
import software.amazon.awssdk.http.HttpExecuteRequest;
26
import software.amazon.awssdk.http.SdkHttpFullRequest;
27
import software.amazon.awssdk.http.ContentStreamProvider;
28
```
29
30
## Basic Usage
31
32
```java
33
// Implementing a synchronous HTTP client
34
public class MyHttpClient implements SdkHttpClient {
35
@Override
36
public ExecutableHttpRequest prepareRequest(HttpExecuteRequest request) {
37
return new MyExecutableHttpRequest(request);
38
}
39
40
@Override
41
public String clientName() {
42
return "MyHttpClientSync";
43
}
44
45
@Override
46
public void close() {
47
// Cleanup resources
48
}
49
}
50
51
// Creating HTTP requests
52
SdkHttpFullRequest request = SdkHttpFullRequest.builder()
53
.protocol("https")
54
.host("api.example.com")
55
.port(443)
56
.encodedPath("/v1/data")
57
.putHeader("Content-Type", "application/json")
58
.contentStreamProvider(ContentStreamProvider.fromUtf8String("{\"key\":\"value\"}"))
59
.build();
60
61
// Service discovery registration
62
public class MyHttpService implements SdkHttpService {
63
@Override
64
public SdkHttpClient.Builder createHttpClientBuilder() {
65
return new MyHttpClientBuilder();
66
}
67
}
68
```
69
70
## Architecture
71
72
The AWS HTTP Client SPI is built around several key architectural components:
73
74
- **HTTP Client Interfaces**: Primary abstractions (`SdkHttpClient`, `SdkAsyncHttpClient`) for synchronous and asynchronous HTTP operations
75
- **Service Discovery**: ServiceLoader-based SPI pattern (`SdkHttpService`, `SdkAsyncHttpService`) for automatic HTTP client discovery
76
- **Request/Response Model**: Immutable HTTP message representations with builder patterns for construction
77
- **Content Management**: Flexible content stream providers supporting various input sources and reactive streams
78
- **Configuration System**: Type-safe execution attributes and comprehensive TLS/SSL configuration
79
- **Metrics Integration**: Built-in metrics collection for HTTP/1.1 and HTTP/2 operations
80
81
## Capabilities
82
83
### HTTP Client Interfaces
84
85
Core synchronous and asynchronous HTTP client abstractions that all implementations must provide. These interfaces define the contract for making HTTP requests and handling responses.
86
87
```java { .api }
88
public interface SdkHttpClient extends SdkAutoCloseable {
89
ExecutableHttpRequest prepareRequest(HttpExecuteRequest request);
90
default String clientName() { return "UNKNOWN"; }
91
}
92
93
public interface SdkAsyncHttpClient extends SdkAutoCloseable {
94
CompletableFuture<Void> execute(AsyncExecuteRequest request);
95
default String clientName() { return "UNKNOWN"; }
96
}
97
```
98
99
[HTTP Client Interfaces](./http-clients.md)
100
101
### Request and Response Model
102
103
Immutable HTTP message representations including requests, responses, headers, and execution models. Provides builder patterns for constructing HTTP messages with comprehensive configuration options.
104
105
```java { .api }
106
public interface SdkHttpFullRequest extends SdkHttpHeaders {
107
Optional<ContentStreamProvider> contentStreamProvider();
108
SdkHttpFullRequest.Builder toBuilder();
109
static Builder builder();
110
}
111
112
public interface SdkHttpResponse extends SdkHttpHeaders {
113
int statusCode();
114
Optional<String> statusText();
115
boolean isSuccessful();
116
}
117
```
118
119
[Request and Response Model](./http-messages.md)
120
121
### Service Discovery
122
123
ServiceLoader-based SPI interfaces that enable automatic discovery and instantiation of HTTP client implementations on the classpath. Follows standard Java service provider patterns.
124
125
```java { .api }
126
@SdkPublicApi
127
public interface SdkHttpService {
128
SdkHttpClient.Builder createHttpClientBuilder();
129
}
130
131
@SdkPublicApi
132
public interface SdkAsyncHttpService {
133
SdkAsyncHttpClient.Builder createAsyncHttpClientFactory();
134
}
135
```
136
137
[Service Discovery](./service-discovery.md)
138
139
### Content Streaming
140
141
Flexible content stream providers and reactive streams publishers for handling HTTP request and response bodies. Supports various input sources and asynchronous streaming patterns.
142
143
```java { .api }
144
@FunctionalInterface
145
public interface ContentStreamProvider {
146
InputStream newStream();
147
default String name() { return "Unknown"; }
148
149
static ContentStreamProvider fromByteArray(byte[] bytes);
150
static ContentStreamProvider fromByteArrayUnsafe(byte[] bytes);
151
static ContentStreamProvider fromString(String string, Charset charset);
152
static ContentStreamProvider fromUtf8String(String string);
153
static ContentStreamProvider fromInputStream(InputStream inputStream);
154
static ContentStreamProvider fromInputStreamSupplier(Supplier<InputStream> inputStreamSupplier);
155
}
156
157
public interface SdkHttpContentPublisher extends Publisher<ByteBuffer> {
158
Optional<Long> contentLength();
159
}
160
```
161
162
[Content Streaming](./content-streaming.md)
163
164
### TLS and SSL Configuration
165
166
Comprehensive TLS/SSL configuration providers for client authentication and server certificate validation. Includes file-based and system property-based key manager providers.
167
168
```java { .api }
169
@FunctionalInterface
170
public interface TlsKeyManagersProvider {
171
KeyManager[] keyManagers();
172
static TlsKeyManagersProvider noneProvider();
173
}
174
175
@FunctionalInterface
176
public interface TlsTrustManagersProvider {
177
TrustManager[] trustManagers();
178
}
179
```
180
181
[TLS and SSL Configuration](./tls-configuration.md)
182
183
### Metrics and Monitoring
184
185
Built-in metrics collection capabilities for HTTP client implementations. Provides standardized metrics for HTTP/1.1 and HTTP/2 operations including connection pooling and performance monitoring.
186
187
```java { .api }
188
public final class HttpMetric {
189
public static final SdkMetric<String> HTTP_CLIENT_NAME;
190
public static final SdkMetric<Integer> MAX_CONCURRENCY;
191
public static final SdkMetric<Integer> AVAILABLE_CONCURRENCY;
192
public static final SdkMetric<Duration> CONCURRENCY_ACQUIRE_DURATION;
193
}
194
195
public final class Http2Metric {
196
public static final SdkMetric<Integer> LOCAL_STREAM_WINDOW_SIZE_IN_BYTES;
197
public static final SdkMetric<Integer> REMOTE_STREAM_WINDOW_SIZE_IN_BYTES;
198
}
199
```
200
201
[Metrics and Monitoring](./metrics.md)
202
203
### Execution Attributes
204
205
Type-safe configuration attributes for HTTP request execution. Provides a mechanism to attach metadata and configuration to HTTP requests in a type-safe manner.
206
207
```java { .api }
208
@SdkPublicApi
209
public abstract class SdkHttpExecutionAttribute<T> extends AttributeMap.Key<T> {
210
protected SdkHttpExecutionAttribute(Class<T> valueType);
211
protected SdkHttpExecutionAttribute(UnsafeValueType unsafeValueType);
212
}
213
214
@SdkPublicApi
215
public final class SdkHttpExecutionAttributes
216
implements ToCopyableBuilder<SdkHttpExecutionAttributes.Builder, SdkHttpExecutionAttributes> {
217
218
public <T> T getAttribute(SdkHttpExecutionAttribute<T> attribute);
219
public static Builder builder();
220
public Builder toBuilder();
221
222
public static final class Builder {
223
public <T> Builder put(SdkHttpExecutionAttribute<T> key, T value);
224
public Builder putAll(Map<? extends SdkHttpExecutionAttribute<?>, ?> attributes);
225
public SdkHttpExecutionAttributes build();
226
}
227
}
228
```
229
230
## Core Types
231
232
```java { .api }
233
@SdkPublicApi
234
public enum ProtocolNegotiation {
235
/** Uses prior knowledge */
236
ASSUME_PROTOCOL,
237
238
/** Uses Application Level Protocol Negotiation */
239
ALPN
240
}
241
242
@SdkPublicApi
243
public final class SdkCancellationException extends RuntimeException {
244
public SdkCancellationException(String message);
245
}
246
```