0
# Connection Management
1

2
Advanced connection handling including custom connections, connection caching, proxy support, TLS configuration, and DNS resolution strategies.
3

4
## Capabilities
5

6
### Client Connection Interface
7

8
Abstraction for client network connections enabling custom connections for testing and advanced use cases.
9

10
```java { .api }
11
/**
12
 * Get data reader for reading responses
13
 * @return data reader instance
14
 */
15
DataReader reader();
16

17
/**
18
 * Get data writer for writing requests
19
 * @return data writer instance
20
 */
21
DataWriter writer();
22

23
/**
24
 * Get connection identifier
25
 * @return unique connection identifier
26
 */
27
String channelId();
28

29
/**
30
 * Get underlying socket
31
 * @return Helidon socket instance
32
 */
33
HelidonSocket helidonSocket();
34

35
/**
36
 * Configure read timeout for this connection
37
 * @param readTimeout timeout duration
38
 */
39
void readTimeout(Duration readTimeout);
40

41
/**
42
 * Check if connection supports Expect: 100-Continue
43
 * @return true if 100-Continue is supported
44
 */
45
default boolean allowExpectContinue();
46

47
/**
48
 * Configure Expect: 100-Continue support
49
 * @param allowExpectContinue true to enable support
50
 */
51
default void allowExpectContinue(boolean allowExpectContinue);
52

53
/**
54
 * Release/close the connection
55
 */
56
default void closeResource();
57
```
58

59
**Usage Examples:**
60

61
```java
62
import io.helidon.webclient.api.ClientConnection;
63
import io.helidon.webclient.api.TcpClientConnection;
64

65
// Use explicit connection for request
66
ClientConnection connection = TcpClientConnection.create(
67
    socketAddress, tls, socketOptions, dnsResolver, proxy);
68

69
String response = client.get("/api/data")
70
    .connection(connection)
71
    .requestEntity(String.class);
72

73
// Connection will be reused for subsequent requests using the same connection
74
```
75

76
### TCP Client Connection
77

78
Concrete implementation of ClientConnection for TCP-based protocols.
79

80
```java { .api }
81
/**
82
 * Create TCP client connection
83
 * @param socketAddress target socket address
84
 * @param tls TLS configuration
85
 * @param socketOptions socket options
86
 * @param dnsResolver DNS resolver
87
 * @param proxy proxy configuration
88
 * @return new TCP connection
89
 */
90
static TcpClientConnection create(
91
    InetSocketAddress socketAddress,
92
    Tls tls,
93
    SocketOptions socketOptions,
94
    DnsResolver dnsResolver,
95
    Optional<Proxy> proxy);
96

97
/**
98
 * Create TCP client connection with additional parameters
99
 * @param webClient associated web client
100
 * @param socketAddress target socket address
101
 * @param socketOptions socket options
102
 * @param tls TLS configuration
103
 * @param dnsResolver DNS resolver
104
 * @param proxy proxy configuration
105
 * @return new TCP connection
106
 */
107
static TcpClientConnection create(
108
    WebClient webClient,
109
    InetSocketAddress socketAddress,
110
    SocketOptions socketOptions,
111
    Tls tls,
112
    DnsResolver dnsResolver,
113
    Optional<Proxy> proxy);
114
```
115

116
### Connection Caching
117

118
Intelligent connection pooling and caching with configurable strategies to improve performance.
119

120
```java { .api }
121
/**
122
 * Interface for connection caching implementations
123
 */
124
public interface ClientConnectionCache {
125
    /**
126
     * Get cached connection for key
127
     * @param key connection key
128
     * @return cached connection if available
129
     */
130
    Optional<ClientConnection> connection(ConnectionKey key);
131
    
132
    /**
133
     * Create and cache new connection
134
     * @param key connection key
135
     * @param connectionSupplier supplier to create connection
136
     * @return new cached connection
137
     */
138
    ClientConnection newConnection(ConnectionKey key, Supplier<ClientConnection> connectionSupplier);
139
}
140

141
/**
142
 * Key for connection caching based on target and configuration
143
 */
144
public record ConnectionKey(
145
    String host,
146
    int port,
147
    boolean tls,
148
    DnsAddressLookup dnsAddressLookup,
149
    Optional<Proxy> proxy
150
) {
151
    // Connection caching key
152
}
153
```
154

155
**Configuration Examples:**
156

157
```java
158
// Configure connection caching
159
WebClient client = WebClient.builder()
160
    .connectionCacheSize(50)  // Maximum cached connections
161
    .shareConnectionCache(true)  // Share cache across client instances
162
    .build();
163
```
164

165
### DNS Resolution
166

167
Pluggable DNS resolution with multiple strategies for handling hostname resolution.
168

169
```java { .api }
170
/**
171
 * Strategy for DNS address lookup
172
 */
173
public interface DnsAddressLookup {
174
    /**
175
     * Resolve hostname to IP addresses
176
     * @param hostname hostname to resolve
177
     * @return list of resolved IP addresses
178
     */
179
    List<InetAddress> listAddresses(String hostname);
180
    
181
    /**
182
     * Default Java DNS lookup
183
     * @return default lookup implementation
184
     */
185
    static DnsAddressLookup defaultLookup();
186
    
187
    /**
188
     * Return only first resolved address
189
     * @return first-address lookup implementation
190
     */
191
    static DnsAddressLookup firstAddress();
192
    
193
    /**
194
     * Round-robin through resolved addresses
195
     * @return round-robin lookup implementation
196
     */
197
    static DnsAddressLookup roundRobin();
198
}
199

200
/**
201
 * DNS resolution strategy interface
202
 */
203
public interface DnsResolver {
204
    /**
205
     * Get address lookup implementation
206
     * @return address lookup instance
207
     */
208
    DnsAddressLookup addressLookup();
209
}
210
```
211

212
**Usage Examples:**
213

214
```java
215
import io.helidon.webclient.api.DnsAddressLookup;
216

217
// Configure DNS resolution strategy
218
WebClient client = WebClient.builder()
219
    .dnsAddressLookup(DnsAddressLookup.roundRobin())  // Round-robin through IPs
220
    .build();
221

222
// Or use first available address only
223
WebClient client = WebClient.builder()
224
    .dnsAddressLookup(DnsAddressLookup.firstAddress())
225
    .build();
226

227
// Custom DNS resolution
228
WebClient client = WebClient.builder()
229
    .dnsResolver(customDnsResolver)
230
    .build();
231
```
232

233
### Proxy Configuration
234

235
Comprehensive proxy support including HTTP proxies, system proxies, and no-proxy patterns.
236

237
```java { .api }
238
/**
239
 * Create proxy configuration builder
240
 * @return new proxy builder
241
 */
242
static Proxy.Builder builder();
243

244
/**
245
 * No-proxy instance (disables proxy usage)
246
 * @return no-proxy configuration
247
 */
248
static Proxy noProxy();
249

250
/**
251
 * Create proxy from system properties
252
 * @return proxy configuration from system settings
253
 */
254
static Proxy create();
255

256
/**
257
 * Create proxy from configuration
258
 * @param config configuration instance
259
 * @return proxy configuration
260
 */
261
static Proxy create(Config config);
262

263
/**
264
 * Create proxied socket
265
 * @param webClient associated web client
266
 * @param inetSocketAddress target address
267
 * @param socketOptions socket options
268
 * @param tls whether connection uses TLS
269
 * @return proxied socket
270
 */
271
Socket tcpSocket(WebClient webClient, InetSocketAddress inetSocketAddress, 
272
                SocketOptions socketOptions, boolean tls);
273

274
/**
275
 * Get proxy type
276
 * @return proxy type
277
 */
278
ProxyType type();
279

280
/**
281
 * Check if URI bypasses proxy (matches no-proxy patterns)
282
 * @param uri target URI
283
 * @return true if URI should bypass proxy
284
 */
285
boolean isNoHosts(InetSocketAddress uri);
286

287
/**
288
 * Check if using system proxy settings
289
 * @param uri target URI
290
 * @return true if using system proxy
291
 */
292
boolean isUsingSystemProxy(String uri);
293

294
/**
295
 * Get proxy host
296
 * @return proxy host
297
 */
298
String host();
299

300
/**
301
 * Get proxy port
302
 * @return proxy port
303
 */
304
int port();
305

306
/**
307
 * Get proxy username
308
 * @return username for proxy authentication
309
 */
310
Optional<String> username();
311

312
/**
313
 * Get proxy password
314
 * @return password for proxy authentication
315
 */
316
Optional<char[]> password();
317
```
318

319
**Proxy Builder:**
320

321
```java { .api }
322
public static class Builder {
323
    /**
324
     * Set proxy type
325
     * @param type proxy type
326
     * @return builder instance
327
     */
328
    Builder type(ProxyType type);
329
    
330
    /**
331
     * Set proxy host
332
     * @param host proxy host
333
     * @return builder instance
334
     */
335
    Builder host(String host);
336
    
337
    /**
338
     * Set proxy port
339
     * @param port proxy port
340
     * @return builder instance
341
     */
342
    Builder port(int port);
343
    
344
    /**
345
     * Set proxy username
346
     * @param username username for authentication
347
     * @return builder instance
348
     */
349
    Builder username(String username);
350
    
351
    /**
352
     * Set proxy password
353
     * @param password password for authentication
354
     * @return builder instance
355
     */
356
    Builder password(char[] password);
357
    
358
    /**
359
     * Add no-proxy host pattern
360
     * @param noHost host pattern to bypass proxy
361
     * @return builder instance
362
     */
363
    Builder addNoHost(String noHost);
364
    
365
    /**
366
     * Build proxy configuration
367
     * @return proxy instance
368
     */
369
    Proxy build();
370
}
371

372
/**
373
 * Proxy types
374
 */
375
public enum ProxyType {
376
    NONE,    // No proxy
377
    SYSTEM,  // Use system proxy settings
378
    HTTP     // HTTP proxy
379
}
380
```
381

382
**Usage Examples:**
383

384
```java
385
import io.helidon.webclient.api.Proxy;
386
import io.helidon.webclient.api.Proxy.ProxyType;
387

388
// HTTP proxy with authentication
389
WebClient client = WebClient.builder()
390
    .proxy(Proxy.builder()
391
        .type(ProxyType.HTTP)
392
        .host("proxy.example.com")
393
        .port(8080)
394
        .username("user")
395
        .password("pass".toCharArray())
396
        .addNoHost("localhost")
397
        .addNoHost("*.internal.com")
398
        .build())
399
    .build();
400

401
// System proxy (uses http.proxyHost, https.proxyHost system properties)
402
WebClient client = WebClient.builder()
403
    .proxy(Proxy.create())
404
    .build();
405

406
// Disable proxy
407
WebClient client = WebClient.builder()
408
    .proxy(Proxy.noProxy())
409
    .build();
410

411
// Per-request proxy override
412
String response = client.get("/api/data")
413
    .proxy(Proxy.builder()
414
        .type(ProxyType.HTTP)
415
        .host("special-proxy.com")
416
        .port(3128)
417
        .build())
418
    .requestEntity(String.class);
419
```
420

421
### TLS Configuration
422

423
Transport Layer Security configuration for secure connections.
424

425
```java { .api }
426
/**
427
 * Configure TLS for client connections
428
 * @param tls TLS configuration
429
 * @return client configuration builder
430
 */
431
WebClientConfig.Builder tls(Tls tls);
432
```
433

434
**Usage Examples:**
435

436
```java
437
import io.helidon.common.tls.Tls;
438

439
// Configure TLS
440
WebClient client = WebClient.builder()
441
    .tls(Tls.builder()
442
        .trustAll(false)  // Validate certificates
443
        .clientKeyStore(keyStore)
444
        .clientTrustStore(trustStore)
445
        .build())
446
    .build();
447

448
// Per-request TLS override
449
String response = client.get("https://api.example.com/data")
450
    .tls(Tls.builder()
451
        .trustAll(true)  // Accept self-signed certificates
452
        .build())
453
    .requestEntity(String.class);
454
```
455

456
### Socket Configuration
457

458
Low-level socket configuration for network connections.
459

460
```java { .api }
461
/**
462
 * Configure socket options
463
 * @param socketOptions socket configuration
464
 * @return client configuration builder
465
 */
466
WebClientConfig.Builder socketOptions(SocketOptions socketOptions);
467
```
468

469
**Usage Examples:**
470

471
```java
472
import io.helidon.common.socket.SocketOptions;
473

474
WebClient client = WebClient.builder()
475
    .socketOptions(SocketOptions.builder()
476
        .connectTimeout(Duration.ofSeconds(10))
477
        .readTimeout(Duration.ofSeconds(30))
478
        .keepAlive(true)
479
        .tcpNoDelay(true)
480
        .receiveBufferSize(65536)
481
        .sendBufferSize(65536)
482
        .build())
483
    .build();
484
```
485

486
### Connection Resource Management
487

488
Proper resource management for connections and associated resources.
489

490
```java { .api }
491
/**
492
 * Base interface for resources that can be released
493
 */
494
public interface ReleasableResource {
495
    /**
496
     * Release/close the resource
497
     */
498
    default void closeResource();
499
}
500
```
501

502
**Usage Examples:**
503

504
```java
505
// WebClient implements ReleasableResource
506
try (WebClient client = WebClient.create()) {
507
    // Use client for requests
508
    String response = client.get("/api/data").requestEntity(String.class);
509
}  // Client connections are automatically closed
510

511
// Manual connection management
512
ClientConnection connection = TcpClientConnection.create(...);
513
try {
514
    // Use connection
515
    String response = client.get("/api/data")
516
        .connection(connection)
517
        .requestEntity(String.class);
518
} finally {
519
    connection.closeResource();
520
}
521

522
// HTTP responses should be closed for streaming
523
try (HttpClientResponse response = client.get("/large-file").request()) {
524
    try (InputStream inputStream = response.inputStream()) {
525
        // Process stream
526
    }
527
}
528
```
529

530
## Types
531

532
```java { .api }
533
public interface ClientConnection extends ReleasableResource {
534
    DataReader reader();
535
    DataWriter writer();
536
    String channelId();
537
    HelidonSocket helidonSocket();
538
    void readTimeout(Duration readTimeout);
539
    default boolean allowExpectContinue();
540
    default void allowExpectContinue(boolean allowExpectContinue);
541
}
542

543
public class TcpClientConnection implements ClientConnection {
544
    static TcpClientConnection create(InetSocketAddress socketAddress, Tls tls, 
545
                                     SocketOptions socketOptions, DnsResolver dnsResolver, 
546
                                     Optional<Proxy> proxy);
547
    static TcpClientConnection create(WebClient webClient, InetSocketAddress socketAddress,
548
                                     SocketOptions socketOptions, Tls tls, 
549
                                     DnsResolver dnsResolver, Optional<Proxy> proxy);
550
}
551

552
public interface ClientConnectionCache {
553
    Optional<ClientConnection> connection(ConnectionKey key);
554
    ClientConnection newConnection(ConnectionKey key, Supplier<ClientConnection> connectionSupplier);
555
}
556

557
public record ConnectionKey(
558
    String host,
559
    int port,
560
    boolean tls,
561
    DnsAddressLookup dnsAddressLookup,
562
    Optional<Proxy> proxy
563
) {}
564

565
public interface DnsAddressLookup {
566
    List<InetAddress> listAddresses(String hostname);
567
    static DnsAddressLookup defaultLookup();
568
    static DnsAddressLookup firstAddress();
569
    static DnsAddressLookup roundRobin();
570
}
571

572
public interface DnsResolver {
573
    DnsAddressLookup addressLookup();
574
}
575

576
public class Proxy {
577
    static Builder builder();
578
    static Proxy noProxy();
579
    static Proxy create();
580
    static Proxy create(Config config);
581
    
582
    Socket tcpSocket(WebClient webClient, InetSocketAddress inetSocketAddress, 
583
                    SocketOptions socketOptions, boolean tls);
584
    ProxyType type();
585
    boolean isNoHosts(InetSocketAddress uri);
586
    boolean isUsingSystemProxy(String uri);
587
    String host();
588
    int port();
589
    Optional<String> username();
590
    Optional<char[]> password();
591
    
592
    enum ProxyType { NONE, SYSTEM, HTTP }
593
    
594
    static class Builder {
595
        Builder type(ProxyType type);
596
        Builder host(String host);
597
        Builder port(int port);
598
        Builder username(String username);
599
        Builder password(char[] password);
600
        Builder addNoHost(String noHost);
601
        Proxy build();
602
    }
603
}
604

605
public interface ReleasableResource {
606
    default void closeResource();
607
}
608
```