0
# Server Building
1

2
Server-side gRPC server creation and configuration using Netty transport. The `NettyServerBuilder` provides comprehensive options for server setup, connection management, SSL/TLS configuration, and performance tuning.
3

4
## Capabilities
5

6
### NettyServerBuilder Factory Methods
7

8
Create `NettyServerBuilder` instances for different server configurations.
9

10
```java { .api }
11
/**
12
 * Create a server builder for a specific port
13
 * @param port The port to listen on
14
 * @return NettyServerBuilder for configuration
15
 */
16
public static NettyServerBuilder forPort(int port);
17

18
/**
19
 * Create a server builder for a port with credentials
20
 */
21
public static NettyServerBuilder forPort(int port, ServerCredentials creds);
22

23
/**
24
 * Create a server builder for a socket address
25
 * @param address The socket address to bind to
26
 * @return NettyServerBuilder for configuration
27
 */
28
public static NettyServerBuilder forAddress(SocketAddress address);
29

30
/**
31
 * Create a server builder for a socket address with credentials
32
 */
33
public static NettyServerBuilder forAddress(SocketAddress address, ServerCredentials creds);
34
```
35

36
**Usage Examples:**
37

38
```java
39
import io.grpc.netty.shaded.io.grpc.netty.NettyServerBuilder;
40
import io.grpc.InsecureServerCredentials;
41

42
// Basic server
43
NettyServerBuilder builder = NettyServerBuilder.forPort(9090);
44

45
// Server with credentials
46
NettyServerBuilder secureBuilder = NettyServerBuilder.forPort(
47
    9090, 
48
    InsecureServerCredentials.create()
49
);
50

51
// Server on specific address
52
NettyServerBuilder addressBuilder = NettyServerBuilder.forAddress(
53
    new InetSocketAddress("0.0.0.0", 8080)
54
);
55
```
56

57
### Server Address Configuration
58

59
Configure additional listen addresses for the server.
60

61
```java { .api }
62
/**
63
 * Add an additional address for the server to listen on
64
 * @param listenAddress Additional socket address to bind
65
 * @return This builder for chaining
66
 */
67
public NettyServerBuilder addListenAddress(SocketAddress listenAddress);
68
```
69

70
**Usage Example:**
71

72
```java
73
import java.net.InetSocketAddress;
74

75
NettyServerBuilder builder = NettyServerBuilder
76
    .forPort(9090)
77
    .addListenAddress(new InetSocketAddress("127.0.0.1", 9091))
78
    .addListenAddress(new InetSocketAddress("::1", 9092));
79
```
80

81
### Channel Type Configuration
82

83
Configure the underlying Netty server channel type and factory.
84

85
```java { .api }
86
/**
87
 * Set the server channel type
88
 * @param channelType The Netty server channel class to use
89
 * @return This builder for chaining
90
 */
91
public NettyServerBuilder channelType(Class<? extends ServerChannel> channelType);
92

93
/**
94
 * Set a custom server channel factory
95
 * @param channelFactory Factory for creating server channels
96
 * @return This builder for chaining
97
 */
98
public NettyServerBuilder channelFactory(ChannelFactory<? extends ServerChannel> channelFactory);
99
```
100

101
**Usage Example:**
102

103
```java
104
import io.grpc.netty.shaded.io.netty.channel.socket.nio.NioServerSocketChannel;
105

106
NettyServerBuilder builder = NettyServerBuilder
107
    .forPort(9090)
108
    .channelType(NioServerSocketChannel.class);
109
```
110

111
### Channel Options Configuration
112

113
Configure Netty channel options for parent and child channels.
114

115
```java { .api }
116
/**
117
 * Set a Netty channel option for the server channel
118
 * @param option The channel option to set
119
 * @param value The value for the option
120
 * @return This builder for chaining
121
 */
122
public <T> NettyServerBuilder withOption(ChannelOption<T> option, T value);
123

124
/**
125
 * Set a Netty channel option for child channels (client connections)
126
 * @param option The channel option to set
127
 * @param value The value for the option
128
 * @return This builder for chaining
129
 */
130
public <T> NettyServerBuilder withChildOption(ChannelOption<T> option, T value);
131
```
132

133
**Usage Example:**
134

135
```java
136
import io.grpc.netty.shaded.io.netty.channel.ChannelOption;
137

138
NettyServerBuilder builder = NettyServerBuilder
139
    .forPort(9090)
140
    .withOption(ChannelOption.SO_BACKLOG, 128)
141
    .withChildOption(ChannelOption.SO_KEEPALIVE, true)
142
    .withChildOption(ChannelOption.TCP_NODELAY, true);
143
```
144

145
### Event Loop Configuration
146

147
Configure Netty event loop groups for the server.
148

149
```java { .api }
150
/**
151
 * Set the boss event loop group (accepts connections)
152
 * @param group The EventLoopGroup for accepting connections
153
 * @return This builder for chaining
154
 */
155
public NettyServerBuilder bossEventLoopGroup(EventLoopGroup group);
156

157
/**
158
 * Set the worker event loop group (handles connections)
159
 * @param group The EventLoopGroup for handling connections
160
 * @return This builder for chaining
161
 */
162
public NettyServerBuilder workerEventLoopGroup(EventLoopGroup group);
163
```
164

165
**Usage Example:**
166

167
```java
168
import io.grpc.netty.shaded.io.netty.channel.nio.NioEventLoopGroup;
169

170
EventLoopGroup bossGroup = new NioEventLoopGroup(1);
171
EventLoopGroup workerGroup = new NioEventLoopGroup(4);
172

173
NettyServerBuilder builder = NettyServerBuilder
174
    .forPort(9090)
175
    .bossEventLoopGroup(bossGroup)
176
    .workerEventLoopGroup(workerGroup);
177
```
178

179
### Security Configuration
180

181
Configure SSL/TLS and transport security.
182

183
```java { .api }
184
/**
185
 * Set a custom SSL context
186
 * @param sslContext The Netty SSL context
187
 * @return This builder for chaining
188
 */
189
public NettyServerBuilder sslContext(SslContext sslContext);
190

191
/**
192
 * Configure transport security with certificate files
193
 * @param certChain Certificate chain file
194
 * @param privateKey Private key file
195
 * @return This builder for chaining
196
 */
197
public NettyServerBuilder useTransportSecurity(File certChain, File privateKey);
198

199
/**
200
 * Configure transport security with certificate streams
201
 * @param certChain Certificate chain input stream
202
 * @param privateKey Private key input stream
203
 * @return This builder for chaining
204
 */
205
public NettyServerBuilder useTransportSecurity(InputStream certChain, InputStream privateKey);
206
```
207

208
**Usage Example:**
209

210
```java
211
import java.io.File;
212

213
NettyServerBuilder builder = NettyServerBuilder
214
    .forPort(9090)
215
    .useTransportSecurity(
216
        new File("server.crt"),
217
        new File("server.key")
218
    );
219
```
220

221
### Connection Management
222

223
Configure connection limits and behavior.
224

225
```java { .api }
226
/**
227
 * Set the maximum number of concurrent calls per connection
228
 * @param maxCalls Maximum concurrent calls per connection
229
 * @return This builder for chaining
230
 */
231
public NettyServerBuilder maxConcurrentCallsPerConnection(int maxCalls);
232

233
/**
234
 * Set the maximum connection idle time
235
 * @param maxConnectionIdle Maximum idle time before closing connection
236
 * @param timeUnit Time unit for maxConnectionIdle
237
 * @return This builder for chaining
238
 */
239
public NettyServerBuilder maxConnectionIdle(long maxConnectionIdle, TimeUnit timeUnit);
240

241
/**
242
 * Set the maximum connection age
243
 * @param maxConnectionAge Maximum age before closing connection
244
 * @param timeUnit Time unit for maxConnectionAge
245
 * @return This builder for chaining
246
 */
247
public NettyServerBuilder maxConnectionAge(long maxConnectionAge, TimeUnit timeUnit);
248

249
/**
250
 * Set the maximum connection age grace period
251
 * @param maxConnectionAgeGrace Grace period after max age
252
 * @param timeUnit Time unit for maxConnectionAgeGrace
253
 * @return This builder for chaining
254
 */
255
public NettyServerBuilder maxConnectionAgeGrace(long maxConnectionAgeGrace, TimeUnit timeUnit);
256
```
257

258
### Flow Control Configuration
259

260
Configure HTTP/2 flow control settings.
261

262
```java { .api }
263
/**
264
 * Set the initial flow control window size
265
 * @param initialFlowControlWindow Initial window size in bytes
266
 * @return This builder for chaining
267
 */
268
public NettyServerBuilder initialFlowControlWindow(int initialFlowControlWindow);
269

270
/**
271
 * Set the flow control window size
272
 * @param flowControlWindow Window size in bytes
273
 * @return This builder for chaining
274
 */
275
public NettyServerBuilder flowControlWindow(int flowControlWindow);
276
```
277

278
### Message and Metadata Limits
279

280
Configure size limits for inbound messages and metadata.
281

282
```java { .api }
283
/**
284
 * Set the maximum inbound message size
285
 * @param bytes Maximum message size in bytes
286
 * @return This builder for chaining
287
 */
288
public NettyServerBuilder maxInboundMessageSize(int bytes);
289

290
/**
291
 * Set the maximum inbound metadata size
292
 * @param bytes Maximum metadata size in bytes
293
 * @return This builder for chaining
294
 */
295
public NettyServerBuilder maxInboundMetadataSize(int bytes);
296

297
/**
298
 * Set soft and hard limits for inbound metadata size
299
 */
300
public NettyServerBuilder maxInboundMetadataSize(int soft, int max);
301

302
/**
303
 * Set the maximum message size (deprecated)
304
 * @param maxMessageSize Maximum message size in bytes
305
 * @return This builder for chaining
306
 * @deprecated Use maxInboundMessageSize(int) instead
307
 */
308
@Deprecated
309
public NettyServerBuilder maxMessageSize(int maxMessageSize);
310

311
/**
312
 * Set the maximum header list size (deprecated)
313
 * @param maxHeaderListSize Maximum header list size in bytes
314
 * @return This builder for chaining
315
 * @deprecated Use maxInboundMetadataSize(int) instead
316
 */
317
@Deprecated
318
public NettyServerBuilder maxHeaderListSize(int maxHeaderListSize);
319
```
320

321
### Keep-Alive Configuration
322

323
Configure server-side keep-alive behavior and policies.
324

325
```java { .api }
326
/**
327
 * Set the keep-alive time (server sends pings)
328
 * @param keepAliveTime Time between keep-alive pings
329
 * @param timeUnit Time unit for keepAliveTime
330
 * @return This builder for chaining
331
 */
332
public NettyServerBuilder keepAliveTime(long keepAliveTime, TimeUnit timeUnit);
333

334
/**
335
 * Set the keep-alive timeout
336
 * @param keepAliveTimeout Timeout for keep-alive response
337
 * @param timeUnit Time unit for keepAliveTimeout
338
 * @return This builder for chaining
339
 */
340
public NettyServerBuilder keepAliveTimeout(long keepAliveTimeout, TimeUnit timeUnit);
341

342
/**
343
 * Set the minimum allowed keep-alive time from clients
344
 * @param keepAliveTime Minimum time between client pings
345
 * @param timeUnit Time unit for keepAliveTime
346
 * @return This builder for chaining
347
 */
348
public NettyServerBuilder permitKeepAliveTime(long keepAliveTime, TimeUnit timeUnit);
349

350
/**
351
 * Allow/disallow keep-alive pings without active calls
352
 * @param permit Whether to allow keep-alive without calls
353
 * @return This builder for chaining
354
 */
355
public NettyServerBuilder permitKeepAliveWithoutCalls(boolean permit);
356
```
357

358
**Usage Example:**
359

360
```java
361
import java.util.concurrent.TimeUnit;
362

363
NettyServerBuilder builder = NettyServerBuilder
364
    .forPort(9090)
365
    .keepAliveTime(60, TimeUnit.SECONDS)
366
    .keepAliveTimeout(10, TimeUnit.SECONDS)
367
    .permitKeepAliveTime(5, TimeUnit.SECONDS)
368
    .permitKeepAliveWithoutCalls(false);
369
```
370

371
### Rate Limiting
372

373
Configure rate limiting for RST frames to prevent abuse.
374

375
```java { .api }
376
/**
377
 * Set the maximum number of RST frames per window
378
 * @param maxRstStream Maximum RST frames allowed
379
 * @param secondsPerWindow Time window in seconds
380
 * @return This builder for chaining
381
 */
382
public NettyServerBuilder maxRstFramesPerWindow(int maxRstStream, int secondsPerWindow);
383
```
384

385
**Usage Example:**
386

387
```java
388
NettyServerBuilder builder = NettyServerBuilder
389
    .forPort(9090)
390
    .maxRstFramesPerWindow(100, 60); // Max 100 RST frames per minute
391
```
392

393
## Constants
394

395
```java { .api }
396
/**
397
 * Default flow control window size (1 MiB)
398
 */
399
public static final int DEFAULT_FLOW_CONTROL_WINDOW = 1024 * 1024;
400

401
/**
402
 * Value indicating max connection idle is disabled
403
 */
404
static final long MAX_CONNECTION_IDLE_NANOS_DISABLED = Long.MAX_VALUE;
405

406
/**
407
 * Value indicating max connection age is disabled
408
 */
409
static final long MAX_CONNECTION_AGE_NANOS_DISABLED = Long.MAX_VALUE;
410

411
/**
412
 * Value indicating infinite connection age grace period
413
 */
414
static final long MAX_CONNECTION_AGE_GRACE_NANOS_INFINITE = Long.MAX_VALUE;
415

416
/**
417
 * Value indicating RST count limiting is disabled
418
 */
419
static final int MAX_RST_COUNT_DISABLED = 0;
420
```