0
# Protocol-Specific Clients
1

2
Access to protocol-specific functionality including HTTP/1.1 features like protocol upgrades, HTTP/2 specific capabilities, and non-HTTP protocols like WebSocket and gRPC.
3

4
## Capabilities
5

6
### Protocol Client Switching
7

8
Switch from the generic WebClient to protocol-specific clients for accessing advanced features.
9

10
```java { .api }
11
/**
12
 * Switch to a protocol-specific client using its configured settings
13
 * @param protocol protocol instance, usually defined as a constant on the protocol interface
14
 * @param <T> type of the protocol client
15
 * @param <C> type of the protocol config
16
 * @return a new protocol client instance
17
 */
18
<T, C extends ProtocolConfig> T client(Protocol<T, C> protocol);
19

20
/**
21
 * Switch to a protocol-specific client with custom configuration
22
 * @param protocol protocol instance, usually defined as a constant on the protocol interface
23
 * @param protocolConfig configuration of the protocol to be used
24
 * @param <T> type of the protocol client
25
 * @param <C> type of the protocol config
26
 * @return a new protocol client instance
27
 */
28
<T, C extends ProtocolConfig> T client(Protocol<T, C> protocol, C protocolConfig);
29
```
30

31
**Usage Examples:**
32

33
```java
34
import io.helidon.webclient.api.WebClient;
35
import io.helidon.webclient.http1.Http1Client;
36
import io.helidon.webclient.http2.Http2Client;
37

38
WebClient webClient = WebClient.create();
39

40
// Switch to HTTP/1.1 client
41
Http1Client http1Client = webClient.client(Http1Client.PROTOCOL);
42

43
// Switch to HTTP/2 client with custom config
44
Http2ClientProtocolConfig http2Config = Http2ClientProtocolConfig.builder()
45
    .maxFrameSize(32768)
46
    .build();
47
Http2Client http2Client = webClient.client(Http2Client.PROTOCOL, http2Config);
48
```
49

50
### HTTP/1.1 Client
51

52
HTTP/1.1 specific client with support for protocol upgrades and HTTP/1.1 features.
53

54
```java { .api }
55
public interface Http1Client extends HttpClient<Http1ClientRequest> {
56
    /**
57
     * HTTP/1.1 protocol identifier
58
     */
59
    String PROTOCOL_ID = "http/1.1";
60
    
61
    /**
62
     * Protocol instance for WebClient integration
63
     */
64
    Protocol<Http1Client, Http1ClientProtocolConfig> PROTOCOL = ...;
65
    
66
    /**
67
     * Create HTTP/1.1 client with default configuration
68
     * @return new HTTP/1.1 client
69
     */
70
    static Http1Client create();
71
    
72
    /**
73
     * Create HTTP/1.1 client with custom configuration
74
     * @param clientConfig configuration to use
75
     * @return new HTTP/1.1 client
76
     */
77
    static Http1Client create(Http1ClientConfig clientConfig);
78
    
79
    /**
80
     * Create HTTP/1.1 client with configuration customization
81
     * @param consumer configuration consumer
82
     * @return new HTTP/1.1 client
83
     */
84
    static Http1Client create(Consumer<Http1ClientConfig.Builder> consumer);
85
    
86
    /**
87
     * Create configuration builder
88
     * @return new configuration builder
89
     */
90
    static Http1ClientConfig.Builder builder();
91
}
92

93
public interface Http1ClientRequest extends ClientRequest<Http1ClientRequest> {
94
    /**
95
     * Submit request with entity (overridden for return type)
96
     * @param entity request entity
97
     * @return HTTP/1.1 response
98
     */
99
    Http1ClientResponse submit(Object entity);
100
    
101
    /**
102
     * Execute request without entity (overridden for return type)
103
     * @return HTTP/1.1 response
104
     */
105
    default Http1ClientResponse request();
106
    
107
    /**
108
     * Handle output stream for request body (overridden for return type)
109
     * @param outputStreamConsumer consumer to write to output stream
110
     * @return HTTP/1.1 response
111
     */
112
    Http1ClientResponse outputStream(OutputStreamHandler outputStreamConsumer);
113
    
114
    /**
115
     * Upgrade to different protocol (WebSocket, HTTP/2, etc.)
116
     * @param protocol target protocol identifier
117
     * @return upgrade response
118
     */
119
    UpgradeResponse upgrade(String protocol);
120
}
121

122
public interface Http1ClientResponse extends HttpClientResponse {
123
    // HTTP/1.1 specific response features
124
}
125
```
126

127
**Usage Examples:**
128

129
```java
130
import io.helidon.webclient.http1.Http1Client;
131
import io.helidon.webclient.http1.Http1ClientRequest;
132
import io.helidon.webclient.http1.Http1ClientResponse;
133

134
// Create standalone HTTP/1.1 client
135
Http1Client http1Client = Http1Client.create();
136

137
// Or get from WebClient
138
WebClient webClient = WebClient.create();
139
Http1Client http1Client = webClient.client(Http1Client.PROTOCOL);
140

141
// Make HTTP/1.1 request
142
Http1ClientResponse response = http1Client.get("/api/data").request();
143

144
// Protocol upgrade (e.g., to WebSocket)
145
Http1ClientRequest upgradeRequest = http1Client.get("/websocket")
146
    .header(HeaderNames.CONNECTION, "Upgrade")
147
    .header(HeaderNames.UPGRADE, "websocket");
148
UpgradeResponse upgradeResponse = upgradeRequest.upgrade("websocket");
149
```
150

151
### HTTP/2 Client
152

153
HTTP/2 specific client with support for HTTP/2 features like multiplexing and server push.
154

155
```java { .api }
156
public interface Http2Client extends HttpClient<Http2ClientRequest> {
157
    /**
158
     * HTTP/2 protocol identifier
159
     */
160
    String PROTOCOL_ID = "h2";
161
    
162
    /**
163
     * Protocol instance for WebClient integration
164
     */
165
    Protocol<Http2Client, Http2ClientProtocolConfig> PROTOCOL = ...;
166
    
167
    /**
168
     * Create HTTP/2 client with default configuration
169
     * @return new HTTP/2 client
170
     */
171
    static Http2Client create();
172
    
173
    /**
174
     * Create HTTP/2 client with custom configuration
175
     * @param clientConfig configuration to use
176
     * @return new HTTP/2 client
177
     */
178
    static Http2Client create(Http2ClientConfig clientConfig);
179
    
180
    /**
181
     * Create HTTP/2 client with configuration customization
182
     * @param consumer configuration consumer
183
     * @return new HTTP/2 client
184
     */
185
    static Http2Client create(Consumer<Http2ClientConfig.Builder> consumer);
186
    
187
    /**
188
     * Create configuration builder
189
     * @return new configuration builder
190
     */
191
    static Http2ClientConfig.Builder builder();
192
}
193

194
public interface Http2ClientRequest extends ClientRequest<Http2ClientRequest> {
195
    /**
196
     * Submit request with entity (overridden for return type)
197
     * @param entity request entity
198
     * @return HTTP/2 response
199
     */
200
    Http2ClientResponse submit(Object entity);
201
    
202
    /**
203
     * Execute request without entity (overridden for return type)
204
     * @return HTTP/2 response
205
     */
206
    default Http2ClientResponse request();
207
    
208
    /**
209
     * Handle output stream for request body (overridden for return type)
210
     * @param outputStreamConsumer consumer to write to output stream
211
     * @return HTTP/2 response
212
     */
213
    Http2ClientResponse outputStream(OutputStreamHandler outputStreamConsumer);
214
}
215

216
public interface Http2ClientResponse extends HttpClientResponse {
217
    // HTTP/2 specific response features
218
}
219
```
220

221
**Usage Examples:**
222

223
```java
224
import io.helidon.webclient.http2.Http2Client;
225
import io.helidon.webclient.http2.Http2ClientProtocolConfig;
226

227
// Create HTTP/2 client with custom configuration
228
Http2Client http2Client = Http2Client.create(builder -> builder
229
    .maxFrameSize(32768)
230
    .enablePush(true));
231

232
// Or get from WebClient with configuration
233
WebClient webClient = WebClient.create();
234
Http2ClientProtocolConfig http2Config = Http2ClientProtocolConfig.builder()
235
    .maxFrameSize(65536)
236
    .build();
237
Http2Client http2Client = webClient.client(Http2Client.PROTOCOL, http2Config);
238

239
// Make HTTP/2 request
240
Http2ClientResponse response = http2Client.get("/api/data").request();
241
```
242

243
### WebSocket Client
244

245
WebSocket client for real-time communication over WebSocket protocol.
246

247
```java { .api }
248
public interface WsClient {
249
    /**
250
     * WebSocket protocol identifier
251
     */
252
    String PROTOCOL_ID = "websocket";
253
    
254
    /**
255
     * Protocol instance for WebClient integration
256
     */
257
    Protocol<WsClient, WsClientProtocolConfig> PROTOCOL = ...;
258
    
259
    /**
260
     * Create WebSocket client
261
     * @return new WebSocket client
262
     */
263
    static WsClient create();
264
    
265
    /**
266
     * Create WebSocket client with configuration
267
     * @param config WebSocket configuration
268
     * @return new WebSocket client
269
     */
270
    static WsClient create(WsClientConfig config);
271
}
272
```
273

274
**Usage Examples:**
275

276
```java
277
import io.helidon.webclient.websocket.WsClient;
278

279
// Get WebSocket client from WebClient
280
WebClient webClient = WebClient.create();
281
WsClient wsClient = webClient.client(WsClient.PROTOCOL);
282

283
// Connect to WebSocket endpoint
284
wsClient.connect("/websocket", (session, message) -> {
285
    // Handle WebSocket messages
286
});
287
```
288

289
### gRPC Client
290

291
gRPC client for Protocol Buffers-based RPC communication over HTTP/2.
292

293
```java { .api }
294
public interface GrpcClient {
295
    /**
296
     * gRPC protocol identifier
297
     */
298
    String PROTOCOL_ID = "grpc";
299
    
300
    /**
301
     * Protocol instance for WebClient integration
302
     */
303
    Protocol<GrpcClient, GrpcClientProtocolConfig> PROTOCOL = ...;
304
    
305
    /**
306
     * Create gRPC client
307
     * @return new gRPC client
308
     */
309
    static GrpcClient create();
310
    
311
    /**
312
     * Create gRPC client with configuration
313
     * @param config gRPC configuration
314
     * @return new gRPC client
315
     */
316
    static GrpcClient create(GrpcClientConfig config);
317
}
318
```
319

320
**Usage Examples:**
321

322
```java
323
import io.helidon.webclient.grpc.GrpcClient;
324

325
// Get gRPC client from WebClient
326
WebClient webClient = WebClient.create();
327
GrpcClient grpcClient = webClient.client(GrpcClient.PROTOCOL);
328

329
// Make gRPC call (assumes generated stub classes)
330
GreeterServiceStub stub = GreeterServiceStub.create(grpcClient);
331
HelloReply response = stub.sayHello(HelloRequest.newBuilder()
332
    .setName("World")
333
    .build());
334
```
335

336
### Protocol Configuration
337

338
Configure protocol-specific settings for different HTTP versions and protocols.
339

340
```java { .api }
341
public interface ProtocolConfig {
342
    // Base protocol configuration
343
}
344

345
public interface Http1ClientProtocolConfig extends ProtocolConfig {
346
    // HTTP/1.1 specific configuration
347
    boolean keepAlive();
348
    boolean pipelining();
349
    Duration keepAliveTimeout();
350
}
351

352
public interface Http2ClientProtocolConfig extends ProtocolConfig {
353
    // HTTP/2 specific configuration
354
    int maxFrameSize();
355
    int maxConcurrentStreams();
356
    boolean enablePush();
357
    Duration connectionWindowSize();
358
    Duration streamWindowSize();
359
}
360

361
public interface WsClientProtocolConfig extends ProtocolConfig {
362
    // WebSocket specific configuration
363
    List<String> subProtocols();
364
    Duration pingPeriod();
365
    int maxMessageSize();
366
}
367

368
public interface GrpcClientProtocolConfig extends ProtocolConfig {
369
    // gRPC specific configuration
370
    Duration deadline();
371
    Metadata headers();
372
    CallCredentials credentials();
373
}
374
```
375

376
### Protocol Discovery
377

378
Helidon WebClient automatically discovers available HTTP protocol implementations based on classpath and server capabilities.
379

380
**Protocol Negotiation Process:**
381

382
1. **TLS Connections**: Uses ALPN (Application-Layer Protocol Negotiation) to negotiate protocol
383
2. **Plaintext Connections**: Attempts HTTP/2 upgrade or uses prior knowledge
384
3. **Fallback**: Falls back to HTTP/1.1 if higher versions are not supported
385

386
**Usage Examples:**
387

388
```java
389
// WebClient automatically selects appropriate protocol
390
WebClient client = WebClient.builder()
391
    // Prefer HTTP/2, fall back to HTTP/1.1
392
    .addProtocolPreference(List.of("h2", "http/1.1"))
393
    .build();
394

395
// Request will use best available protocol
396
String response = client.get("https://example.com/api/data")
397
    .requestEntity(String.class);
398

399
// Force specific protocol if needed
400
String response = client.get("https://example.com/api/data")
401
    .protocolId("http/1.1")  // Force HTTP/1.1
402
    .requestEntity(String.class);
403
```
404

405
## Types
406

407
```java { .api }
408
public interface Protocol<T, C extends ProtocolConfig> {
409
    ClientProtocolProvider<T, C> provider();
410
}
411

412
public interface ProtocolConfig {
413
    // Base protocol configuration marker interface
414
}
415

416
public interface ClientProtocolProvider<T, C extends ProtocolConfig> {
417
    T protocol(WebClient client, C protocolConfig);
418
}
419

420
public interface UpgradeResponse {
421
    Status status();
422
    ClientResponseHeaders headers();
423
    // Protocol-specific upgrade result
424
}
425

426
// HTTP/1.1 specific types
427
public interface Http1Client extends HttpClient<Http1ClientRequest> {
428
    // HTTP/1.1 client interface
429
}
430

431
public interface Http1ClientRequest extends ClientRequest<Http1ClientRequest> {
432
    Http1ClientResponse submit(Object entity);
433
    Http1ClientResponse request();
434
    Http1ClientResponse outputStream(OutputStreamHandler outputStreamConsumer);
435
    UpgradeResponse upgrade(String protocol);
436
}
437

438
public interface Http1ClientResponse extends HttpClientResponse {
439
    // HTTP/1.1 response interface
440
}
441

442
// HTTP/2 specific types
443
public interface Http2Client extends HttpClient<Http2ClientRequest> {
444
    // HTTP/2 client interface
445
}
446

447
public interface Http2ClientRequest extends ClientRequest<Http2ClientRequest> {
448
    Http2ClientResponse submit(Object entity);
449
    Http2ClientResponse request();
450
    Http2ClientResponse outputStream(OutputStreamHandler outputStreamConsumer);
451
}
452

453
public interface Http2ClientResponse extends HttpClientResponse {
454
    // HTTP/2 response interface
455
}
456
```