0
# Quarkus gRPC Extension
1
2
The Quarkus gRPC extension enables implementing and consuming gRPC services within the Quarkus framework. It provides seamless integration with Quarkus's reactive engine, supporting both imperative and reactive programming models with Mutiny integration. The extension enables efficient, type-safe communication between microservices using HTTP/2, TLS, and Protocol Buffers.
3
4
## Package Information
5
6
- **Package Name**: quarkus-grpc
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to Maven `pom.xml`
10
11
Maven:
12
```xml
13
<dependency>
14
<groupId>io.quarkus</groupId>
15
<artifactId>quarkus-grpc</artifactId>
16
</dependency>
17
```
18
19
Gradle:
20
```gradle
21
implementation 'io.quarkus:quarkus-grpc'
22
```
23
24
## Core Imports
25
26
```java
27
import io.quarkus.grpc.GrpcService;
28
import io.quarkus.grpc.GrpcClient;
29
import io.quarkus.grpc.MutinyService;
30
import io.quarkus.grpc.MutinyClient;
31
import jakarta.inject.Inject;
32
```
33
34
## Basic Usage
35
36
### Implementing a gRPC Service
37
38
```java
39
import io.quarkus.grpc.GrpcService;
40
import io.smallrye.mutiny.Uni;
41
42
@GrpcService
43
public class GreetingService implements MutinyService {
44
45
public Uni<HelloReply> sayHello(HelloRequest request) {
46
return Uni.createFrom().item(
47
HelloReply.newBuilder()
48
.setMessage("Hello " + request.getName())
49
.build()
50
);
51
}
52
}
53
```
54
55
### Consuming a gRPC Service
56
57
```java
58
import io.quarkus.grpc.GrpcClient;
59
import io.smallrye.mutiny.Uni;
60
import jakarta.inject.Inject;
61
62
public class GreetingClient {
63
64
@Inject
65
@GrpcClient("greeting")
66
MutinyGreetingGrpc client;
67
68
public Uni<HelloReply> greet(String name) {
69
HelloRequest request = HelloRequest.newBuilder()
70
.setName(name)
71
.build();
72
return client.sayHello(request);
73
}
74
}
75
```
76
77
## Architecture
78
79
The Quarkus gRPC extension is built around several key components:
80
81
- **Service Annotations**: `@GrpcService` for implementing gRPC services, `@GrpcClient` for injecting gRPC clients
82
- **Mutiny Integration**: Full reactive programming support with `Uni` and `Multi` types for non-blocking operations
83
- **Code Generation**: Automatic generation of Mutiny-based client and service interfaces from protobuf definitions
84
- **Interceptor Support**: Global and service-specific interceptors for cross-cutting concerns
85
- **Exception Handling**: Customizable exception transformation and error handling mechanisms
86
- **Configuration System**: Comprehensive configuration for servers, clients, TLS, and other options
87
- **Development Support**: Hot reload, reflection support, and in-process testing capabilities
88
89
## Capabilities
90
91
### Service Implementation
92
93
Core functionality for implementing gRPC services with reactive programming support. Services are implemented as CDI beans with automatic lifecycle management.
94
95
```java { .api }
96
@Target({ FIELD, PARAMETER, TYPE })
97
@Retention(RUNTIME)
98
@Qualifier
99
public @interface GrpcService {
100
}
101
102
public interface MutinyService {
103
}
104
```
105
106
[Service Implementation](./service-implementation.md)
107
108
### Client Injection and Usage
109
110
Client functionality for consuming gRPC services with reactive programming support and configuration management.
111
112
```java { .api }
113
@Target({ FIELD, PARAMETER })
114
@Retention(RUNTIME)
115
@Qualifier
116
public @interface GrpcClient {
117
String value() default ELEMENT_NAME;
118
String ELEMENT_NAME = "<<element name>>";
119
}
120
121
public interface MutinyClient<T extends AbstractStub<T>> {
122
T getStub();
123
MutinyClient<T> newInstanceWithStub(T stub);
124
}
125
```
126
127
[Client Usage](./client-usage.md)
128
129
### Interceptor Registration
130
131
Interceptor system for implementing cross-cutting concerns like authentication, logging, and metrics across gRPC services and clients.
132
133
```java { .api }
134
@Target({ FIELD, PARAMETER, TYPE, METHOD })
135
@Retention(RUNTIME)
136
public @interface GlobalInterceptor {
137
}
138
139
@Target(TYPE)
140
@Retention(RUNTIME)
141
@Repeatable(RegisterInterceptors.class)
142
public @interface RegisterInterceptor {
143
Class<? extends ServerInterceptor> value();
144
}
145
```
146
147
[Interceptors](./interceptors.md)
148
149
### Exception Handling
150
151
Comprehensive exception handling system with customizable error transformation and gRPC status code mapping.
152
153
```java { .api }
154
public abstract class ExceptionHandler<ReqT, RespT> extends
155
ForwardingServerCallListener.SimpleForwardingServerCallListener<ReqT> {
156
157
protected abstract void handleException(
158
Throwable t,
159
ServerCall<ReqT, RespT> call,
160
Metadata metadata
161
);
162
}
163
164
public interface ExceptionHandlerProvider {
165
<ReqT, RespT> ExceptionHandler<ReqT, RespT> createHandler(
166
Listener<ReqT> listener,
167
ServerCall<ReqT, RespT> serverCall,
168
Metadata metadata
169
);
170
}
171
```
172
173
[Exception Handling](./exception-handling.md)
174
175
### Reactive Streaming
176
177
Low-level reactive streaming utilities for implementing custom gRPC call patterns with Mutiny integration.
178
179
```java { .api }
180
public class ServerCalls {
181
public static <I, O> void oneToOne(
182
I request,
183
StreamObserver<O> response,
184
String compression,
185
Function<I, Uni<O>> implementation
186
);
187
188
public static <I, O> void oneToMany(
189
I request,
190
StreamObserver<O> response,
191
String compression,
192
Function<I, Multi<O>> implementation
193
);
194
}
195
```
196
197
[Reactive Streaming](./reactive-streaming.md)
198
199
### Configuration and Customization
200
201
Server and client configuration with customization hooks for advanced use cases including TLS, load balancing, and performance tuning.
202
203
```java { .api }
204
public interface ServerBuilderCustomizer<T extends ServerBuilder<T>> {
205
default void customize(GrpcServerConfiguration config, T builder);
206
default void customize(GrpcServerConfiguration config, GrpcServerOptions options);
207
default int priority();
208
}
209
210
public interface ChannelBuilderCustomizer<T extends ManagedChannelBuilder<T>> {
211
default Map<String, Object> customize(
212
String name,
213
GrpcClientConfiguration config,
214
T builder
215
);
216
}
217
```
218
219
[Configuration](./configuration.md)
220
221
## Types
222
223
### Core Marker Interfaces
224
225
```java { .api }
226
public interface MutinyGrpc {
227
}
228
229
public interface MutinyBean {
230
}
231
232
public interface MutinyStub {
233
}
234
```
235
236
### Client Utilities
237
238
```java { .api }
239
public class GrpcClientUtils {
240
public static <T> T attachHeaders(T client, Metadata extraHeaders);
241
public static <T> T getProxiedObject(T client);
242
}
243
```
244
245
### Stream Observers
246
247
```java { .api }
248
public class UniStreamObserver<T> implements StreamObserver<T> {
249
}
250
251
public class MultiStreamObserver<T> implements StreamObserver<T> {
252
}
253
254
public class ManyToManyObserver<T> implements StreamObserver<T> {
255
}
256
257
public class ManyToOneObserver<T> implements StreamObserver<T> {
258
}
259
```