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
```