0
# Client Transport
1

2
Client transport functionality provides comprehensive channel creation and configuration for connecting to gRPC servers using Netty's HTTP/2 implementation.
3

4
## Core Imports
5

6
```java
7
import io.grpc.ManagedChannel;
8
import io.grpc.netty.NettyChannelBuilder;
9
import io.grpc.netty.NegotiationType;
10
import io.grpc.ChannelCredentials;
11
import io.netty.channel.Channel;
12
import io.netty.channel.ChannelFactory;
13
import io.netty.channel.ChannelOption;
14
import io.netty.channel.EventLoopGroup;
15
import io.netty.handler.ssl.SslContext;
16
import java.net.SocketAddress;
17
import java.util.concurrent.TimeUnit;
18
```
19

20
## NettyChannelBuilder
21

22
The primary entry point for creating gRPC channels with Netty transport.
23

24
### Factory Methods
25

26
```java { .api }
27
public static NettyChannelBuilder forAddress(String host, int port);
28
public static NettyChannelBuilder forAddress(SocketAddress serverAddress);
29
public static NettyChannelBuilder forAddress(String host, int port, ChannelCredentials creds);
30
public static NettyChannelBuilder forAddress(SocketAddress serverAddress, ChannelCredentials creds);
31
public static NettyChannelBuilder forTarget(String target);
32
public static NettyChannelBuilder forTarget(String target, ChannelCredentials creds);
33
```
34

35
**Parameters:**
36
- `host` - The server hostname or IP address
37
- `port` - The server port number
38
- `serverAddress` - A `SocketAddress` for the server
39
- `target` - A target string (e.g., "dns:///example.com:443")
40
- `creds` - Channel credentials for authentication
41

42
### Channel Configuration
43

44
```java { .api }
45
public NettyChannelBuilder channelType(Class<? extends Channel> channelType);
46
public NettyChannelBuilder channelType(Class<? extends Channel> channelType, 
47
                                      Class<? extends SocketAddress> transportSocketType);
48
public NettyChannelBuilder channelFactory(ChannelFactory<? extends Channel> channelFactory);
49
public NettyChannelBuilder channelFactory(ChannelFactory<? extends Channel> channelFactory,
50
                                         Class<? extends SocketAddress> transportSocketType);
51
public <T> NettyChannelBuilder withOption(ChannelOption<T> option, T value);
52
public NettyChannelBuilder eventLoopGroup(EventLoopGroup eventLoopGroup);
53
```
54

55
**Parameters:**
56
- `channelType` - Netty channel class (e.g., `NioSocketChannel.class`)  
57
- `channelFactory` - Custom channel factory for advanced use cases
58
- `option` - Netty `ChannelOption` to configure
59
- `value` - Value for the channel option
60
- `eventLoopGroup` - Custom event loop group for the channel
61

62
### Protocol Configuration
63

64
```java { .api }
65
public NettyChannelBuilder negotiationType(NegotiationType type);
66
public NettyChannelBuilder sslContext(SslContext sslContext);
67
```
68

69
**Parameters:**
70
- `type` - HTTP/2 negotiation type (`TLS`, `PLAINTEXT`, `PLAINTEXT_UPGRADE`)
71
- `sslContext` - Netty SSL context for TLS connections
72

73
### Flow Control and Limits
74

75
```java { .api }
76
public NettyChannelBuilder initialFlowControlWindow(int initialFlowControlWindow);
77
public NettyChannelBuilder flowControlWindow(int flowControlWindow);
78
public NettyChannelBuilder maxInboundMetadataSize(int bytes);
79
public NettyChannelBuilder maxInboundMetadataSize(int soft, int max);
80
public NettyChannelBuilder maxInboundMessageSize(int max);
81
```
82

83
**Parameters:**
84
- `initialFlowControlWindow` - Initial HTTP/2 flow control window size in bytes
85
- `flowControlWindow` - Flow control window size in bytes  
86
- `bytes` - Maximum size for inbound metadata headers
87
- `soft` - Soft limit for metadata size
88
- `max` - Hard limit for metadata size
89
- `max` - Maximum size for inbound messages in bytes
90

91
**Constants:**
92
```java { .api }
93
public static final int DEFAULT_FLOW_CONTROL_WINDOW = 1048576; // 1 MiB
94
```
95

96
### Keep-Alive Configuration
97

98
```java { .api }
99
public NettyChannelBuilder keepAliveTime(long keepAliveTime, TimeUnit timeUnit);
100
public NettyChannelBuilder keepAliveTimeout(long keepAliveTimeout, TimeUnit timeUnit);
101
public NettyChannelBuilder keepAliveWithoutCalls(boolean enable);
102
```
103

104
**Parameters:**
105
- `keepAliveTime` - Time between keep-alive pings
106
- `keepAliveTimeout` - Timeout for keep-alive ping responses
107
- `timeUnit` - Time unit for the duration values
108
- `enable` - Whether to send keep-alive pings when no calls are active
109

110
### Advanced Configuration
111

112
```java { .api }
113
public NettyChannelBuilder localSocketPicker(LocalSocketPicker localSocketPicker);
114
```
115

116
**Parameters:**
117
- `localSocketPicker` - Custom local socket picker implementation
118

119
### LocalSocketPicker
120

121
```java { .api }
122
public static class LocalSocketPicker {
123
    @Nullable
124
    public SocketAddress createSocketAddress(SocketAddress remoteAddress, 
125
                                           Attributes attrs);
126
}
127
```
128

129
## Usage Examples
130

131
### Basic Client Channel
132

133
```java
134
import io.grpc.ManagedChannel;
135
import io.grpc.netty.NettyChannelBuilder;
136

137
ManagedChannel channel = NettyChannelBuilder.forAddress("localhost", 9090)
138
    .usePlaintext()
139
    .build();
140
```
141

142
### Production Client with TLS
143

144
```java
145
import io.grpc.netty.NettyChannelBuilder;
146
import io.grpc.netty.GrpcSslContexts;
147
import io.netty.handler.ssl.SslContext;
148

149
SslContext sslContext = GrpcSslContexts.forClient()
150
    .trustManager(InsecureTrustManagerFactory.INSTANCE)
151
    .build();
152

153
ManagedChannel channel = NettyChannelBuilder.forAddress("api.example.com", 443)
154
    .sslContext(sslContext)
155
    .keepAliveTime(30, TimeUnit.SECONDS)
156
    .keepAliveTimeout(5, TimeUnit.SECONDS)
157
    .keepAliveWithoutCalls(true)
158
    .initialFlowControlWindow(1024 * 1024) // 1MB
159
    .maxInboundMetadataSize(8192)
160
    .build();
161
```
162

163
### High-Performance Configuration
164

165
```java
166
import io.netty.channel.nio.NioEventLoopGroup;
167
import io.netty.channel.socket.nio.NioSocketChannel;
168

169
EventLoopGroup eventLoopGroup = new NioEventLoopGroup(4);
170

171
ManagedChannel channel = NettyChannelBuilder.forAddress("server.example.com", 443)
172
    .channelType(NioSocketChannel.class)
173
    .eventLoopGroup(eventLoopGroup)
174
    .withOption(ChannelOption.TCP_NODELAY, true)
175
    .withOption(ChannelOption.SO_KEEPALIVE, true)
176
    .keepAliveTime(30, TimeUnit.SECONDS)
177
    .build();
178
```
179

180
### Unix Domain Socket Client
181

182
```java
183
import io.netty.channel.epoll.EpollDomainSocketChannel;
184
import io.netty.channel.epoll.EpollEventLoopGroup;
185
import io.netty.channel.unix.DomainSocketAddress;
186

187
EventLoopGroup eventLoopGroup = new EpollEventLoopGroup();
188

189
ManagedChannel channel = NettyChannelBuilder.forAddress(
190
        new DomainSocketAddress("/tmp/grpc.sock"))
191
    .channelType(EpollDomainSocketChannel.class)
192
    .eventLoopGroup(eventLoopGroup)
193
    .usePlaintext()
194
    .build();
195
```
196

197
## Error Handling
198

199
Transport-level connection errors are propagated as `StatusRuntimeException`:
200

201
```java
202
try {
203
    ManagedChannel channel = NettyChannelBuilder.forAddress("unreachable.example.com", 443)
204
        .build();
205
    // Use channel...
206
} catch (StatusRuntimeException e) {
207
    if (e.getStatus().getCode() == Status.Code.UNAVAILABLE) {
208
        // Handle connection failure
209
    }
210
}
211
```
212

213
## Resource Management
214

215
Always properly shut down channels to avoid resource leaks:
216

217
```java
218
ManagedChannel channel = NettyChannelBuilder.forAddress("localhost", 9090)
219
    .usePlaintext()
220
    .build();
221

222
try {
223
    // Use channel...
224
} finally {
225
    channel.shutdown();
226
    try {
227
        if (!channel.awaitTermination(5, TimeUnit.SECONDS)) {
228
            channel.shutdownNow();
229
        }
230
    } catch (InterruptedException e) {
231
        channel.shutdownNow();
232
        Thread.currentThread().interrupt();
233
    }
234
}
235
```