0
# Proxy Configuration
1

2
Comprehensive proxy support with automatic system property and environment variable integration for enterprise environments. Supports HTTP and HTTPS proxies with authentication and host exclusions.
3

4
## Capabilities
5

6
### ProxyConfiguration
7

8
Configuration class for HTTP/HTTPS proxy settings including host, port, credentials, and non-proxy hosts. Supports automatic resolution from system properties and environment variables.
9

10
```java { .api }
11
/**
12
 * ProxyConfiguration provides HTTP and HTTPS proxy settings with automatic system integration.
13
 * Supports authentication, host exclusions, and fallback to system properties and environment variables.
14
 */
15
public final class ProxyConfiguration implements ToCopyableBuilder<ProxyConfiguration.Builder, ProxyConfiguration> {
16
    /**
17
     * Returns the proxy scheme (http or https)
18
     * @return proxy scheme
19
     */
20
    public String scheme();
21
    
22
    /**
23
     * Returns the proxy host from configuration, system properties, or environment variables
24
     * Checks: configured value -> system properties -> environment variables
25
     * @return proxy host name or IP address
26
     */
27
    public String host();
28
    
29
    /**
30
     * Returns the proxy port from configuration, system properties, or environment variables
31
     * Checks: configured value -> system properties -> environment variables
32
     * @return proxy port number
33
     */
34
    public int port();
35
    
36
    /**
37
     * Returns the proxy username from configuration, system properties, or environment variables
38
     * @return proxy username for authentication (null if not configured)
39
     */
40
    public String username();
41
    
42
    /**
43
     * Returns the proxy password from configuration, system properties, or environment variables
44
     * @return proxy password for authentication (null if not configured)
45
     */
46
    public String password();
47
    
48
    /**
49
     * Returns hosts that should bypass the proxy
50
     * @return unmodifiable set of hosts to exclude from proxy
51
     */
52
    public Set<String> nonProxyHosts();
53
    
54
    /**
55
     * Creates a new builder from this configuration
56
     * @return builder initialized with current values
57
     */
58
    public Builder toBuilder();
59
    
60
    /**
61
     * Creates a new builder instance
62
     * @return new Builder for proxy configuration
63
     */
64
    public static Builder builder();
65
    
66
    /**
67
     * Standard equals implementation
68
     */
69
    public boolean equals(Object obj);
70
    
71
    /**
72
     * Standard hashCode implementation
73
     */
74
    public int hashCode();
75
}
76
```
77

78
**Usage Examples:**
79

80
```java
81
import software.amazon.awssdk.http.nio.netty.ProxyConfiguration;
82
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
83

84
// Basic proxy configuration
85
ProxyConfiguration proxyConfig = ProxyConfiguration.builder()
86
    .scheme("http")
87
    .host("proxy.company.com")
88
    .port(8080)
89
    .build();
90

91
// Proxy with authentication
92
ProxyConfiguration proxyConfig = ProxyConfiguration.builder()
93
    .scheme("http")
94
    .host("proxy.company.com")
95
    .port(8080)
96
    .username("myuser")
97
    .password("mypassword")
98
    .build();
99

100
// Use with HTTP client
101
NettyNioAsyncHttpClient client = NettyNioAsyncHttpClient.builder()
102
    .proxyConfiguration(proxyConfig)
103
    .build();
104
```
105

106
### ProxyConfiguration Builder
107

108
Builder interface for configuring proxy settings with support for system property and environment variable fallbacks.
109

110
```java { .api }
111
/**
112
 * Builder for configuring proxy settings with system integration
113
 */
114
public interface Builder extends CopyableBuilder<Builder, ProxyConfiguration> {
115
    /**
116
     * Sets the proxy host name or IP address
117
     * @param host proxy host
118
     * @return this builder for method chaining
119
     */
120
    Builder host(String host);
121
    
122
    /**
123
     * Sets the proxy port number
124
     * @param port proxy port (typically 8080, 3128, or 80/443)
125
     * @return this builder for method chaining
126
     */
127
    Builder port(int port);
128
    
129
    /**
130
     * Sets the proxy scheme (http or https)
131
     * @param scheme "http" or "https" (default: "http")
132
     * @return this builder for method chaining
133
     */
134
    Builder scheme(String scheme);
135
    
136
    /**
137
     * Sets hosts that should bypass the proxy.
138
     * Supports wildcards and patterns for flexible host matching.
139
     * @param nonProxyHosts set of hosts to exclude from proxy
140
     * @return this builder for method chaining
141
     */
142
    Builder nonProxyHosts(Set<String> nonProxyHosts);
143
    
144
    /**
145
     * Sets the proxy username for authentication
146
     * @param username proxy username
147
     * @return this builder for method chaining
148
     */
149
    Builder username(String username);
150
    
151
    /**
152
     * Sets the proxy password for authentication
153
     * @param password proxy password
154
     * @return this builder for method chaining
155
     */
156
    Builder password(String password);
157
    
158
    /**
159
     * Enables or disables fallback to system properties for proxy configuration.
160
     * When enabled, checks standard Java system properties like http.proxyHost.
161
     * @param useSystemPropertyValues true to enable system property fallback (default: true)
162
     * @return this builder for method chaining
163
     */
164
    Builder useSystemPropertyValues(Boolean useSystemPropertyValues);
165
    
166
    /**
167
     * Enables or disables fallback to environment variables for proxy configuration.
168
     * When enabled, checks environment variables like HTTP_PROXY, HTTPS_PROXY.
169
     * @param useEnvironmentVariableValues true to enable environment variable fallback (default: false)
170
     * @return this builder for method chaining
171
     */
172
    Builder useEnvironmentVariableValues(Boolean useEnvironmentVariableValues);
173
    
174
    /**
175
     * Builds the proxy configuration instance
176
     * @return configured ProxyConfiguration
177
     */
178
    ProxyConfiguration build();
179
}
180
```
181

182
**Configuration Examples:**
183

184
```java
185
// Enterprise proxy with exclusions
186
Set<String> nonProxyHosts = Set.of(
187
    "localhost",
188
    "127.0.0.1", 
189
    "*.internal.company.com",
190
    "*.amazonaws.com"
191
);
192

193
ProxyConfiguration enterpriseProxy = ProxyConfiguration.builder()
194
    .scheme("http")
195
    .host("corporate-proxy.company.com")
196
    .port(8080)
197
    .username("domain\\username")
198
    .password("password")
199
    .nonProxyHosts(nonProxyHosts)
200
    .useSystemPropertyValues(true)
201
    .build();
202

203
// Automatic system property resolution
204
ProxyConfiguration systemProxy = ProxyConfiguration.builder()
205
    .useSystemPropertyValues(true)        // Use http.proxyHost, http.proxyPort, etc.
206
    .useEnvironmentVariableValues(false)
207
    .build();
208

209
// Environment variable resolution (common in containers)
210
ProxyConfiguration envProxy = ProxyConfiguration.builder()
211
    .useSystemPropertyValues(false)
212
    .useEnvironmentVariableValues(true)   // Use HTTP_PROXY, HTTPS_PROXY, NO_PROXY
213
    .build();
214

215
// Hybrid approach - explicit config with fallbacks
216
ProxyConfiguration hybridProxy = ProxyConfiguration.builder()
217
    .host("primary-proxy.com")
218
    .port(8080)
219
    .useSystemPropertyValues(true)        // Fallback to system properties
220
    .useEnvironmentVariableValues(true)   // Fallback to environment variables
221
    .build();
222
```
223

224
## System Integration
225

226
### System Properties
227

228
The proxy configuration integrates with standard Java system properties:
229

230
```java
231
// System properties checked when useSystemPropertyValues(true)
232
System.setProperty("http.proxyHost", "proxy.company.com");
233
System.setProperty("http.proxyPort", "8080");
234
System.setProperty("http.proxyUser", "username");
235
System.setProperty("http.proxyPassword", "password");
236
System.setProperty("http.nonProxyHosts", "localhost|127.0.0.1|*.internal.com");
237

238
// HTTPS proxy properties
239
System.setProperty("https.proxyHost", "secure-proxy.company.com");
240
System.setProperty("https.proxyPort", "8443");
241
System.setProperty("https.proxyUser", "username");
242
System.setProperty("https.proxyPassword", "password");
243

244
// Configuration will automatically use these values
245
ProxyConfiguration config = ProxyConfiguration.builder()
246
    .useSystemPropertyValues(true)
247
    .build();
248
```
249

250
### Environment Variables
251

252
Support for container and cloud-native proxy configurations:
253

254
```bash
255
# Environment variables checked when useEnvironmentVariableValues(true)
256
export HTTP_PROXY=http://proxy.company.com:8080
257
export HTTPS_PROXY=http://secure-proxy.company.com:8443
258
export NO_PROXY=localhost,127.0.0.1,*.internal.com
259

260
# With authentication
261
export HTTP_PROXY=http://username:password@proxy.company.com:8080
262
export HTTPS_PROXY=http://username:password@secure-proxy.company.com:8443
263
```
264

265
```java
266
// Configuration will automatically parse environment variables
267
ProxyConfiguration config = ProxyConfiguration.builder()
268
    .useEnvironmentVariableValues(true)
269
    .build();
270
```
271

272
### Precedence Order
273

274
Configuration values are resolved in this order (first found wins):
275

276
1. **Explicitly configured values** (via builder methods)
277
2. **System properties** (if `useSystemPropertyValues(true)`)
278
3. **Environment variables** (if `useEnvironmentVariableValues(true)`)
279
4. **Default values** (where applicable)
280

281
```java
282
// Example showing precedence
283
ProxyConfiguration config = ProxyConfiguration.builder()
284
    .host("explicit-proxy.com")           // 1. Explicit value wins
285
    .useSystemPropertyValues(true)        // 2. Fallback to system properties
286
    .useEnvironmentVariableValues(true)   // 3. Fallback to environment variables
287
    .build();
288

289
// Even if HTTP_PROXY is set, explicit host takes precedence
290
```
291

292
## Host Exclusion Patterns
293

294
### Non-Proxy Hosts
295

296
The `nonProxyHosts` setting supports various patterns for excluding hosts from proxy:
297

298
```java
299
Set<String> exclusions = Set.of(
300
    "localhost",                    // Exact match
301
    "127.0.0.1",                   // IP address
302
    "*.internal.company.com",      // Wildcard subdomain
303
    "*.amazonaws.com",             // AWS services
304
    "10.*",                        // IP range pattern
305
    "192.168.*"                    // Private network ranges
306
);
307

308
ProxyConfiguration config = ProxyConfiguration.builder()
309
    .host("proxy.company.com")
310
    .port(8080)
311
    .nonProxyHosts(exclusions)
312
    .build();
313
```
314

315
### Pattern Matching
316

317
Host exclusion supports shell-style patterns:
318

319
- `*` matches any sequence of characters
320
- `?` matches any single character
321
- Character classes like `[a-z]` are not supported
322
- Case-insensitive matching
323

324
```java
325
// Common exclusion patterns
326
Set<String> patterns = Set.of(
327
    "*.local",                     // All .local domains
328
    "*.localhost",                 // All localhost variants
329
    "10.*",                        // All 10.x.x.x addresses
330
    "192.168.*",                   // All 192.168.x.x addresses
331
    "*internal*",                  // Any host containing "internal"
332
    "test-*"                       // Any host starting with "test-"
333
);
334
```
335

336
## Integration with HTTP Client
337

338
### Basic Proxy Setup
339

340
```java
341
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
342
import software.amazon.awssdk.http.nio.netty.ProxyConfiguration;
343

344
// Configure proxy for all requests
345
ProxyConfiguration proxyConfig = ProxyConfiguration.builder()
346
    .scheme("http")
347
    .host("proxy.company.com")
348
    .port(8080)
349
    .username("user")
350
    .password("pass")
351
    .build();
352

353
NettyNioAsyncHttpClient client = NettyNioAsyncHttpClient.builder()
354
    .proxyConfiguration(proxyConfig)
355
    .build();
356

357
// Use with AWS services
358
S3AsyncClient s3 = S3AsyncClient.builder()
359
    .httpClient(client)
360
    .build();
361
```
362

363
### Advanced Enterprise Setup
364

365
```java
366
// Enterprise configuration with comprehensive settings
367
Set<String> nonProxyHosts = Set.of(
368
    "localhost", "127.0.0.1", "::1",
369
    "*.internal.company.com",
370
    "*.amazonaws.com", 
371
    "*.s3.*.amazonaws.com",
372
    "10.*", "192.168.*", "172.16.*"
373
);
374

375
ProxyConfiguration enterpriseConfig = ProxyConfiguration.builder()
376
    .scheme("http")
377
    .host("corporate-proxy.company.com")
378
    .port(8080)
379
    .username(System.getProperty("proxy.username"))
380
    .password(System.getProperty("proxy.password"))
381
    .nonProxyHosts(nonProxyHosts)
382
    .useSystemPropertyValues(true)        // Corporate system properties
383
    .useEnvironmentVariableValues(false)  // Disable for security
384
    .build();
385

386
NettyNioAsyncHttpClient client = NettyNioAsyncHttpClient.builder()
387
    .proxyConfiguration(enterpriseConfig)
388
    .connectionTimeout(Duration.ofSeconds(30))  // Longer timeout through proxy
389
    .readTimeout(Duration.ofMinutes(2))
390
    .build();
391
```
392

393
## Types
394

395
### Proxy Configuration Types
396

397
```java { .api }
398
interface ToCopyableBuilder<B extends CopyableBuilder<B, T>, T> {
399
    B toBuilder();
400
}
401

402
interface CopyableBuilder<B extends CopyableBuilder<B, T>, T> {
403
    T build();
404
}
405

406
// Standard Java collections for host exclusions
407
interface Set<E> extends Collection<E> {
408
    boolean contains(Object o);
409
    int size();
410
    boolean isEmpty();
411
}
412
```
413

414
### System Integration Types
415

416
```java { .api }
417
// System property access
418
class System {
419
    static String getProperty(String key);
420
    static String getProperty(String key, String def);
421
    static void setProperty(String key, String value);
422
}
423

424
// Environment variable access
425
class System {
426
    static Map<String, String> getenv();
427
    static String getenv(String name);
428
}
429
```
430

431
## Security Considerations
432

433
### Credential Handling
434

435
- Proxy passwords are stored in memory as strings (not secured)
436
- Consider using system properties or environment variables for credentials
437
- Avoid hardcoding credentials in source code
438
- Use secure credential management systems in production
439

440
### Network Security
441

442
- Proxy connections may be monitored by network administrators
443
- HTTPS traffic through HTTP proxies uses CONNECT tunneling
444
- Consider using HTTPS proxies for sensitive applications
445
- Validate proxy certificates when using HTTPS proxies