0
# gRPC Netty
1

2
gRPC Netty provides a Netty-based HTTP/2 transport implementation for gRPC Java, offering high-performance network communication capabilities. It serves as the primary transport layer for production gRPC applications, enabling efficient client-server communication over HTTP/2 protocol using the Netty framework.
3

4
## Package Information
5

6
- **Package Name**: io.grpc:grpc-netty
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven or Gradle dependencies
10
  ```xml
11
  <dependency>
12
    <groupId>io.grpc</groupId>
13
    <artifactId>grpc-netty</artifactId>
14
    <version>1.73.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import io.grpc.netty.NettyChannelBuilder;
22
import io.grpc.netty.NettyServerBuilder;
23
import io.grpc.netty.GrpcSslContexts;
24
import io.grpc.netty.NegotiationType;
25
```
26

27
## Basic Usage
28

29
### Client Setup
30

31
```java
32
import io.grpc.ManagedChannel;
33
import io.grpc.netty.NettyChannelBuilder;
34

35
// Create a gRPC channel using Netty transport
36
ManagedChannel channel = NettyChannelBuilder.forAddress("localhost", 9090)
37
    .usePlaintext()
38
    .build();
39

40
// Use the channel with your gRPC stub
41
// MyServiceGrpc.MyServiceBlockingStub stub = 
42
//     MyServiceGrpc.newBlockingStub(channel);
43
```
44

45
### Server Setup
46

47
```java
48
import io.grpc.Server;
49
import io.grpc.netty.NettyServerBuilder;
50

51
// Create a gRPC server using Netty transport
52
Server server = NettyServerBuilder.forPort(9090)
53
    .addService(new MyServiceImpl())
54
    .build()
55
    .start();
56
```
57

58
### TLS Configuration
59

60
```java
61
import io.grpc.netty.GrpcSslContexts;
62
import io.netty.handler.ssl.SslContext;
63

64
// Client with TLS
65
SslContext sslContext = GrpcSslContexts.forClient()
66
    .trustManager(new File("ca-cert.pem"))
67
    .build();
68

69
ManagedChannel channel = NettyChannelBuilder.forAddress("localhost", 9090)
70
    .sslContext(sslContext)
71
    .build();
72

73
// Server with TLS
74
SslContext serverSslContext = GrpcSslContexts.forServer(
75
    new File("server-cert.pem"),
76
    new File("server-key.pem")
77
).build();
78

79
Server server = NettyServerBuilder.forPort(9090)
80
    .sslContext(serverSslContext)
81
    .addService(new MyServiceImpl())
82
    .build();
83
```
84

85
## Architecture
86

87
gRPC Netty is built around several key components:
88

89
- **Transport Layer**: Netty-based HTTP/2 implementation providing the communication foundation
90
- **Builder Pattern**: Fluent API through `NettyChannelBuilder` and `NettyServerBuilder` for configuration
91
- **SSL/TLS Integration**: Deep integration with Netty's SSL contexts and gRPC's security requirements
92
- **Protocol Negotiation**: Support for various HTTP/2 negotiation strategies (TLS ALPN, plaintext upgrade)
93
- **Performance Optimization**: Advanced features like flow control, connection pooling, and native socket support
94

95
## Capabilities
96

97
### Client Transport
98

99
Client-side channel creation and configuration for connecting to gRPC servers. Provides comprehensive control over connection parameters, SSL/TLS settings, and performance tuning.
100

101
```java { .api }
102
public static NettyChannelBuilder forAddress(String host, int port);
103
public static NettyChannelBuilder forAddress(SocketAddress serverAddress);
104
public static NettyChannelBuilder forTarget(String target);
105
```
106

107
[Client Transport](./client-transport.md)
108

109
### Server Transport
110

111
Server-side configuration for accepting gRPC connections. Offers fine-grained control over server behavior, connection limits, and transport-specific optimizations.
112

113
```java { .api }
114
public static NettyServerBuilder forPort(int port);
115
public static NettyServerBuilder forAddress(SocketAddress address);
116
public NettyServerBuilder addListenAddress(SocketAddress listenAddress);
117
```
118

119
[Server Transport](./server-transport.md)
120

121
### SSL/TLS Configuration
122

123
Comprehensive SSL/TLS support with utilities for creating properly configured SSL contexts for gRPC communication, including ALPN negotiation and certificate management.
124

125
```java { .api }
126
public static SslContextBuilder forClient();
127
public static SslContextBuilder forServer(File keyCertChainFile, File keyFile);
128
public static SslContextBuilder configure(SslContextBuilder builder);
129
```
130

131
[SSL/TLS Configuration](./ssl-tls.md)
132

133
### Protocol Negotiation
134

135
HTTP/2 protocol negotiation strategies for different deployment scenarios, from TLS ALPN to plaintext upgrades and direct HTTP/2 connections.
136

137
```java { .api }
138
public enum NegotiationType {
139
    TLS, PLAINTEXT_UPGRADE, PLAINTEXT
140
}
141
```
142

143
[Protocol Negotiation](./protocol-negotiation.md)
144

145
### Socket Support
146

147
Low-level socket information access and native optimization features for advanced performance tuning and monitoring.
148

149
```java { .api }
150
public static NativeSocketOptions getNativeSocketOptions(Channel ch);
151
```
152

153
[Socket Support](./socket-support.md)
154

155
## Common Patterns
156

157
### Production Server Configuration
158

159
```java
160
Server server = NettyServerBuilder.forPort(9090)
161
    .addService(new MyServiceImpl())
162
    .maxConcurrentCallsPerConnection(1000)
163
    .maxInboundMetadataSize(8192)
164
    .keepAliveTime(30, TimeUnit.SECONDS)
165
    .keepAliveTimeout(5, TimeUnit.SECONDS)
166
    .maxConnectionIdle(60, TimeUnit.SECONDS)
167
    .build();
168
```
169

170
### High-Performance Client
171

172
```java
173
ManagedChannel channel = NettyChannelBuilder.forAddress("server.example.com", 443)
174
    .sslContext(sslContext)
175
    .keepAliveTime(30, TimeUnit.SECONDS)
176
    .keepAliveTimeout(5, TimeUnit.SECONDS)
177
    .keepAliveWithoutCalls(true)
178
    .maxInboundMetadataSize(4096)
179
    .build();
180
```
181

182
## Types
183

184
### Core Types
185

186
```java { .api }
187
// From io.grpc package
188
interface ChannelCredentials {}
189
interface ServerCredentials {}
190
class ManagedChannel {}
191
class Server {}
192

193
// From io.netty.channel package  
194
interface Channel {}
195
interface ServerChannel {}
196
interface ChannelFactory<T extends Channel> {}
197
interface EventLoopGroup {}
198
class ChannelOption<T> {}
199

200
// From io.netty.handler.ssl package
201
class SslContext {}
202
class SslContextBuilder {}
203
enum SslProvider { OPENSSL, JDK }
204

205
// From java.net package
206
interface SocketAddress {}
207

208
// From java.util.concurrent package
209
enum TimeUnit { NANOSECONDS, MICROSECONDS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS }
210
```
211

212
### Netty-Specific Types
213

214
```java { .api }
215
// From io.grpc.netty package
216
enum NegotiationType { TLS, PLAINTEXT_UPGRADE, PLAINTEXT }
217

218
class NettyChannelBuilder.LocalSocketPicker {
219
    @Nullable
220
    public SocketAddress createSocketAddress(SocketAddress remoteAddress, Attributes attrs);
221
}
222

223
class NettySocketSupport.NativeSocketOptions {
224
    @Nullable
225
    public final TcpInfo tcpInfo;
226
    public final ImmutableMap<String, String> otherInfo;
227
}
228
```
229

230
## Error Handling
231

232
gRPC Netty integrates with gRPC's standard error handling mechanisms. Transport-level errors are typically wrapped in `StatusRuntimeException` or `StatusException` and can be handled using standard gRPC error handling patterns.
233

234
## Performance Considerations
235

236
- Use connection pooling for high-throughput scenarios
237
- Configure flow control windows based on your message sizes
238
- Enable keep-alive for long-lived connections
239
- Use native transport (epoll on Linux) for maximum performance
240
- Configure appropriate thread pools for your workload