0
# Transport Providers
1

2
Automatic discovery and registration of Netty transport providers for gRPC, including Unix Domain Socket support and internal configuration APIs. The provider system enables automatic transport selection and configuration through Java's ServiceLoader mechanism.
3

4
## Capabilities
5

6
### NettyChannelProvider
7

8
Provider for Netty-based gRPC client channels with automatic discovery and configuration.
9

10
```java { .api }
11
/**
12
 * Check if the Netty channel provider is available
13
 * @return true if Netty transport is available
14
 */
15
public boolean isAvailable();
16

17
/**
18
 * Get the priority of this provider (higher values have higher priority)
19
 * @return Provider priority value
20
 */
21
public int priority();
22

23
/**
24
 * Create a channel builder for the specified address
25
 * @param name Host name
26
 * @param port Port number
27
 * @return NettyChannelBuilder for the address
28
 */
29
public NettyChannelBuilder builderForAddress(String name, int port);
30

31
/**
32
 * Create a channel builder for the specified target
33
 * @param target Target string (e.g., "dns:///service.com:443")
34
 * @return NettyChannelBuilder for the target
35
 */
36
public NettyChannelBuilder builderForTarget(String target);
37

38
/**
39
 * Create a new channel builder with credentials
40
 * @param target Target string
41
 * @param creds Channel credentials
42
 * @return Result containing the channel builder
43
 */
44
public NewChannelBuilderResult newChannelBuilder(String target, ChannelCredentials creds);
45
```
46

47
**Usage Example:**
48

49
```java
50
import io.grpc.netty.shaded.io.grpc.netty.NettyChannelProvider;
51

52
NettyChannelProvider provider = new NettyChannelProvider();
53

54
if (provider.isAvailable()) {
55
    NettyChannelBuilder builder = provider.builderForAddress("localhost", 9090);
56
    ManagedChannel channel = builder.build();
57
}
58
```
59

60
### NettyServerProvider
61

62
Provider for Netty-based gRPC servers with automatic discovery and configuration.
63

64
```java { .api }
65
/**
66
 * Check if the Netty server provider is available
67
 * @return true if Netty server transport is available
68
 */
69
protected boolean isAvailable();
70

71
/**
72
 * Get the priority of this provider (higher values have higher priority)
73
 * @return Provider priority value
74
 */
75
protected int priority();
76

77
/**
78
 * Create a server builder for the specified port
79
 * @param port Port number to listen on
80
 * @return NettyServerBuilder for the port
81
 */
82
protected NettyServerBuilder builderForPort(int port);
83

84
/**
85
 * Create a new server builder with credentials
86
 * @param port Port number to listen on
87
 * @param creds Server credentials
88
 * @return Result containing the server builder
89
 */
90
protected NewServerBuilderResult newServerBuilderForPort(int port, ServerCredentials creds);
91
```
92

93
**Usage Example:**
94

95
```java
96
import io.grpc.netty.shaded.io.grpc.netty.NettyServerProvider;
97

98
NettyServerProvider provider = new NettyServerProvider();
99

100
if (provider.isAvailable()) {
101
    NettyServerBuilder builder = provider.builderForPort(9090);
102
    Server server = builder.addService(new MyServiceImpl()).build();
103
}
104
```
105

106
### UdsNettyChannelProvider
107

108
Provider for Unix Domain Socket channels using Netty transport.
109

110
```java { .api }
111
/**
112
 * Check if Unix Domain Socket transport is available
113
 * @return true if UDS transport is available
114
 */
115
public boolean isAvailable();
116

117
/**
118
 * Get the priority of this provider
119
 * @return Provider priority value
120
 */
121
public int priority();
122

123
/**
124
 * Create a channel builder for the specified address (UDS specific)
125
 * @param name Socket path or identifier
126
 * @param port Port number (may be ignored for UDS)
127
 * @return NettyChannelBuilder configured for UDS
128
 */
129
public NettyChannelBuilder builderForAddress(String name, int port);
130

131
/**
132
 * Create a channel builder for the specified target (UDS specific)
133
 * @param target Target string (e.g., "unix:///path/to/socket")
134
 * @return NettyChannelBuilder configured for UDS
135
 */
136
public NettyChannelBuilder builderForTarget(String target);
137

138
/**
139
 * Create a new UDS channel builder with credentials
140
 * @param target Target string
141
 * @param creds Channel credentials
142
 * @return Result containing the channel builder
143
 */
144
public NewChannelBuilderResult newChannelBuilder(String target, ChannelCredentials creds);
145
```
146

147
**Usage Example:**
148

149
```java
150
import io.grpc.netty.shaded.io.grpc.netty.UdsNettyChannelProvider;
151

152
UdsNettyChannelProvider udsProvider = new UdsNettyChannelProvider();
153

154
if (udsProvider.isAvailable()) {
155
    NettyChannelBuilder builder = udsProvider.builderForTarget("unix:///tmp/grpc.sock");
156
    ManagedChannel channel = builder.build();
157
}
158
```
159

160
### UdsNameResolverProvider
161

162
Name resolver provider for Unix Domain Socket addresses.
163

164
```java { .api }
165
/**
166
 * Check if UDS name resolution is available
167
 * @return true if UDS name resolution is supported
168
 */
169
public boolean isAvailable();
170

171
/**
172
 * Get the priority of this name resolver provider
173
 * @return Provider priority value
174
 */
175
public int priority();
176

177
/**
178
 * Get the default URI scheme for UDS
179
 * @return Default scheme string (typically "unix")
180
 */
181
public String getDefaultScheme();
182

183
/**
184
 * Create a name resolver for the given URI
185
 * @param targetUri Target URI to resolve
186
 * @param args Name resolver arguments
187
 * @return NameResolver for the URI or null if not supported
188
 */
189
public NameResolver newNameResolver(URI targetUri, NameResolver.Args args);
190
```
191

192
**Usage Example:**
193

194
```java
195
import io.grpc.netty.shaded.io.grpc.netty.UdsNameResolverProvider;
196
import java.net.URI;
197

198
UdsNameResolverProvider resolver = new UdsNameResolverProvider();
199

200
if (resolver.isAvailable()) {
201
    URI uri = URI.create("unix:///tmp/grpc.sock");
202
    NameResolver nameResolver = resolver.newNameResolver(uri, args);
203
}
204
```
205

206
## Internal Provider APIs
207

208
### InternalNettyChannelBuilder
209

210
Internal API for advanced channel builder configuration and transport factory creation.
211

212
```java { .api }
213
/**
214
 * Disable authority checking for the channel
215
 * @param builder The NettyChannelBuilder to configure
216
 */
217
public static void disableCheckAuthority(NettyChannelBuilder builder);
218

219
/**
220
 * Enable authority checking for the channel
221
 * @param builder The NettyChannelBuilder to configure
222
 */
223
public static void enableCheckAuthority(NettyChannelBuilder builder);
224

225
/**
226
 * Set a protocol negotiator factory
227
 * @param builder The NettyChannelBuilder to configure
228
 * @param protocolNegotiator The protocol negotiator factory
229
 */
230
public static void setProtocolNegotiatorFactory(
231
    NettyChannelBuilder builder, 
232
    ProtocolNegotiatorFactory protocolNegotiator);
233

234
/**
235
 * Set statistics collection enabled/disabled
236
 * @param builder The NettyChannelBuilder to configure
237
 * @param value Whether to enable stats collection
238
 */
239
public static void setStatsEnabled(NettyChannelBuilder builder, boolean value);
240

241
/**
242
 * Set tracing enabled/disabled
243
 * @param builder The NettyChannelBuilder to configure
244
 * @param value Whether to enable tracing
245
 */
246
public static void setTracingEnabled(NettyChannelBuilder builder, boolean value);
247

248
/**
249
 * Build the underlying transport factory
250
 * @param builder The configured NettyChannelBuilder
251
 * @return ClientTransportFactory for the configuration
252
 */
253
public static ClientTransportFactory buildTransportFactory(NettyChannelBuilder builder);
254
```
255

256
### InternalNettyServerBuilder
257

258
Internal API for advanced server builder configuration.
259

260
```java { .api }
261
// Various internal configuration methods for advanced server setup
262
// (specific methods vary based on internal gRPC requirements)
263
```
264

265
### Internal Credentials
266

267
Internal credential factories for custom protocol negotiators.
268

269
```java { .api }
270
/**
271
 * Create channel credentials from a protocol negotiator factory
272
 * @param factory The protocol negotiator factory
273
 * @return ChannelCredentials using the factory
274
 */
275
public static ChannelCredentials create(ProtocolNegotiator.ClientFactory factory);
276

277
/**
278
 * Create server credentials from a protocol negotiator factory
279
 * @param factory The protocol negotiator factory
280
 * @return ServerCredentials using the factory
281
 */
282
public static ServerCredentials create(ProtocolNegotiator.ServerFactory factory);
283
```
284

285
## Automatic Provider Discovery
286

287
The gRPC library automatically discovers and uses transport providers through Java's ServiceLoader mechanism. The Netty providers register themselves and are selected based on availability and priority.
288

289
**Usage Example - Automatic Discovery:**
290

291
```java
292
import io.grpc.Grpc;
293
import io.grpc.InsecureChannelCredentials;
294
import io.grpc.InsecureServerCredentials;
295

296
// gRPC automatically selects the best available transport provider
297
// (will use Netty if available due to higher priority)
298

299
ManagedChannel channel = Grpc.newChannelBuilder(
300
    "localhost:9090", 
301
    InsecureChannelCredentials.create()
302
).build(); // Automatically uses NettyChannelBuilder
303

304
Server server = Grpc.newServerBuilderForPort(
305
    9090, 
306
    InsecureServerCredentials.create()
307
).build(); // Automatically uses NettyServerBuilder
308
```
309

310
## Provider Priority System
311

312
Transport providers are ranked by priority, with higher values taking precedence:
313

314
1. **NettyChannelProvider** - High priority for standard TCP connections
315
2. **UdsNettyChannelProvider** - Specialized priority for Unix Domain Socket connections  
316
3. **NettyServerProvider** - High priority for standard TCP servers
317

318
The priority system ensures that:
319
- Netty transport is preferred over other transports when available
320
- UDS transport is used for `unix://` URIs
321
- Fallback to other transports occurs if Netty is unavailable
322

323
## Provider Result Types
324

325
```java { .api }
326
/**
327
 * Result of creating a new channel builder
328
 */
329
public static class NewChannelBuilderResult {
330
    private final ManagedChannelBuilder<?> channelBuilder;
331
    private final boolean intercepted;
332
    
333
    // Getters and construction methods
334
}
335

336
/**
337
 * Result of creating a new server builder  
338
 */
339
public static class NewServerBuilderResult {
340
    private final ServerBuilder<?> serverBuilder;
341
    private final boolean intercepted;
342
    
343
    // Getters and construction methods
344
}
345
```
346

347
## Platform-Specific Considerations
348

349
### Linux
350
- Full support for epoll transport
351
- Native TCP optimization
352
- Unix Domain Socket support
353

354
### macOS  
355
- kqueue transport support
356
- Unix Domain Socket support
357
- Native library compatibility
358

359
### Windows
360
- NIO transport (epoll/kqueue not available)
361
- Named pipe support varies
362
- TCP optimization through native libraries
363

364
The provider system automatically selects the best available transport for each platform.