or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-usage.mdconfiguration.mdexception-handling.mdindex.mdinterceptors.mdreactive-streaming.mdservice-implementation.md
tile.json

tessl/maven-io-quarkus--quarkus-grpc

Quarkus gRPC extension that enables implementing and consuming gRPC services with reactive and imperative programming models.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.quarkus/quarkus-grpc@3.23.x

To install, run

npx @tessl/cli install tessl/maven-io-quarkus--quarkus-grpc@3.23.0

index.mddocs/

Quarkus gRPC Extension

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.

Package Information

  • Package Name: quarkus-grpc
  • Package Type: maven
  • Language: Java
  • Installation: Add to Maven pom.xml

Maven:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-grpc</artifactId>
</dependency>

Gradle:

implementation 'io.quarkus:quarkus-grpc'

Core Imports

import io.quarkus.grpc.GrpcService;
import io.quarkus.grpc.GrpcClient;
import io.quarkus.grpc.MutinyService;
import io.quarkus.grpc.MutinyClient;
import jakarta.inject.Inject;

Basic Usage

Implementing a gRPC Service

import io.quarkus.grpc.GrpcService;
import io.smallrye.mutiny.Uni;

@GrpcService
public class GreetingService implements MutinyService {
    
    public Uni<HelloReply> sayHello(HelloRequest request) {
        return Uni.createFrom().item(
            HelloReply.newBuilder()
                .setMessage("Hello " + request.getName())
                .build()
        );
    }
}

Consuming a gRPC Service

import io.quarkus.grpc.GrpcClient;
import io.smallrye.mutiny.Uni;
import jakarta.inject.Inject;

public class GreetingClient {
    
    @Inject
    @GrpcClient("greeting")
    MutinyGreetingGrpc client;
    
    public Uni<HelloReply> greet(String name) {
        HelloRequest request = HelloRequest.newBuilder()
            .setName(name)
            .build();
        return client.sayHello(request);
    }
}

Architecture

The Quarkus gRPC extension is built around several key components:

  • Service Annotations: @GrpcService for implementing gRPC services, @GrpcClient for injecting gRPC clients
  • Mutiny Integration: Full reactive programming support with Uni and Multi types for non-blocking operations
  • Code Generation: Automatic generation of Mutiny-based client and service interfaces from protobuf definitions
  • Interceptor Support: Global and service-specific interceptors for cross-cutting concerns
  • Exception Handling: Customizable exception transformation and error handling mechanisms
  • Configuration System: Comprehensive configuration for servers, clients, TLS, and other options
  • Development Support: Hot reload, reflection support, and in-process testing capabilities

Capabilities

Service Implementation

Core functionality for implementing gRPC services with reactive programming support. Services are implemented as CDI beans with automatic lifecycle management.

@Target({ FIELD, PARAMETER, TYPE })
@Retention(RUNTIME)
@Qualifier
public @interface GrpcService {
}

public interface MutinyService {
}

Service Implementation

Client Injection and Usage

Client functionality for consuming gRPC services with reactive programming support and configuration management.

@Target({ FIELD, PARAMETER })
@Retention(RUNTIME) 
@Qualifier
public @interface GrpcClient {
    String value() default ELEMENT_NAME;
    String ELEMENT_NAME = "<<element name>>";
}

public interface MutinyClient<T extends AbstractStub<T>> {
    T getStub();
    MutinyClient<T> newInstanceWithStub(T stub);
}

Client Usage

Interceptor Registration

Interceptor system for implementing cross-cutting concerns like authentication, logging, and metrics across gRPC services and clients.

@Target({ FIELD, PARAMETER, TYPE, METHOD })
@Retention(RUNTIME)
public @interface GlobalInterceptor {
}

@Target(TYPE)
@Retention(RUNTIME)
@Repeatable(RegisterInterceptors.class)
public @interface RegisterInterceptor {
    Class<? extends ServerInterceptor> value();
}

Interceptors

Exception Handling

Comprehensive exception handling system with customizable error transformation and gRPC status code mapping.

public abstract class ExceptionHandler<ReqT, RespT> extends 
    ForwardingServerCallListener.SimpleForwardingServerCallListener<ReqT> {
    
    protected abstract void handleException(
        Throwable t, 
        ServerCall<ReqT, RespT> call, 
        Metadata metadata
    );
}

public interface ExceptionHandlerProvider {
    <ReqT, RespT> ExceptionHandler<ReqT, RespT> createHandler(
        Listener<ReqT> listener,
        ServerCall<ReqT, RespT> serverCall, 
        Metadata metadata
    );
}

Exception Handling

Reactive Streaming

Low-level reactive streaming utilities for implementing custom gRPC call patterns with Mutiny integration.

public class ServerCalls {
    public static <I, O> void oneToOne(
        I request, 
        StreamObserver<O> response, 
        String compression,
        Function<I, Uni<O>> implementation
    );
    
    public static <I, O> void oneToMany(
        I request, 
        StreamObserver<O> response, 
        String compression,
        Function<I, Multi<O>> implementation
    );
}

Reactive Streaming

Configuration and Customization

Server and client configuration with customization hooks for advanced use cases including TLS, load balancing, and performance tuning.

public interface ServerBuilderCustomizer<T extends ServerBuilder<T>> {
    default void customize(GrpcServerConfiguration config, T builder);
    default void customize(GrpcServerConfiguration config, GrpcServerOptions options);
    default int priority();
}

public interface ChannelBuilderCustomizer<T extends ManagedChannelBuilder<T>> {
    default Map<String, Object> customize(
        String name, 
        GrpcClientConfiguration config, 
        T builder
    );
}

Configuration

Types

Core Marker Interfaces

public interface MutinyGrpc {
}

public interface MutinyBean {
}

public interface MutinyStub {
}

Client Utilities

public class GrpcClientUtils {
    public static <T> T attachHeaders(T client, Metadata extraHeaders);
    public static <T> T getProxiedObject(T client);
}

Stream Observers

public class UniStreamObserver<T> implements StreamObserver<T> {
}

public class MultiStreamObserver<T> implements StreamObserver<T> {
}

public class ManyToManyObserver<T> implements StreamObserver<T> {
}

public class ManyToOneObserver<T> implements StreamObserver<T> {
}