0
# Network Transport
1
2
The network transport layer provides high-performance Netty-based communication with cluster servers including connection management, reconnection logic, and request/response processing.
3
4
## Capabilities
5
6
### NettyTransportClient
7
8
Low-level transport client that handles the actual network communication with cluster servers using Netty.
9
10
```java { .api }
11
/**
12
* Netty-based transport client for cluster server communication
13
*/
14
public class NettyTransportClient implements ClusterTransportClient {
15
/**
16
* Create transport client for specified server
17
* @param host server hostname or IP address (must not be blank)
18
* @param port server port number (must be > 0)
19
*/
20
public NettyTransportClient(String host, int port);
21
22
/**
23
* Start the transport client and establish connection
24
* @throws Exception if connection setup fails
25
*/
26
public void start() throws Exception;
27
28
/**
29
* Stop the transport client and close connections
30
* @throws Exception if shutdown fails
31
*/
32
public void stop() throws Exception;
33
34
/**
35
* Check if transport client is ready to send requests
36
* @return true if connected and ready, false otherwise
37
*/
38
public boolean isReady();
39
40
/**
41
* Send cluster request and wait for response
42
* @param request cluster request to send (must not be null with valid type)
43
* @return cluster response from server
44
* @throws Exception if request fails or times out
45
*/
46
public ClusterResponse sendRequest(ClusterRequest request) throws Exception;
47
}
48
```
49
50
**Usage Examples:**
51
52
```java
53
import com.alibaba.csp.sentinel.cluster.client.NettyTransportClient;
54
import com.alibaba.csp.sentinel.cluster.request.ClusterRequest;
55
import com.alibaba.csp.sentinel.cluster.response.ClusterResponse;
56
import com.alibaba.csp.sentinel.cluster.ClusterConstants;
57
58
// Create and start transport client
59
NettyTransportClient client = new NettyTransportClient("cluster-server", 8719);
60
try {
61
client.start();
62
63
// Wait for connection to be established
64
while (!client.isReady()) {
65
Thread.sleep(100);
66
}
67
68
// Send ping request
69
ClusterRequest pingRequest = new ClusterRequest<>(ClusterConstants.MSG_TYPE_PING, null);
70
ClusterResponse response = client.sendRequest(pingRequest);
71
72
if (response.getStatus() == ClusterConstants.RESPONSE_STATUS_SUCCESS) {
73
System.out.println("Ping successful");
74
}
75
76
} finally {
77
client.stop();
78
}
79
```
80
81
### Connection Management
82
83
The transport client automatically handles connection lifecycle and recovery.
84
85
**Connection States:**
86
- **CLIENT_STATUS_OFF**: Client is stopped or not connected
87
- **CLIENT_STATUS_PENDING**: Client is attempting to connect (used internally)
88
- **CLIENT_STATUS_STARTED**: Client is connected and ready
89
90
Note: The DefaultClusterTokenClient's getState() method simplifies the transport client state to only OFF or STARTED, but internally the transport client uses PENDING during connection attempts.
91
92
**Connection Features:**
93
94
```java
95
// Automatic reconnection with exponential backoff
96
public static final int RECONNECT_DELAY_MS = 2000; // Base reconnection delay
97
98
// Connection monitoring
99
if (client.isReady()) {
100
// Safe to send requests
101
ClusterResponse response = client.sendRequest(request);
102
} else {
103
// Client not ready - connection may be establishing
104
System.out.println("Client not ready for requests");
105
}
106
```
107
108
**Reconnection Behavior:**
109
110
```java
111
// The client automatically reconnects with increasing delays:
112
// First failure: reconnect after 2 seconds
113
// Second failure: reconnect after 4 seconds
114
// Third failure: reconnect after 6 seconds
115
// etc.
116
117
// Reconnection can be controlled by stopping the client
118
client.stop(); // Disables automatic reconnection
119
client.start(); // Re-enables reconnection
120
```
121
122
### Request Processing
123
124
The transport client handles synchronous request/response communication with timeout support.
125
126
**Request Flow:**
127
1. Validate request parameters
128
2. Generate unique request ID
129
3. Send request over network
130
4. Wait for response with timeout
131
5. Return response or throw timeout exception
132
133
**Error Handling:**
134
135
```java
136
try {
137
ClusterResponse response = client.sendRequest(request);
138
// Process successful response
139
} catch (SentinelClusterException e) {
140
if (e.getMessage().contains("REQUEST_TIME_OUT")) {
141
System.err.println("Request timed out");
142
} else if (e.getMessage().contains("CLIENT_NOT_READY")) {
143
System.err.println("Client not connected");
144
} else if (e.getMessage().contains("BAD_REQUEST")) {
145
System.err.println("Invalid request format");
146
}
147
} catch (Exception e) {
148
System.err.println("Network error: " + e.getMessage());
149
}
150
```
151
152
### Network Configuration
153
154
The transport client uses optimized Netty settings for cluster communication.
155
156
**Netty Configuration:**
157
- **Channel Type**: NioSocketChannel for non-blocking I/O
158
- **TCP_NODELAY**: Enabled for low latency
159
- **Connection Pooling**: PooledByteBufAllocator for efficient memory management
160
- **Frame Encoding**: Length-field based framing for reliable message boundaries
161
162
**Timeout Configuration:**
163
164
```java
165
import com.alibaba.csp.sentinel.cluster.client.config.ClusterClientConfigManager;
166
167
// Connection timeout (from config)
168
int connectTimeout = ClusterClientConfigManager.getConnectTimeout();
169
170
// Request timeout (from config)
171
int requestTimeout = ClusterClientConfigManager.getRequestTimeout();
172
173
// These timeouts are automatically applied by the transport client
174
```
175
176
### Pipeline Configuration
177
178
The Netty pipeline includes several handlers for request/response processing:
179
180
**Pipeline Components:**
181
1. **LengthFieldBasedFrameDecoder**: Handles message framing
182
2. **NettyResponseDecoder**: Decodes incoming responses
183
3. **LengthFieldPrepender**: Adds length headers to outgoing messages
184
4. **NettyRequestEncoder**: Encodes outgoing requests
185
5. **TokenClientHandler**: Manages request/response correlation
186
187
### Request Correlation Management
188
189
The transport client uses a promise-based system to correlate asynchronous requests and responses.
190
191
```java { .api }
192
/**
193
* Utility for managing request/response correlation using Netty promises
194
*/
195
public final class TokenClientPromiseHolder {
196
/**
197
* Store a promise for a request ID
198
* @param xid unique request ID
199
* @param promise Netty channel promise for the request
200
*/
201
public static void putPromise(int xid, ChannelPromise promise);
202
203
/**
204
* Get promise entry for a request ID
205
* @param xid unique request ID
206
* @return entry containing promise and response, or null if not found
207
*/
208
public static SimpleEntry<ChannelPromise, ClusterResponse> getEntry(int xid);
209
210
/**
211
* Remove promise entry for a request ID
212
* @param xid unique request ID to remove
213
*/
214
public static void remove(int xid);
215
216
/**
217
* Complete a promise with response data
218
* @param xid unique request ID
219
* @param response cluster response to associate with promise
220
* @return true if promise was completed successfully
221
*/
222
public static <T> boolean completePromise(int xid, ClusterResponse<T> response);
223
}
224
```
225
226
### Thread Safety
227
228
The `NettyTransportClient` is thread-safe for concurrent request sending, but each client instance should only be started and stopped from a single thread.
229
230
**Safe Concurrent Usage:**
231
232
```java
233
NettyTransportClient client = new NettyTransportClient("server", 8719);
234
client.start();
235
236
// Multiple threads can safely send requests concurrently
237
ExecutorService executor = Executors.newFixedThreadPool(10);
238
for (int i = 0; i < 100; i++) {
239
final int requestId = i;
240
executor.submit(() -> {
241
try {
242
ClusterRequest request = createRequest(requestId);
243
ClusterResponse response = client.sendRequest(request);
244
processResponse(response);
245
} catch (Exception e) {
246
handleError(e);
247
}
248
});
249
}
250
251
executor.shutdown();
252
client.stop();
253
```
254
255
### Resource Management
256
257
The transport client properly manages network resources and cleanup.
258
259
**Resource Cleanup:**
260
- Netty EventLoopGroup shutdown
261
- Channel closure and cleanup
262
- Connection pool resource release
263
- Request correlation cleanup
264
265
**Proper Shutdown:**
266
267
```java
268
NettyTransportClient client = new NettyTransportClient("server", 8719);
269
try {
270
client.start();
271
// Use client for requests
272
} finally {
273
// Always stop client to release resources
274
client.stop();
275
}
276
277
// Or with try-with-resources pattern (if implementing AutoCloseable)
278
// Currently NettyTransportClient does not implement AutoCloseable
279
```
280
281
### Performance Considerations
282
283
**Connection Reuse:**
284
- Create one transport client per target server
285
- Reuse client instances across multiple requests
286
- Avoid creating new clients for each request
287
288
**Request Batching:**
289
- Send multiple requests concurrently rather than sequentially
290
- Use connection pooling for high-throughput scenarios
291
- Monitor connection state before sending requests
292
293
**Memory Management:**
294
- Uses pooled ByteBuf allocators for efficient memory usage
295
- Automatic cleanup of request correlation data
296
- Proper resource disposal on client shutdown