0
# Configuration and Customization
1

2
Server and client configuration with customization hooks for advanced use cases including TLS, load balancing, and performance tuning. The configuration system provides comprehensive control over gRPC behavior.
3

4
## Capabilities
5

6
### ServerBuilderCustomizer Interface
7

8
Allows customization of gRPC server building process. Implement this interface to customize server configuration beyond what's available through standard configuration properties.
9

10
```java { .api }
11
/**
12
 * Allow for customization of Server building.
13
 * Implement the customize method, depending on which ServerBuilder implementation you're going to use,
14
 * e.g. Vert.x or Netty.
15
 * This is an experimental API, subject to change.
16
 */
17
public interface ServerBuilderCustomizer<T extends ServerBuilder<T>> {
18
    
19
    /**
20
     * Customize a ServerBuilder instance.
21
     *
22
     * @param config server's configuration
23
     * @param builder Server builder instance
24
     */
25
    default void customize(GrpcServerConfiguration config, T builder) {
26
    }
27
    
28
    /**
29
     * Customize a GrpcServerOptions instance.
30
     *
31
     * @param config server's configuration
32
     * @param options GrpcServerOptions instance
33
     */
34
    default void customize(GrpcServerConfiguration config, GrpcServerOptions options) {
35
    }
36
    
37
    /**
38
     * Priority by which the customizers are applied.
39
     * Higher priority is applied later.
40
     *
41
     * @return the priority
42
     */
43
    default int priority() {
44
        return 0;
45
    }
46
}
47
```
48

49
**Usage Examples:**
50

51
```java
52
import io.quarkus.grpc.api.ServerBuilderCustomizer;
53
import io.grpc.netty.NettyServerBuilder;
54
import jakarta.enterprise.context.ApplicationScoped;
55

56
@ApplicationScoped
57
public class CustomServerBuilder implements ServerBuilderCustomizer<NettyServerBuilder> {
58
    
59
    @Override
60
    public void customize(GrpcServerConfiguration config, NettyServerBuilder builder) {
61
        // Customize Netty server builder
62
        builder.maxInboundMessageSize(4 * 1024 * 1024) // 4MB
63
               .maxInboundMetadataSize(8 * 1024) // 8KB
64
               .keepAliveTime(30, TimeUnit.SECONDS)
65
               .keepAliveTimeout(10, TimeUnit.SECONDS)
66
               .permitKeepAliveWithoutCalls(true)
67
               .maxConnectionIdle(5, TimeUnit.MINUTES);
68
    }
69
    
70
    @Override
71
    public void customize(GrpcServerConfiguration config, GrpcServerOptions options) {
72
        // Customize Vert.x gRPC server options
73
        options.setMaxMessageSize(4 * 1024 * 1024);
74
        options.setKeepAliveTime(30000); // 30 seconds
75
        options.setKeepAliveTimeout(10000); // 10 seconds
76
    }
77
    
78
    @Override
79
    public int priority() {
80
        return 100; // Higher priority than default customizers
81
    }
82
}
83
```
84

85
### ChannelBuilderCustomizer Interface
86

87
Allows customization of gRPC channel building process for clients. Implement this interface to customize client configuration beyond standard configuration options.
88

89
```java { .api }
90
/**
91
 * Allow for customization of Channel building.
92
 * Implement the customize method, depending on which Channel implementation you're going to use,
93
 * e.g. Vert.x or Netty.
94
 * This is an experimental API, subject to change.
95
 */
96
public interface ChannelBuilderCustomizer<T extends ManagedChannelBuilder<T>> {
97
    
98
    /**
99
     * Customize a ManagedChannelBuilder instance.
100
     *
101
     * @param name gRPC client name
102
     * @param config client's configuration
103
     * @param builder Channel builder instance
104
     * @return map of config properties to be used as default service config against the builder
105
     */
106
    default Map<String, Object> customize(String name, 
107
                                         GrpcClientConfiguration config, 
108
                                         T builder) {
109
        return Map.of();
110
    }
111
    
112
    /**
113
     * Customize a GrpcClientOptions instance.
114
     *
115
     * @param name gRPC client name
116
     * @param config client's configuration
117
     * @param options GrpcClientOptions instance
118
     */
119
    default void customize(String name, 
120
                          GrpcClientConfiguration config, 
121
                          GrpcClientOptions options) {
122
    }
123
    
124
    /**
125
     * Priority by which the customizers are applied.
126
     * Higher priority is applied later.
127
     *
128
     * @return the priority
129
     */
130
    default int priority() {
131
        return 0;
132
    }
133
}
134
```
135

136
**Usage Examples:**
137

138
```java
139
import io.quarkus.grpc.api.ChannelBuilderCustomizer;
140
import io.grpc.netty.NettyChannelBuilder;
141
import jakarta.enterprise.context.ApplicationScoped;
142
import java.util.Map;
143

144
@ApplicationScoped
145
public class CustomChannelBuilder implements ChannelBuilderCustomizer<NettyChannelBuilder> {
146
    
147
    @Override
148
    public Map<String, Object> customize(String name, 
149
                                        GrpcClientConfiguration config, 
150
                                        NettyChannelBuilder builder) {
151
        
152
        // Customize based on client name
153
        if ("high-throughput-service".equals(name)) {
154
            builder.maxInboundMessageSize(16 * 1024 * 1024) // 16MB
155
                   .maxInboundMetadataSize(16 * 1024) // 16KB
156
                   .keepAliveTime(15, TimeUnit.SECONDS)
157
                   .keepAliveWithoutCalls(true);
158
        } else {
159
            builder.maxInboundMessageSize(4 * 1024 * 1024) // 4MB
160
                   .keepAliveTime(30, TimeUnit.SECONDS);
161
        }
162
        
163
        // Return service config for load balancing
164
        return Map.of(
165
            "loadBalancingConfig", Map.of(
166
                "round_robin", Map.of()
167
            ),
168
            "retryPolicy", Map.of(
169
                "maxAttempts", 3,
170
                "initialBackoff", "1s",
171
                "maxBackoff", "10s",
172
                "backoffMultiplier", 2.0,
173
                "retryableStatusCodes", List.of("UNAVAILABLE", "DEADLINE_EXCEEDED")
174
            )
175
        );
176
    }
177
    
178
    @Override
179
    public void customize(String name, 
180
                         GrpcClientConfiguration config, 
181
                         GrpcClientOptions options) {
182
        // Customize Vert.x gRPC client options
183
        options.setMaxMessageSize(4 * 1024 * 1024);
184
        options.setKeepAliveTime(30000);
185
        
186
        if ("secure-service".equals(name)) {
187
            options.setSsl(true);
188
            options.setTrustAll(false);
189
        }
190
    }
191
    
192
    @Override
193
    public int priority() {
194
        return 50;
195
    }
196
}
197
```
198

199
### Configuration Classes
200

201
Core configuration classes for gRPC server and client settings:
202

203
```java { .api }
204
public class GrpcConfiguration {
205
    // Root gRPC configuration
206
}
207

208
public class GrpcServerConfiguration {
209
    // Server-specific configuration including port, TLS, etc.
210
}
211

212
public class GrpcClientConfiguration {
213
    // Client-specific configuration including host, port, TLS, etc.
214
}
215
```
216

217
## Configuration Examples
218

219
### Server Configuration
220

221
```properties
222
# Basic server configuration
223
quarkus.grpc.server.port=9000
224
quarkus.grpc.server.host=0.0.0.0
225

226
# TLS configuration
227
quarkus.grpc.server.ssl.certificate=path/to/server.crt
228
quarkus.grpc.server.ssl.key=path/to/server.key
229
quarkus.grpc.server.ssl.key-store=path/to/keystore.p12
230
quarkus.grpc.server.ssl.key-store-password=secret
231

232
# Performance tuning
233
quarkus.grpc.server.max-inbound-message-size=4194304
234
quarkus.grpc.server.max-inbound-metadata-size=8192
235
quarkus.grpc.server.keep-alive-time=30s
236
quarkus.grpc.server.keep-alive-timeout=10s
237

238
# Development settings
239
quarkus.grpc.server.reflection.enabled=true
240
quarkus.grpc.server.health.enabled=true
241
```
242

243
### Client Configuration
244

245
```properties
246
# User service client
247
quarkus.grpc.clients.user-service.host=user-service.example.com
248
quarkus.grpc.clients.user-service.port=443
249
quarkus.grpc.clients.user-service.ssl.trust-store=path/to/truststore.p12
250
quarkus.grpc.clients.user-service.ssl.trust-store-password=secret
251
quarkus.grpc.clients.user-service.deadline=10s
252

253
# Payment service client with load balancing
254
quarkus.grpc.clients.payment-service.host=payment-service
255
quarkus.grpc.clients.payment-service.port=9000
256
quarkus.grpc.clients.payment-service.load-balancing-policy=round_robin
257
quarkus.grpc.clients.payment-service.max-retry-attempts=3
258

259
# Local development client
260
quarkus.grpc.clients.local-service.host=localhost
261
quarkus.grpc.clients.local-service.port=9001
262
quarkus.grpc.clients.local-service.plain-text=true
263
```
264

265
### Advanced TLS Configuration
266

267
```java
268
@ApplicationScoped
269
public class TlsCustomizer implements ServerBuilderCustomizer<NettyServerBuilder> {
270
    
271
    @Override
272
    public void customize(GrpcServerConfiguration config, NettyServerBuilder builder) {
273
        try {
274
            // Custom SSL context
275
            SslContextBuilder sslContextBuilder = SslContextBuilder.forServer(
276
                new File("path/to/server.crt"),
277
                new File("path/to/server.key")
278
            );
279
            
280
            // Configure client authentication
281
            sslContextBuilder.clientAuth(ClientAuth.REQUIRE);
282
            
283
            // Configure trusted client certificates
284
            sslContextBuilder.trustManager(new File("path/to/client-ca.crt"));
285
            
286
            // Configure cipher suites
287
            sslContextBuilder.ciphers(Arrays.asList(
288
                "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
289
                "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
290
            ));
291
            
292
            // Configure protocols
293
            sslContextBuilder.protocols("TLSv1.2", "TLSv1.3");
294
            
295
            builder.sslContext(sslContextBuilder.build());
296
            
297
        } catch (Exception e) {
298
            throw new RuntimeException("Failed to configure TLS", e);
299
        }
300
    }
301
}
302
```
303

304
### Load Balancing Configuration
305

306
```java
307
@ApplicationScoped
308
public class LoadBalancingCustomizer implements ChannelBuilderCustomizer<NettyChannelBuilder> {
309
    
310
    @Override
311
    public Map<String, Object> customize(String name, 
312
                                        GrpcClientConfiguration config, 
313
                                        NettyChannelBuilder builder) {
314
        
315
        if ("distributed-service".equals(name)) {
316
            // Configure service discovery
317
            builder.nameResolverFactory(new DnsNameResolverProvider())
318
                   .defaultLoadBalancingPolicy("round_robin");
319
            
320
            // Return advanced service config
321
            return Map.of(
322
                "loadBalancingConfig", List.of(
323
                    Map.of("weighted_round_robin", Map.of(
324
                        "enableOobLoadReport", true,
325
                        "oobReportingPeriod", "10s"
326
                    )),
327
                    Map.of("round_robin", Map.of())
328
                ),
329
                "healthCheckConfig", Map.of(
330
                    "serviceName", "health-check-service"
331
                )
332
            );
333
        }
334
        
335
        return Map.of();
336
    }
337
}
338
```
339

340
### Custom Interceptor Configuration
341

342
```java
343
@ApplicationScoped
344
public class InterceptorCustomizer implements ServerBuilderCustomizer<NettyServerBuilder> {
345
    
346
    @Inject
347
    MeterRegistry meterRegistry;
348
    
349
    @Inject
350
    TracingService tracingService;
351
    
352
    @Override
353
    public void customize(GrpcServerConfiguration config, NettyServerBuilder builder) {
354
        // Add metrics interceptor
355
        builder.intercept(new MetricsServerInterceptor(meterRegistry));
356
        
357
        // Add tracing interceptor
358
        builder.intercept(new TracingServerInterceptor(tracingService));
359
        
360
        // Add rate limiting interceptor
361
        builder.intercept(new RateLimitingInterceptor(
362
            RateLimiter.create(100.0))); // 100 requests per second
363
        
364
        // Add authentication interceptor for specific services
365
        builder.intercept(ServerInterceptors.useInputStreamMessages(
366
            new AuthenticationInterceptor()));
367
    }
368
}
369
```
370

371
### Development Mode Configuration
372

373
```java
374
@ApplicationScoped
375
public class DevelopmentCustomizer implements ServerBuilderCustomizer<NettyServerBuilder> {
376
    
377
    @Override
378
    public void customize(GrpcServerConfiguration config, NettyServerBuilder builder) {
379
        if (LaunchMode.current() == LaunchMode.DEVELOPMENT) {
380
            // Enable reflection for development
381
            builder.addService(ProtoReflectionService.newInstance());
382
            
383
            // Add development interceptors
384
            builder.intercept(new DevelopmentLoggingInterceptor());
385
            builder.intercept(new RequestDumpingInterceptor());
386
            
387
            // Relaxed settings for development
388
            builder.permitKeepAliveWithoutCalls(true)
389
                   .permitKeepAliveTime(1, TimeUnit.SECONDS);
390
        }
391
    }
392
}
393
```
394

395
### Health Check Integration
396

397
```properties
398
# Enable health checks
399
quarkus.grpc.server.health.enabled=true
400

401
# Configure health check service
402
quarkus.grpc.server.health.service-name=grpc-health-check
403
```
404

405
```java
406
@ApplicationScoped
407
public class HealthCheckCustomizer implements ServerBuilderCustomizer<NettyServerBuilder> {
408
    
409
    @Override
410
    public void customize(GrpcServerConfiguration config, NettyServerBuilder builder) {
411
        // Add custom health check service
412
        HealthStatusManager healthStatusManager = new HealthStatusManager();
413
        builder.addService(healthStatusManager.getHealthService());
414
        
415
        // Set service status
416
        healthStatusManager.setStatus("", HealthCheckResponse.Status.SERVING);
417
        healthStatusManager.setStatus("greeting-service", HealthCheckResponse.Status.SERVING);
418
    }
419
}
420
```
421

422
## Configuration Priority
423

424
1. **Application properties** (highest priority)
425
2. **Environment variables**
426
3. **System properties**
427
4. **Default values** (lowest priority)
428

429
Configuration customizers are applied in priority order (higher priority applied later), allowing fine-grained control over the final configuration.