0
# Transport Layer
1
2
gRPC Core defines the fundamental transport abstractions that enable different transport implementations (Netty, OkHttp, in-process) to work with the gRPC framework. These interfaces provide contracts for client and server communication.
3
4
## Capabilities
5
6
### Client Transport Interface
7
8
Defines the contract for client-side transport implementations.
9
10
```java { .api }
11
/**
12
* Interface for client-side transport implementations
13
* Located: io.grpc.internal.ClientTransport
14
*/
15
interface ClientTransport extends InternalInstrumented<SocketStats> {
16
/**
17
* Creates a new stream for an RPC call
18
* @param method The method descriptor for the RPC
19
* @param headers Initial metadata/headers for the request
20
* @param callOptions Options for this specific call
21
* @param tracers Array of tracers for monitoring the stream
22
* @return ClientStream instance for this RPC
23
*/
24
ClientStream newStream(
25
MethodDescriptor<?, ?> method,
26
Metadata headers,
27
CallOptions callOptions,
28
ClientStreamTracer[] tracers
29
);
30
31
/**
32
* Ping the remote endpoint to verify connectivity
33
* @param callback Callback to invoke when ping completes
34
* @param executor Executor to run the callback on
35
*/
36
void ping(PingCallback callback, Executor executor);
37
}
38
```
39
40
### Connection Client Transport Interface
41
42
Extended interface for connection-based client transports.
43
44
```java { .api }
45
/**
46
* Interface for connection-based client transports
47
* Located: io.grpc.internal.ConnectionClientTransport
48
*/
49
interface ConnectionClientTransport extends ClientTransport {
50
/**
51
* Initiates shutdown of the transport
52
* @param reason Status indicating reason for shutdown
53
* @return ListenableFuture that completes when shutdown is initiated
54
*/
55
ListenableFuture<Void> shutdown(Status reason);
56
57
/**
58
* Initiates graceful shutdown with specified timeout
59
* @param reason Status indicating reason for shutdown
60
* @param timeout Timeout for graceful shutdown
61
* @param unit Time unit for timeout
62
* @return ListenableFuture that completes when shutdown is complete
63
*/
64
ListenableFuture<Void> shutdownNow(Status reason, long timeout, TimeUnit unit);
65
66
/**
67
* Gets connectivity state of the transport
68
* @return Current connectivity state
69
*/
70
ConnectivityState getConnectivityState();
71
72
/**
73
* Registers a listener for connectivity state changes
74
* @param state State to watch for changes from
75
* @param listener Listener to notify of state changes
76
* @param executor Executor to run listener on
77
*/
78
void notifyWhenStateChanged(
79
ConnectivityState state,
80
Runnable listener,
81
Executor executor
82
);
83
}
84
```
85
86
### Server Transport Interface
87
88
Defines the contract for server-side transport implementations.
89
90
```java { .api }
91
/**
92
* Interface for server-side transport implementations
93
* Located: io.grpc.internal.ServerTransport
94
*/
95
interface ServerTransport {
96
/**
97
* Starts the server transport with the given listener
98
* @param listener Listener for transport events
99
*/
100
void start(ServerTransportListener listener);
101
102
/**
103
* Initiates graceful shutdown of the transport
104
*/
105
void shutdown();
106
107
/**
108
* Initiates immediate shutdown of the transport
109
* @param reason Status indicating reason for shutdown
110
*/
111
void shutdownNow(Status reason);
112
113
/**
114
* Gets the log ID for this transport (for debugging/logging)
115
* @return Unique log ID string
116
*/
117
InternalLogId getLogId();
118
119
/**
120
* Gets the attributes associated with this transport
121
* @return Transport attributes
122
*/
123
Attributes getAttributes();
124
}
125
```
126
127
### Transport Listeners
128
129
Listener interfaces for handling transport events.
130
131
```java { .api }
132
/**
133
* Listener for server transport events
134
* Located: io.grpc.internal.ServerTransportListener
135
*/
136
interface ServerTransportListener {
137
/**
138
* Called when a new stream is created on the transport
139
* @param stream The new server stream
140
* @param method Method descriptor for the RPC
141
* @param headers Initial metadata from the client
142
*/
143
void streamCreated(ServerStream stream, String method, Metadata headers);
144
145
/**
146
* Called when the transport is ready to accept streams
147
* @param attributes Updated transport attributes
148
*/
149
void transportReady(Attributes attributes);
150
151
/**
152
* Called when the transport is shutting down
153
* @param status Status indicating reason for shutdown
154
*/
155
void transportTerminated(Status status);
156
}
157
158
/**
159
* Listener for client transport events
160
* Located: io.grpc.internal.ClientTransportListener
161
*/
162
interface ClientTransportListener {
163
/**
164
* Called when the transport is ready for use
165
*/
166
void transportReady();
167
168
/**
169
* Called when the transport is shutting down
170
* @param status Status indicating reason for shutdown
171
*/
172
void transportShutdown(Status status);
173
174
/**
175
* Called when the transport is completely terminated
176
* @param status Status indicating reason for termination
177
*/
178
void transportTerminated(Status status);
179
180
/**
181
* Called when transport is in use (has active streams)
182
* @param inUse true if transport has active streams
183
*/
184
void transportInUse(boolean inUse);
185
}
186
```
187
188
### Ping Callback Interface
189
190
Callback interface for ping operations.
191
192
```java { .api }
193
/**
194
* Callback for ping operations
195
* Located: io.grpc.internal.ClientTransport.PingCallback
196
*/
197
interface PingCallback {
198
/**
199
* Called when ping operation succeeds
200
* @param roundTripTimeNanos Round trip time in nanoseconds
201
*/
202
void onSuccess(long roundTripTimeNanos);
203
204
/**
205
* Called when ping operation fails
206
* @param cause Status indicating the failure reason
207
*/
208
void onFailure(Status cause);
209
}
210
```
211
212
## Transport Implementations
213
214
### Delayed Client Transport
215
216
Special transport implementation that queues operations until the actual transport is ready.
217
218
```java { .api }
219
/**
220
* Transport that delays operations until ready
221
* Located: io.grpc.internal.DelayedClientTransport
222
*/
223
class DelayedClientTransport implements ClientTransport {
224
/**
225
* Creates a new delayed client transport
226
* @param executor Executor for callback operations
227
* @param syncContext Synchronization context
228
*/
229
public DelayedClientTransport(Executor executor, SynchronizationContext syncContext);
230
231
/**
232
* Sets the real transport once it becomes available
233
* @param transport The actual transport to delegate to
234
*/
235
public final void setTransport(ClientTransport transport);
236
237
/**
238
* Shuts down the transport with the given status
239
* @param status Status indicating shutdown reason
240
* @param errorDescription Optional error description
241
*/
242
public final void shutdownNow(Status status, String errorDescription);
243
244
@Override
245
public ClientStream newStream(
246
MethodDescriptor<?, ?> method,
247
Metadata headers,
248
CallOptions callOptions,
249
ClientStreamTracer[] tracers
250
);
251
252
@Override
253
public void ping(PingCallback callback, Executor executor);
254
}
255
```
256
257
### Forwarding Client Transport
258
259
Base class for transport implementations that delegate to another transport.
260
261
```java { .api }
262
/**
263
* Base class for forwarding client transports
264
* Located: io.grpc.internal.ForwardingClientTransport
265
*/
266
abstract class ForwardingClientTransport implements ClientTransport {
267
/**
268
* Gets the delegate transport
269
* @return The transport to forward calls to
270
*/
271
protected abstract ClientTransport delegate();
272
273
@Override
274
public ClientStream newStream(
275
MethodDescriptor<?, ?> method,
276
Metadata headers,
277
CallOptions callOptions,
278
ClientStreamTracer[] tracers
279
) {
280
return delegate().newStream(method, headers, callOptions, tracers);
281
}
282
283
@Override
284
public void ping(PingCallback callback, Executor executor) {
285
delegate().ping(callback, executor);
286
}
287
}
288
```
289
290
## Transport Usage Patterns
291
292
### Client Transport Lifecycle
293
294
1. **Creation**: Transport factory creates transport for target address
295
2. **Connection**: Transport establishes connection to server
296
3. **Stream Creation**: Client creates streams for RPC calls
297
4. **Communication**: Data flows through streams over transport
298
5. **Shutdown**: Transport gracefully closes connections
299
300
**Example:**
301
302
```java
303
// Transport factory creates transport
304
ClientTransport transport = factory.newClientTransport(serverAddress, options);
305
306
// Create stream for RPC
307
ClientStream stream = transport.newStream(method, headers, callOptions, tracers);
308
309
// Use stream for communication
310
stream.writeMessage(requestMessage);
311
stream.halfClose();
312
313
// Shutdown transport when done
314
if (transport instanceof ConnectionClientTransport) {
315
((ConnectionClientTransport) transport).shutdown(Status.OK);
316
}
317
```
318
319
### Server Transport Lifecycle
320
321
1. **Binding**: Server transport binds to listen address
322
2. **Starting**: Transport starts listening for connections
323
3. **Stream Handling**: Transport creates streams for incoming RPCs
324
4. **Communication**: Data flows through streams over transport
325
5. **Shutdown**: Transport stops accepting new connections and closes existing ones
326
327
**Example:**
328
329
```java
330
// Server transport starts with listener
331
ServerTransportListener listener = new ServerTransportListener() {
332
@Override
333
public void streamCreated(ServerStream stream, String method, Metadata headers) {
334
// Handle new stream
335
ServerStreamListener streamListener = serviceRegistry.lookupMethod(method);
336
stream.setListener(streamListener);
337
}
338
339
@Override
340
public void transportReady(Attributes attributes) {
341
// Transport ready for connections
342
}
343
};
344
345
serverTransport.start(listener);
346
```
347
348
## Error Handling
349
350
Transport layer error handling:
351
352
- **Connection Failures**: Reported via transport listeners with appropriate Status
353
- **Stream Errors**: Individual stream failures don't affect transport
354
- **Protocol Violations**: Result in transport shutdown with PROTOCOL_ERROR status
355
- **Resource Exhaustion**: May trigger flow control or transport shutdown
356
- **Graceful Shutdown**: Allows in-flight RPCs to complete before closing
357
- **Immediate Shutdown**: Cancels all active streams and closes transport