0
# Server Builders
1

2
High-level builders for creating secure gRPC servers with ALTS authentication.
3

4
## Required Imports
5

6
```java
7
import io.grpc.alts.AltsServerBuilder;
8
import io.grpc.Server;
9
import io.grpc.BindableService;
10
import io.grpc.ServerServiceDefinition;
11
import io.grpc.ServerInterceptor;
12
import io.grpc.ServerStreamTracer;
13
import io.grpc.ServerTransportFilter;
14
import io.grpc.HandlerRegistry;
15
import io.grpc.CompressorRegistry;
16
import io.grpc.DecompressorRegistry;
17
import java.io.File;
18
import java.util.concurrent.Executor;
19
import java.util.concurrent.TimeUnit;
20
```
21

22
## Capabilities
23

24
### ALTS Server Builder
25

26
Creates a gRPC server that accepts ALTS-secured connections from authenticated Google Cloud VMs.
27

28
```java { .api }
29
/**
30
 * gRPC secure server builder used for ALTS. Adds necessary ALTS support to create
31
 * a production server on Google Cloud Platform.
32
 */
33
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/4151")
34
public final class AltsServerBuilder extends ForwardingServerBuilder<AltsServerBuilder> {
35
    
36
    /**
37
     * Creates a gRPC server builder for the given port
38
     * @param port the port number to bind to
39
     * @return AltsServerBuilder instance
40
     */
41
    public static AltsServerBuilder forPort(int port);
42
    
43
    /**
44
     * Enables untrusted ALTS for testing. Disables Google Cloud Platform checks.
45
     * @return this builder for chaining
46
     */
47
    public AltsServerBuilder enableUntrustedAltsForTesting();
48
    
49
    /**
50
     * Sets a custom handshaker service address for testing
51
     * @param handshakerAddress the handshaker service address
52
     * @return this builder for chaining
53
     */
54
    public AltsServerBuilder setHandshakerAddressForTesting(String handshakerAddress);
55
    
56
    /**
57
     * Sets the handshake timeout
58
     * @param timeout the timeout value
59
     * @param unit the time unit
60
     * @return this builder for chaining
61
     */
62
    public AltsServerBuilder handshakeTimeout(long timeout, TimeUnit unit);
63
    
64
    /**
65
     * Uses the direct executor for server operations
66
     * @return this builder for chaining
67
     */
68
    public AltsServerBuilder directExecutor();
69
    
70
    /**
71
     * Adds a stream tracer factory
72
     * @param factory the stream tracer factory
73
     * @return this builder for chaining
74
     */
75
    public AltsServerBuilder addStreamTracerFactory(ServerStreamTracer.Factory factory);
76
    
77
    /**
78
     * Adds a transport filter
79
     * @param filter the transport filter
80
     * @return this builder for chaining
81
     */
82
    public AltsServerBuilder addTransportFilter(ServerTransportFilter filter);
83
    
84
    /**
85
     * Sets the executor for server operations
86
     * @param executor the executor
87
     * @return this builder for chaining
88
     */
89
    public AltsServerBuilder executor(Executor executor);
90
    
91
    /**
92
     * Adds a service definition
93
     * @param service the service definition
94
     * @return this builder for chaining
95
     */
96
    public AltsServerBuilder addService(ServerServiceDefinition service);
97
    
98
    /**
99
     * Adds a bindable service implementation
100
     * @param bindableService the bindable service
101
     * @return this builder for chaining
102
     */
103
    public AltsServerBuilder addService(BindableService bindableService);
104
    
105
    /**
106
     * Sets the fallback handler registry
107
     * @param fallbackRegistry the fallback handler registry
108
     * @return this builder for chaining
109
     */
110
    public AltsServerBuilder fallbackHandlerRegistry(HandlerRegistry fallbackRegistry);
111
    
112
    /**
113
     * Sets the decompressor registry
114
     * @param registry the decompressor registry
115
     * @return this builder for chaining
116
     */
117
    public AltsServerBuilder decompressorRegistry(DecompressorRegistry registry);
118
    
119
    /**
120
     * Sets the compressor registry
121
     * @param registry the compressor registry
122
     * @return this builder for chaining
123
     */
124
    public AltsServerBuilder compressorRegistry(CompressorRegistry registry);
125
    
126
    /**
127
     * Adds a server interceptor
128
     * @param interceptor the server interceptor
129
     * @return this builder for chaining
130
     */
131
    public AltsServerBuilder intercept(ServerInterceptor interceptor);
132
    
133
    /**
134
     * Attempts to set TLS transport security. Not supported for ALTS servers.
135
     * @param certChain the certificate chain file
136
     * @param privateKey the private key file
137
     * @return this builder (never reached)
138
     * @throws UnsupportedOperationException always thrown - TLS configuration not supported for ALTS
139
     */
140
    public AltsServerBuilder useTransportSecurity(File certChain, File privateKey);
141
    
142
    /**
143
     * Builds the server with ALTS security
144
     * @return the configured Server
145
     */
146
    public Server build();
147
}
148
```
149

150
**Usage Examples:**
151

152
```java
153
import io.grpc.alts.AltsServerBuilder;
154
import io.grpc.Server;
155
import io.grpc.BindableService;
156

157
// Basic ALTS server
158
Server server = AltsServerBuilder.forPort(8080)
159
    .addService(new MyServiceImpl())
160
    .build();
161

162
server.start();
163
server.awaitTermination();
164

165
// Advanced ALTS server configuration
166
Server advancedServer = AltsServerBuilder.forPort(8080)
167
    .addService(new MyServiceImpl())
168
    .addService(new AnotherServiceImpl())
169
    .handshakeTimeout(30, TimeUnit.SECONDS)
170
    .executor(Executors.newFixedThreadPool(10))
171
    .intercept(new LoggingInterceptor())
172
    .addTransportFilter(new CustomTransportFilter())
173
    .build();
174

175
// Testing configuration
176
Server testServer = AltsServerBuilder.forPort(8080)
177
    .addService(new TestServiceImpl())
178
    .enableUntrustedAltsForTesting()
179
    .setHandshakerAddressForTesting("localhost:9999")
180
    .build();
181
```
182

183
## Server Configuration
184

185
### Service Registration
186

187
Add your gRPC service implementations using either:
188
- `addService(ServerServiceDefinition)` for pre-built service definitions
189
- `addService(BindableService)` for service implementations
190

191
### Execution Control
192

193
Configure how the server handles requests:
194
- `executor(Executor)` - Custom thread pool for request processing
195
- `directExecutor()` - Process requests on the network threads (for low-latency scenarios)
196

197
### Interceptors and Filters
198

199
Add cross-cutting concerns:
200
- `intercept(ServerInterceptor)` - Add interceptors for logging, authentication, etc.
201
- `addTransportFilter(ServerTransportFilter)` - Add transport-level filters
202
- `addStreamTracerFactory(ServerStreamTracer.Factory)` - Add stream tracing
203

204
### Compression
205

206
Configure message compression:
207
- `compressorRegistry(CompressorRegistry)` - Set available compressors
208
- `decompressorRegistry(DecompressorRegistry)` - Set available decompressors
209

210
### Timeouts
211

212
Configure connection timeouts:
213
- `handshakeTimeout(long, TimeUnit)` - Set ALTS handshake timeout
214

215
## Server Lifecycle
216

217
```java
218
import io.grpc.alts.AltsServerBuilder;
219
import io.grpc.Server;
220

221
// Build and start server
222
Server server = AltsServerBuilder.forPort(8080)
223
    .addService(new MyServiceImpl())
224
    .build();
225

226
// Start the server
227
server.start();
228
System.out.println("Server started on port 8080");
229

230
// Add shutdown hook for graceful termination
231
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
232
    System.out.println("Shutting down server...");
233
    server.shutdown();
234
    try {
235
        server.awaitTermination(5, TimeUnit.SECONDS);
236
    } catch (InterruptedException e) {
237
        server.shutdownNow();
238
    }
239
}));
240

241
// Wait for termination
242
server.awaitTermination();
243
```
244

245
## Security Considerations
246

247
- **ALTS Only**: The server only accepts ALTS-secured connections from authenticated Google Cloud VMs
248
- **No TLS Configuration**: ALTS servers cannot use TLS transport security - calling `useTransportSecurity()` will throw `UnsupportedOperationException`
249
- **Mutual Authentication**: Both client and server identities are verified during the handshake
250
- **Testing**: Never use testing methods (`enableUntrustedAltsForTesting()`) in production environments
251
- **Port Binding**: Choose appropriate ports that don't conflict with other services
252
- **Service Accounts**: Clients must use valid Google Cloud service accounts to connect