0
# Server Transport
1

2
Server transport functionality provides comprehensive server creation and configuration for accepting gRPC connections using Netty's HTTP/2 implementation.
3

4
## Core Imports
5

6
```java
7
import io.grpc.Server;
8
import io.grpc.netty.NettyServerBuilder;
9
import io.grpc.ServerCredentials;
10
import io.netty.channel.ChannelFactory;
11
import io.netty.channel.ChannelOption;
12
import io.netty.channel.EventLoopGroup;
13
import io.netty.channel.ServerChannel;
14
import io.netty.handler.ssl.SslContext;
15
import java.io.File;
16
import java.io.InputStream;
17
import java.net.SocketAddress;
18
import java.util.concurrent.TimeUnit;
19
```
20

21
## NettyServerBuilder
22

23
The primary entry point for creating gRPC servers with Netty transport.
24

25
### Factory Methods
26

27
```java { .api }
28
public static NettyServerBuilder forPort(int port);
29
public static NettyServerBuilder forPort(int port, ServerCredentials creds);
30
public static NettyServerBuilder forAddress(SocketAddress address);
31
public static NettyServerBuilder forAddress(SocketAddress address, ServerCredentials creds);
32
```
33

34
**Parameters:**
35
- `port` - The port number to listen on
36
- `address` - A `SocketAddress` to bind to
37
- `creds` - Server credentials for authentication/encryption
38

39
### Server Address Configuration
40

41
```java { .api }
42
public NettyServerBuilder addListenAddress(SocketAddress listenAddress);
43
```
44

45
**Parameters:**
46
- `listenAddress` - Additional socket address to listen on (supports multiple bind addresses)
47

48
### Channel Configuration
49

50
```java { .api }
51
public NettyServerBuilder channelType(Class<? extends ServerChannel> channelType);
52
public NettyServerBuilder channelFactory(ChannelFactory<? extends ServerChannel> channelFactory);
53
public <T> NettyServerBuilder withOption(ChannelOption<T> option, T value);
54
public <T> NettyServerBuilder withChildOption(ChannelOption<T> option, T value);
55
```
56

57
**Parameters:**
58
- `channelType` - Netty server channel class (e.g., `NioServerSocketChannel.class`)
59
- `option` - Channel option for the server channel (accepts connections)
60
- `value` - Value for the channel option
61
- Channel options vs child options:
62
  - `withOption` - Configures the server channel that accepts connections
63
  - `withChildOption` - Configures individual client connection channels
64

65
### Event Loop Configuration
66

67
```java { .api }
68
public NettyServerBuilder bossEventLoopGroup(EventLoopGroup group);
69
public NettyServerBuilder workerEventLoopGroup(EventLoopGroup group);
70
```
71

72
**Parameters:**
73
- `group` - Custom event loop group
74
- Boss event loop - Handles incoming connection acceptance
75
- Worker event loop - Handles I/O operations for established connections
76

77
### SSL/TLS Configuration
78

79
```java { .api }
80
public NettyServerBuilder sslContext(SslContext sslContext);
81
public NettyServerBuilder useTransportSecurity(File certChain, File privateKey);
82
public NettyServerBuilder useTransportSecurity(InputStream certChain, InputStream privateKey);
83
```
84

85
**Parameters:**
86
- `sslContext` - Netty SSL context for TLS connections
87
- `certChain` - Certificate chain file or stream
88
- `privateKey` - Private key file or stream
89

90
### Connection Limits and Control
91

92
```java { .api }
93
public NettyServerBuilder maxConcurrentCallsPerConnection(int maxCalls);
94
public NettyServerBuilder maxConnectionIdle(long maxConnectionIdle, TimeUnit timeUnit);
95
public NettyServerBuilder maxConnectionAge(long maxConnectionAge, TimeUnit timeUnit);
96
public NettyServerBuilder maxConnectionAgeGrace(long maxConnectionAgeGrace, TimeUnit timeUnit);
97
```
98

99
**Parameters:**
100
- `maxCalls` - Maximum number of concurrent calls per connection
101
- `maxConnectionIdle` - Maximum time a connection can be idle before being closed
102
- `maxConnectionAge` - Maximum age of a connection before server closes it
103
- `maxConnectionAgeGrace` - Grace period for active calls when closing aged connections
104
- `timeUnit` - Time unit for the duration values
105

106
### Flow Control and Message Limits
107

108
```java { .api }
109
public NettyServerBuilder initialFlowControlWindow(int initialFlowControlWindow);
110
public NettyServerBuilder flowControlWindow(int flowControlWindow);
111
public NettyServerBuilder maxInboundMetadataSize(int bytes);
112
public NettyServerBuilder maxInboundMetadataSize(int soft, int max);
113
public NettyServerBuilder maxInboundMessageSize(int bytes);
114
```
115

116
**Parameters:**
117
- `initialFlowControlWindow` - Initial HTTP/2 flow control window size in bytes
118
- `bytes` - Maximum size for inbound metadata headers
119

120
**Constants:**
121
```java { .api }
122
public static final int DEFAULT_FLOW_CONTROL_WINDOW = 1048576; // 1 MiB
123
```
124

125
### Keep-Alive Configuration
126

127
```java { .api }
128
public NettyServerBuilder keepAliveTime(long keepAliveTime, TimeUnit timeUnit);
129
public NettyServerBuilder keepAliveTimeout(long keepAliveTimeout, TimeUnit timeUnit);
130
public NettyServerBuilder permitKeepAliveTime(long keepAliveTime, TimeUnit timeUnit);
131
public NettyServerBuilder permitKeepAliveWithoutCalls(boolean permit);
132
```
133

134
**Parameters:**
135
- `keepAliveTime` - Time between server-initiated keep-alive pings
136
- `keepAliveTimeout` - Timeout for keep-alive ping responses
137
- `permitKeepAliveTime` - Minimum time clients must wait between keep-alive pings
138
- `permit` - Whether to allow client keep-alive pings when no calls are active
139

140
### Security and Rate Limiting
141

142
```java { .api }
143
public NettyServerBuilder maxRstFramesPerWindow(int maxRstStream, int secondsPerWindow);
144
```
145

146
**Parameters:**
147
- `maxRstStream` - Maximum number of RST_STREAM frames allowed per time window
148
- `secondsPerWindow` - Time window duration in seconds for RST frame counting
149

150
## Usage Examples
151

152
### Basic Server
153

154
```java
155
import io.grpc.Server;
156
import io.grpc.netty.NettyServerBuilder;
157

158
Server server = NettyServerBuilder.forPort(9090)
159
    .addService(new GreeterImpl())
160
    .build()
161
    .start();
162

163
// Keep server running
164
server.awaitTermination();
165
```
166

167
### Production Server with TLS
168

169
```java
170
import io.grpc.netty.NettyServerBuilder;
171
import java.io.File;
172

173
Server server = NettyServerBuilder.forPort(9090)
174
    .useTransportSecurity(
175
        new File("server-cert.pem"),
176
        new File("server-key.pem")
177
    )
178
    .addService(new GreeterImpl())
179
    .maxConcurrentCallsPerConnection(1000)
180
    .maxInboundMetadataSize(8192)
181
    .keepAliveTime(30, TimeUnit.SECONDS)
182
    .keepAliveTimeout(5, TimeUnit.SECONDS)
183
    .permitKeepAliveTime(5, TimeUnit.SECONDS)
184
    .maxConnectionIdle(60, TimeUnit.SECONDS)
185
    .build()
186
    .start();
187
```
188

189
### High-Performance Server Configuration
190

191
```java
192
import io.netty.channel.nio.NioEventLoopGroup;
193
import io.netty.channel.socket.nio.NioServerSocketChannel;
194

195
EventLoopGroup bossGroup = new NioEventLoopGroup(1);
196
EventLoopGroup workerGroup = new NioEventLoopGroup(8);
197

198
Server server = NettyServerBuilder.forPort(9090)
199
    .channelType(NioServerSocketChannel.class)
200
    .bossEventLoopGroup(bossGroup)
201
    .workerEventLoopGroup(workerGroup)
202
    .withOption(ChannelOption.SO_BACKLOG, 1024)
203
    .withChildOption(ChannelOption.TCP_NODELAY, true)
204
    .withChildOption(ChannelOption.SO_KEEPALIVE, true)
205
    .addService(new GreeterImpl())
206
    .initialFlowControlWindow(1024 * 1024) // 1MB
207
    .maxConcurrentCallsPerConnection(500)
208
    .build()
209
    .start();
210
```
211

212
### Multi-Address Server
213

214
```java
215
import java.net.InetSocketAddress;
216

217
Server server = NettyServerBuilder.forPort(9090)
218
    .addListenAddress(new InetSocketAddress("0.0.0.0", 9091))
219
    .addListenAddress(new InetSocketAddress("localhost", 9092))
220
    .addService(new GreeterImpl())
221
    .build()
222
    .start();
223
```
224

225
### Unix Domain Socket Server
226

227
```java
228
import io.netty.channel.epoll.EpollEventLoopGroup;
229
import io.netty.channel.epoll.EpollServerDomainSocketChannel;
230
import io.netty.channel.unix.DomainSocketAddress;
231

232
EventLoopGroup bossGroup = new EpollEventLoopGroup(1);
233
EventLoopGroup workerGroup = new EpollEventLoopGroup(4);
234

235
Server server = NettyServerBuilder.forAddress(
236
        new DomainSocketAddress("/tmp/grpc.sock"))
237
    .channelType(EpollServerDomainSocketChannel.class)
238
    .bossEventLoopGroup(bossGroup)
239
    .workerEventLoopGroup(workerGroup)
240
    .addService(new GreeterImpl())
241
    .build()
242
    .start();
243
```
244

245
### Rate-Limited Server
246

247
```java
248
Server server = NettyServerBuilder.forPort(9090)
249
    .addService(new GreeterImpl())
250
    .maxConcurrentCallsPerConnection(100)
251
    .maxRstFramesPerWindow(10, 10) // Max 10 RST frames per 10 seconds
252
    .permitKeepAliveTime(30, TimeUnit.SECONDS) // Clients must wait 30s between pings
253
    .permitKeepAliveWithoutCalls(false) // No pings without active calls
254
    .build()
255
    .start();
256
```
257

258
## Error Handling
259

260
Server startup errors are typically thrown as `IOException`:
261

262
```java
263
try {
264
    Server server = NettyServerBuilder.forPort(9090)
265
        .addService(new GreeterImpl())
266
        .build()
267
        .start();
268
} catch (IOException e) {
269
    // Handle server startup failure (e.g., port already in use)
270
    System.err.println("Failed to start server: " + e.getMessage());
271
}
272
```
273

274
## Resource Management
275

276
Properly shutdown servers to release resources:
277

278
```java
279
Server server = NettyServerBuilder.forPort(9090)
280
    .addService(new GreeterImpl())
281
    .build()
282
    .start();
283

284
// Add shutdown hook
285
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
286
    System.out.println("Shutting down gRPC server...");
287
    server.shutdown();
288
    try {
289
        if (!server.awaitTermination(30, TimeUnit.SECONDS)) {
290
            server.shutdownNow();
291
        }
292
    } catch (InterruptedException e) {
293
        server.shutdownNow();
294
        Thread.currentThread().interrupt();
295
    }
296
}));
297

298
// Wait for termination
299
server.awaitTermination();
300
```
301

302
## Thread Pool Management
303

304
When using custom event loop groups, ensure proper shutdown:
305

306
```java
307
EventLoopGroup bossGroup = new NioEventLoopGroup(1);
308
EventLoopGroup workerGroup = new NioEventLoopGroup(8);
309

310
try {
311
    Server server = NettyServerBuilder.forPort(9090)
312
        .bossEventLoopGroup(bossGroup)
313
        .workerEventLoopGroup(workerGroup)
314
        .addService(new GreeterImpl())
315
        .build()
316
        .start();
317
        
318
    server.awaitTermination();
319
} finally {
320
    bossGroup.shutdownGracefully();
321
    workerGroup.shutdownGracefully();
322
}
323
```