Quarkus gRPC Client Extension

Extension to call gRPC services in your Quarkus application.

@ApplicationScoped
public class RouteGuideClient {

    private RouteGuideBlockingStub blockingStub;
    
    @Inject
    public RouteGuideClient(@Channel("route") ManagedChannel channel) {
        blockingStub = RouteGuideGrpc.newBlockingStub(channel);    
    }

    public Feature getFeature(int lat, int lon) {
        Point request = Point.newBuilder().setLatitude(lat).setLongitude(lon).build();
        return blockingStub.getFeature(request);
    }
}

You can inject named channels into your beans. Each channel has a name and is configured in your application.properties:

quarkus.grpc-client.route.host=localhost
quarkus.grpc-client.route.port=5050

The property names are made up of quarkus.grpc-client plus the name of the channel. Right now you can configure host and port. Channels are created with usePlaintext() at the moment, but TLS and support for additional settings (like timeouts) is in the works. Injected channels are created as singletons and are automatically shutdown when Quarkus is shutdown.

Getting Started

The gRPC client extension is not available in Maven Central. For now you have to clone the repository and install the extension in your local maven repository. Then follow these steps to write and deploy a simple hello world gRPC service:

Setup Project

Create a new project using the Quarkus archetype:

mvn io.quarkus:quarkus-maven-plugin:0.11.0:create \
    -DprojectGroupId=io.grpc.helloworld \
    -DprojectArtifactId=helloworld

Add the following dependency to your pom.xml:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-grpc-client</artifactId>
    <version>${quarkus.grpc.client.version}</version>
</dependency>

Setup gRPC

To setup the gRPC code generation, add the following settings to your pom.xml:

<build>
    <extensions>
        <extension>
            <groupId>kr.motd.maven</groupId>
            <artifactId>os-maven-plugin</artifactId>
            <version>1.6.2</version>
        </extension>
    </extensions>
    <plugins>
        <plugin>
            <groupId>org.xolstice.maven.plugins</groupId>
            <artifactId>protobuf-maven-plugin</artifactId>
            <version>0.6.1</version>
            <configuration>
                <protocArtifact>com.google.protobuf:protoc:3.7.1:exe:${os.detected.classifier}
                </protocArtifact>
                <pluginId>grpc-java</pluginId>
                <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.19.0:exe:${os.detected.classifier}
                </pluginArtifact>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>compile</goal>
                        <goal>compile-custom</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    <plugins>
</build>

Define gRPC Client

You need a running gRPC service you can talk to. See the Quarkus gRPC extension on how to get your gRPC services up and running. Then in your client code, inject a managed channel and create a blocking and/or asynchronous stub:

@ApplicationScoped
public class RouteGuideClient {

    private RouteGuideStub asyncStub;
    private RouteGuideBlockingStub blockingStub;
    
    @Inject
    public RouteGuideClient(@Channel("route") ManagedChannel channel) {
        asyncStub = RouteGuideGrpc.newStub(channel);
        blockingStub = RouteGuideGrpc.newBlockingStub(channel);    
    }

    public Feature getFeature(int lat, int lon) {
        Point request = Point.newBuilder().setLatitude(lat).setLongitude(lon).build();
        return blockingStub.getFeature(request);
    }
}

Finally specify the host and port in your application.properties:

quarkus.grpc-client.route.host=localhost
quarkus.grpc-client.route.port=5050

Quickstart

If you want to see a more complex example, checkout the gRPC quickstart. It uses both the gRPC and the gRPC client extension to implement the route guide example provided by gRPC Java.

What's Missing

TLS
Better devmode support
More configuration options