0
# Proxy Configuration
1

2
This document covers HTTP proxy configuration for the UrlConnectionHttpClient, including authentication, host exclusion, and system property integration.
3

4
## ProxyConfiguration Class
5

6
```java { .api }
7
public final class ProxyConfiguration implements ToCopyableBuilder<ProxyConfiguration.Builder, ProxyConfiguration> {
8
    // Static factory
9
    public static Builder builder();
10
    
11
    // Configuration accessors
12
    public String host();
13
    public int port();
14
    public String scheme();
15
    public String username();
16
    public String password();
17
    public Set<String> nonProxyHosts();
18
    
19
    // Builder conversion
20
    public Builder toBuilder();
21
}
22
```
23

24
## Basic Proxy Setup
25

26
### Simple Proxy Configuration
27

28
```java
29
import software.amazon.awssdk.http.urlconnection.ProxyConfiguration;
30
import java.net.URI;
31

32
ProxyConfiguration proxy = ProxyConfiguration.builder()
33
    .endpoint(URI.create("http://proxy.example.com:8080"))
34
    .build();
35

36
SdkHttpClient client = UrlConnectionHttpClient.builder()
37
    .proxyConfiguration(proxy)
38
    .build();
39
```
40

41
### Proxy with Authentication
42

43
```java
44
ProxyConfiguration proxy = ProxyConfiguration.builder()
45
    .endpoint(URI.create("http://proxy.example.com:8080"))
46
    .username("proxyuser")
47
    .password("proxypassword")
48
    .build();
49
```
50

51
### HTTPS Proxy
52

53
```java
54
ProxyConfiguration proxy = ProxyConfiguration.builder()
55
    .endpoint(URI.create("https://secure-proxy.example.com:8443"))
56
    .username("user")
57
    .password("pass")
58
    .build();
59
```
60

61
## Advanced Proxy Configuration
62

63
### Host Exclusion (Non-Proxy Hosts)
64

65
```java
66
import java.util.Set;
67

68
ProxyConfiguration proxy = ProxyConfiguration.builder()
69
    .endpoint(URI.create("http://proxy.example.com:8080"))
70
    .nonProxyHosts(Set.of("localhost", "*.internal.com", "192.168.*"))
71
    .build();
72

73
// Or add hosts individually
74
ProxyConfiguration proxy2 = ProxyConfiguration.builder()
75
    .endpoint(URI.create("http://proxy.example.com:8080"))
76
    .addNonProxyHost("localhost")
77
    .addNonProxyHost("*.internal.com")
78
    .addNonProxyHost("10.0.0.*")
79
    .build();
80
```
81

82
### System Property Integration
83

84
```java
85
// Use system properties (http.proxyHost, http.proxyPort, etc.)
86
ProxyConfiguration proxy = ProxyConfiguration.builder()
87
    .useSystemPropertyValues(true)
88
    .build();
89

90
// Use environment variables (HTTP_PROXY, NO_PROXY, etc.)
91
ProxyConfiguration proxy2 = ProxyConfiguration.builder()
92
    .useEnvironmentVariablesValues(true)
93
    .build();
94

95
// Disable both system properties and environment variables
96
ProxyConfiguration proxy3 = ProxyConfiguration.builder()
97
    .endpoint(URI.create("http://proxy.example.com:8080"))
98
    .useSystemPropertyValues(false)
99
    .useEnvironmentVariablesValues(false)
100
    .build();
101
```
102

103
## ProxyConfiguration.Builder
104

105
```java { .api }
106
public interface Builder extends CopyableBuilder<Builder, ProxyConfiguration> {
107
    // Basic configuration
108
    Builder endpoint(URI endpoint);
109
    Builder username(String username);
110
    Builder password(String password);
111
    Builder scheme(String scheme);
112
    
113
    // Host exclusion
114
    Builder nonProxyHosts(Set<String> nonProxyHosts);
115
    Builder addNonProxyHost(String nonProxyHost);
116
    
117
    // System integration
118
    Builder useSystemPropertyValues(Boolean useSystemPropertyValues);
119
    Builder useEnvironmentVariablesValues(Boolean useEnvironmentVariablesValues);
120
    
121
    // Build
122
    ProxyConfiguration build();
123
}
124
```
125

126
### Builder Usage Examples
127

128
```java
129
// Complete proxy configuration
130
ProxyConfiguration proxy = ProxyConfiguration.builder()
131
    .endpoint(URI.create("http://corporate-proxy.example.com:3128"))
132
    .username("domain\\user")  // Windows domain authentication
133
    .password("password123")
134
    .nonProxyHosts(Set.of("localhost", "127.0.0.1", "*.internal.corp"))
135
    .useSystemPropertyValues(false)  // Don't override with system properties
136
    .build();
137

138
// Consumer-style configuration with HTTP client
139
SdkHttpClient client = UrlConnectionHttpClient.builder()
140
    .proxyConfiguration(proxy -> proxy
141
        .endpoint(URI.create("http://proxy.example.com:8080"))
142
        .username("user")
143
        .password("pass")
144
        .addNonProxyHost("localhost")
145
        .addNonProxyHost("*.test.com"))
146
    .build();
147
```
148

149
## System Property Support
150

151
When `useSystemPropertyValues(true)` is set (default), the following system properties are used:
152

153
- `http.proxyHost` - Proxy hostname
154
- `http.proxyPort` - Proxy port (default 80)
155
- `http.proxyUser` - Proxy username
156
- `http.proxyPassword` - Proxy password
157
- `http.nonProxyHosts` - Pipe-separated list of hosts to bypass proxy
158

159
```java
160
// System properties will be automatically used
161
System.setProperty("http.proxyHost", "proxy.company.com");
162
System.setProperty("http.proxyPort", "8080");
163
System.setProperty("http.proxyUser", "username");
164
System.setProperty("http.proxyPassword", "password");
165
System.setProperty("http.nonProxyHosts", "localhost|*.internal.com");
166

167
ProxyConfiguration proxy = ProxyConfiguration.builder()
168
    .useSystemPropertyValues(true)
169
    .build();
170
```
171

172
## Environment Variable Support
173

174
When `useEnvironmentVariablesValues(true)` is set (default), the following environment variables are used:
175

176
- `HTTP_PROXY` or `http_proxy` - Proxy URL (e.g., `http://proxy.example.com:8080`)
177
- `HTTPS_PROXY` or `https_proxy` - HTTPS proxy URL
178
- `NO_PROXY` or `no_proxy` - Comma-separated list of hosts to bypass proxy
179

180
```bash
181
export HTTP_PROXY=http://proxy.example.com:8080
182
export NO_PROXY=localhost,*.internal.com,192.168.*
183
```
184

185
```java
186
ProxyConfiguration proxy = ProxyConfiguration.builder()
187
    .useEnvironmentVariablesValues(true)
188
    .build();
189
```
190

191
## Configuration Priority
192

193
When both system properties and environment variables are enabled:
194
1. Explicit builder values take precedence
195
2. System properties override environment variables
196
3. Environment variables are used as fallback
197

198
## Usage Examples
199

200
### Corporate Environment
201

202
```java
203
// Typical corporate proxy setup
204
ProxyConfiguration corpProxy = ProxyConfiguration.builder()
205
    .endpoint(URI.create("http://proxy.corporate.com:8080"))
206
    .username("DOMAIN\\username")
207
    .password("password")
208
    .nonProxyHosts(Set.of(
209
        "localhost",
210
        "127.0.0.1", 
211
        "*.corporate.com",
212
        "*.internal",
213
        "10.*",
214
        "192.168.*"
215
    ))
216
    .build();
217

218
SdkHttpClient client = UrlConnectionHttpClient.builder()
219
    .proxyConfiguration(corpProxy)
220
    .connectionTimeout(Duration.ofSeconds(30))
221
    .build();
222
```
223

224
### Development Environment
225

226
```java
227
// Development with system property fallback
228
ProxyConfiguration devProxy = ProxyConfiguration.builder()
229
    .useSystemPropertyValues(true)
230
    .useEnvironmentVariablesValues(true)
231
    .addNonProxyHost("localhost")
232
    .addNonProxyHost("*.test")
233
    .build();
234
```
235

236
### No Proxy
237

238
```java
239
// Explicitly disable proxy
240
ProxyConfiguration noProxy = ProxyConfiguration.builder()
241
    .useSystemPropertyValues(false)
242
    .useEnvironmentVariablesValues(false)
243
    .build();
244
```
245

246
## Types
247

248
```java { .api }
249
// Main proxy configuration class
250
public final class ProxyConfiguration implements ToCopyableBuilder<ProxyConfiguration.Builder, ProxyConfiguration> {
251
    public String host();
252
    public int port();
253
    public String scheme();
254
    public String username();
255
    public String password();
256
    public Set<String> nonProxyHosts();
257
    public String resolveScheme();  // Resolves scheme from endpoint if available
258
    public Builder toBuilder();
259
    public static Builder builder();
260
}
261

262
// Builder interface
263
public interface Builder extends CopyableBuilder<Builder, ProxyConfiguration> {
264
    // Fluent builder methods
265
    Builder endpoint(URI endpoint);
266
    Builder username(String username);
267
    Builder password(String password);
268
    Builder nonProxyHosts(Set<String> nonProxyHosts);
269
    Builder addNonProxyHost(String nonProxyHost);
270
    Builder useSystemPropertyValues(Boolean useSystemPropertyValues);
271
    Builder useEnvironmentVariablesValues(Boolean useEnvironmentVariablesValues);
272
    Builder scheme(String scheme);
273
    
274
    // JavaBean setter methods (for framework integration)
275
    void setEndpoint(URI endpoint);
276
    void setUsername(String username);
277
    void setPassword(String password);
278
    void setNonProxyHosts(Set<String> nonProxyHosts);
279
    void setUseSystemPropertyValues(Boolean useSystemPropertyValues);
280
    void setUseEnvironmentVariablesValues(Boolean useEnvironmentVariablesValues);
281
    void setScheme(String scheme);
282
    
283
    // Build method
284
    ProxyConfiguration build();
285
}
286
```