0
# Socket Support
1

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

4
## Core Imports
5

6
```java
7
import io.grpc.netty.NettySocketSupport;
8
import io.grpc.netty.NettySocketSupport.NativeSocketOptions;
9
import io.grpc.InternalChannelz.TcpInfo;
10
import io.netty.channel.Channel;
11
import com.google.common.collect.ImmutableMap;
12
```
13

14
## NettySocketSupport
15

16
Utility class for accessing native socket information and options from Netty channels.
17

18
```java { .api }
19
public static NativeSocketOptions getNativeSocketOptions(Channel ch);
20
```
21

22
**Parameters:**
23
- `ch` - Netty channel to inspect
24

25
**Returns:** `NativeSocketOptions` containing socket information, or `null` if not available
26

27
## NativeSocketOptions
28

29
Container class providing access to TCP socket information and native socket options.
30

31
### Socket Information Access
32

33
```java { .api }
34
public class NativeSocketOptions {
35
    // Methods for accessing socket information
36
    public SocketOption<Integer> getSocketOption(String name);
37
    public Map<String, Object> getAllOptions();
38
}
39
```
40

41
**Note:** The exact API surface depends on the underlying native transport implementation and platform support.
42

43
## Usage Examples
44

45
### Basic Socket Information
46

47
```java
48
import io.grpc.netty.NettySocketSupport;
49
import io.grpc.netty.NettySocketSupport.NativeSocketOptions;
50
import io.netty.channel.Channel;
51

52
// Get channel from established connection
53
Channel channel = getNettyChannel(); // From your gRPC channel/server
54

55
NativeSocketOptions socketOptions = NettySocketSupport.getNativeSocketOptions(channel);
56

57
if (socketOptions != null) {
58
    // Access native socket information
59
    System.out.println("Native socket options available");
60
    
61
    // Get specific socket options (platform-dependent)
62
    Map<String, Object> allOptions = socketOptions.getAllOptions();
63
    allOptions.forEach((key, value) -> 
64
        System.out.println(key + ": " + value));
65
} else {
66
    System.out.println("Native socket options not available");
67
}
68
```
69

70
### TCP Information Monitoring
71

72
```java
73
import io.netty.channel.epoll.EpollSocketChannel;
74
import io.netty.channel.epoll.EpollChannelOption;
75

76
// When using epoll transport on Linux
77
if (channel instanceof EpollSocketChannel) {
78
    EpollSocketChannel epollChannel = (EpollSocketChannel) channel;
79
    
80
    // Access TCP_INFO (Linux-specific)
81
    EpollTcpInfo tcpInfo = epollChannel.tcpInfo();
82
    if (tcpInfo != null) {
83
        System.out.println("RTT: " + tcpInfo.rtt());
84
        System.out.println("RTT variance: " + tcpInfo.rttvar());
85
        System.out.println("Send buffer: " + tcpInfo.sndMss());
86
        System.out.println("Receive buffer: " + tcpInfo.rcvMss());
87
    }
88
}
89
```
90

91
### Performance Monitoring Integration
92

93
```java
94
import java.util.concurrent.ScheduledExecutorService;
95
import java.util.concurrent.TimeUnit;
96

97
public class ConnectionMonitor {
98
    private final ScheduledExecutorService scheduler = 
99
        Executors.newScheduledThreadPool(1);
100
    
101
    public void startMonitoring(Channel channel) {
102
        scheduler.scheduleAtFixedRate(() -> {
103
            NativeSocketOptions options = NettySocketSupport.getNativeSocketOptions(channel);
104
            if (options != null) {
105
                logSocketMetrics(options);
106
            }
107
        }, 0, 30, TimeUnit.SECONDS);
108
    }
109
    
110
    private void logSocketMetrics(NativeSocketOptions options) {
111
        Map<String, Object> metrics = options.getAllOptions();
112
        // Log metrics to your monitoring system
113
        System.out.println("Socket metrics: " + metrics);
114
    }
115
}
116
```
117

118
## Platform-Specific Features
119

120
### Linux (Epoll Transport)
121

122
```java
123
import io.netty.channel.epoll.EpollSocketChannel;
124
import io.netty.channel.epoll.EpollChannelOption;
125

126
// Configure epoll-specific options
127
ServerBootstrap bootstrap = new ServerBootstrap()
128
    .group(bossGroup, workerGroup)
129
    .channel(EpollServerSocketChannel.class)
130
    .childOption(EpollChannelOption.TCP_CORK, false)
131
    .childOption(EpollChannelOption.TCP_QUICKACK, true)
132
    .childOption(EpollChannelOption.SO_REUSEPORT, true);
133

134
// Access epoll-specific information
135
if (channel instanceof EpollSocketChannel) {
136
    EpollSocketChannel epollChannel = (EpollSocketChannel) channel;
137
    
138
    // Get TCP connection info
139
    EpollTcpInfo info = epollChannel.tcpInfo();
140
    if (info != null) {
141
        System.out.println("Connection state: " + info.state());
142
        System.out.println("Congestion window: " + info.sndCwnd());
143
        System.out.println("Slow start threshold: " + info.sndSsthresh());
144
    }
145
}
146
```
147

148
### macOS/BSD (KQueue Transport)
149

150
```java
151
import io.netty.channel.kqueue.KQueueSocketChannel;
152
import io.netty.channel.kqueue.KQueueChannelOption;
153

154
// Configure kqueue-specific options
155
ServerBootstrap bootstrap = new ServerBootstrap()
156
    .group(bossGroup, workerGroup)
157
    .channel(KQueueServerSocketChannel.class)
158
    .childOption(KQueueChannelOption.SO_REUSEPORT, true);
159
```
160

161
## Integration with gRPC Channels
162

163
### Client Channel Monitoring
164

165
```java
166
import io.grpc.netty.NettyChannelBuilder;
167
import io.grpc.ConnectivityState;
168

169
ManagedChannel channel = NettyChannelBuilder.forAddress("localhost", 9090)
170
    .usePlaintext()
171
    .build();
172

173
// Monitor channel state changes
174
channel.notifyWhenStateChanged(ConnectivityState.IDLE, () -> {
175
    // Access underlying Netty channel when connected
176
    if (channel.getState(false) == ConnectivityState.READY) {
177
        // Get Netty channel (requires reflection or internal APIs)
178
        monitorSocketOptions(channel);
179
    }
180
});
181
```
182

183
### Server Connection Monitoring
184

185
```java
186
import io.grpc.netty.NettyServerBuilder;
187

188
public class MonitoringServerInterceptor implements ServerInterceptor {
189
    @Override
190
    public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
191
            ServerCall<ReqT, RespT> call,
192
            Metadata headers,
193
            ServerCallHandler<ReqT, RespT> next) {
194
        
195
        // Access transport attributes
196
        Attributes attributes = call.getAttributes();
197
        
198
        // Monitor connection if available
199
        monitorConnection(call);
200
        
201
        return next.startCall(call, headers);
202
    }
203
    
204
    private void monitorConnection(ServerCall<?, ?> call) {
205
        // Access underlying transport information
206
        // Implementation depends on internal gRPC APIs
207
    }
208
}
209
```
210

211
## Native Transport Configuration
212

213
### High-Performance Linux Setup
214

215
```java
216
import io.netty.channel.epoll.EpollEventLoopGroup;
217
import io.netty.channel.epoll.EpollServerSocketChannel;
218
import io.netty.channel.epoll.EpollSocketChannel;
219

220
// Use native epoll transport for better performance
221
EventLoopGroup bossGroup = new EpollEventLoopGroup(1);
222
EventLoopGroup workerGroup = new EpollEventLoopGroup();
223

224
Server server = NettyServerBuilder.forPort(9090)
225
    .channelType(EpollServerSocketChannel.class)
226
    .bossEventLoopGroup(bossGroup)
227
    .workerEventLoopGroup(workerGroup)
228
    .withChildOption(EpollChannelOption.TCP_NODELAY, true)
229
    .withChildOption(EpollChannelOption.SO_KEEPALIVE, true)
230
    .withChildOption(EpollChannelOption.SO_REUSEPORT, true)
231
    .addService(new GreeterImpl())
232
    .build();
233

234
// Client with epoll
235
ManagedChannel channel = NettyChannelBuilder.forAddress("localhost", 9090)
236
    .channelType(EpollSocketChannel.class)
237
    .eventLoopGroup(new EpollEventLoopGroup())
238
    .usePlaintext()
239
    .build();
240
```
241

242
### Available Native Transports
243

244
| Platform | Transport | Channel Types | Benefits |
245
|----------|-----------|---------------|----------|
246
| Linux | Epoll | `EpollSocketChannel`, `EpollServerSocketChannel` | Better performance, more socket options |  
247
| macOS/BSD | KQueue | `KQueueSocketChannel`, `KQueueServerSocketChannel` | Native BSD socket support |
248
| All | NIO | `NioSocketChannel`, `NioServerSocketChannel` | Cross-platform compatibility |
249
250
## Socket Option Configuration
251

252
### Common Socket Options
253

254
```java
255
import io.netty.channel.ChannelOption;
256

257
// Standard socket options (cross-platform)
258
NettyServerBuilder.forPort(9090)
259
    .withChildOption(ChannelOption.TCP_NODELAY, true)
260
    .withChildOption(ChannelOption.SO_KEEPALIVE, true)
261
    .withChildOption(ChannelOption.SO_SNDBUF, 65536)
262
    .withChildOption(ChannelOption.SO_RCVBUF, 65536)
263
    .withChildOption(ChannelOption.CONNECT_TIMEOUT_MILLIS, 10000);
264
```
265

266
### Linux-Specific Options
267

268
```java
269
import io.netty.channel.epoll.EpollChannelOption;
270

271
// Linux epoll-specific options
272
.withChildOption(EpollChannelOption.TCP_CORK, false)
273
.withChildOption(EpollChannelOption.TCP_QUICKACK, true)
274
.withChildOption(EpollChannelOption.SO_REUSEPORT, true)
275
.withChildOption(EpollChannelOption.TCP_FASTOPEN, 3)
276
```
277

278
## Troubleshooting Socket Issues
279

280
### Check Native Transport Availability
281

282
```java
283
import io.netty.channel.epoll.Epoll;
284
import io.netty.channel.kqueue.KQueue;
285

286
System.out.println("Epoll available: " + Epoll.isAvailable());
287
if (!Epoll.isAvailable()) {
288
    System.out.println("Epoll unavailability cause: " + Epoll.unavailabilityCause());
289
}
290

291
System.out.println("KQueue available: " + KQueue.isAvailable());
292
if (!KQueue.isAvailable()) {
293
    System.out.println("KQueue unavailability cause: " + KQueue.unavailabilityCause());
294
}
295
```
296

297
### Debug Socket Configuration
298

299
```java
300
// Enable Netty logging
301
System.setProperty("io.netty.leakDetection.level", "paranoid");
302
System.setProperty("io.netty.leakDetection.targetRecords", "20");
303

304
// Log socket option configuration
305
Logger logger = LoggerFactory.getLogger("socket.config");
306
logger.info("Configuring socket options...");
307
```
308

309
## Best Practices
310

311
1. **Use Native Transports**: Enable epoll on Linux, kqueue on macOS for better performance
312
2. **Monitor Sparingly**: Socket monitoring has overhead, use judiciously
313
3. **Platform-Specific Tuning**: Configure platform-specific options for optimal performance
314
4. **Resource Management**: Properly shut down custom event loop groups
315
5. **Testing**: Test with different transports to verify compatibility
316
6. **Documentation**: Document native transport requirements for deployment