Implementing a gRPC Service

gRPC service implementations exposed as beans are automatically registered and served by quarkus-grpc.

Implementation base

The generation has created 2 implementation bases:

1. One using the default gRPC API

2. One using the Mutiny API

The first classname is structured as follows: ${NAME_OF_THE_SERVICE}Grpc.${NAME_OF_THE_SERVICE}ImplBase. The second classname is structured as follows: Mutiny${NAME_OF_THE_SERVICE}Grpc.${NAME_OF_THE_SERVICE}ImplBase.

For example, if you use Greeter as service name as in:

service Greeter {
    rpc SayHello (HelloRequest) returns (HelloReply) {}
}

The regular implementation base is: GreeterGrpc.GreeterImplBase. The second implementation base is: MutinyGreeterGrpc.GreeterImplBase.

Note that these classes are not interfaces but regular classes. When extending them, you need to override the service methods defined in the service definition.

Implementing a service with the default gRPC API

To implement a gRPC service using the default gRPC API, create a class extending the default implementation base. Then, override the methods defined in the service interface. Finally, expose the service as a CDI bean using the @Singleton annotation:

import javax.inject.Singleton;
@Singleton
public class HelloService extends GreeterGrpc.GreeterImplBase {
    @Override
    public void sayHello(HelloRequest request, StreamObserver<HelloReply> responseObserver) {
        String name = request.getName();
        String message = "Hello " + name;
        responseObserver.onNext(HelloReply.newBuilder().setMessage(message).build());
        responseObserver.onCompleted();
    }
}

Implementing a service with the Mutiny API

To implement a gRPC service using the Mutiny gRPC API, create a class extending the Mutiny implementation base. Then, override the methods defined in the service interface. These methods are using Mutiny types. Finally, expose the service as a CDI bean using the @Singleton annotation:

import javax.inject.Singleton;
@Singleton
public class ReactiveHelloService extends MutinyGreeterGrpc.GreeterImplBase {
    @Override
    public Uni<HelloReply> sayHello(HelloRequest request) {
        return Uni.createFrom().item(() ->
                HelloReply.newBuilder().setMessage("Hello " + request.getName()).build()
        );
    }
}

Handling streams

gRPC allows receiving and returning streams:

service Streaming {
    rpc Source(Empty) returns (stream Item) {} // Returns a stream
    rpc Sink(stream Item) returns (Empty) {}   // Reads a stream
    rpc Pipe(stream Item) returns (stream Item) {}  // Reads a streams and return a streams
}

Using Mutiny, you can implement these as follows:

@Singleton
public class StreamingService extends MutinyStreamingGrpc.StreamingImplBase {
    @Override
    public Multi<Item> source(Empty request) {
        // Just returns a stream emitting an item every 2ms and stopping after 10 items.
        return Multi.createFrom().ticks().every(Duration.ofMillis(2))
                .transform().byTakingFirstItems(10)
                .map(l -> Item.newBuilder().setValue(Long.toString(l)).build());
    }
    @Override
    public Uni<Empty> sink(Multi<Item> request) {
        // Reads the incoming streams, consume all the items.
        return request
                .map(Item::getValue)
                .map(Long::parseLong)
                .collectItems().last()
                .map(l -> Empty.newBuilder().build());
    }
    @Override
    public Multi<Item> pipe(Multi<Item> request) {
        // Reads the incoming stream, compute a sum and return the cumulative results
        // in the outbound stream.
        return request
                .map(Item::getValue)
                .map(Long::parseLong)
                .onItem().scan(() -> 0L, Long::sum)
                .onItem().transform(l -> Item.newBuilder().setValue(Long.toString(l)).build());
    }
}

Health check

For the exposed services, Quarkus gRPC exposes health information in the following format:

syntax = "proto3";
package grpc.health.v1;
message HealthCheckRequest {
  string service = 1;
}
message HealthCheckResponse {
  enum ServingStatus {
    UNKNOWN = 0;
    SERVING = 1;
    NOT_SERVING = 2;
  }
  ServingStatus status = 1;
}
service Health {
  rpc Check(HealthCheckRequest) returns (HealthCheckResponse);
  rpc Watch(HealthCheckRequest) returns (stream HealthCheckResponse);
}

Clients can specify the fully qualified service name to get the health status of a specific service or skip specifying the service name to get the general status of the gRPC server.

For more details, check out the gRPC documentation

Additionally, if Quarkus SmallRye Health is added to the application, a readiness check for the state of the gRPC services will be added to the MicroProfile Health endpoint response, that is /health.

Reflection Service

Quarkus gRPC Server implements the reflection service. This service allows tools like grpcurl or grpcox to interact with your services.

The reflection service is enabled by default in dev mode. In test or production mode, you need to enable it explicitly by setting quarkus.grpc.server.enable-reflection-service to true.

Scaling

By default, quarkus-grpc starts a single gRPC server running on a single event loop.

If you wish to scale your server, you can set the number of server instances by setting quarkus.grpc.server.instances.

Server configuration

Example of configuration

Enabling TLS

To enable TLS, use the following configuration:

quarkus.grpc.server.ssl.certificate=src/main/resources/tls/server.pem
quarkus.grpc.server.ssl.key=src/main/resources/tls/server.key

TLS with Mutual Auth

To use TLS with mutual authentication, use the following configuration:

quarkus.grpc.server.ssl.certificate=src/main/resources/tls/server.pem
quarkus.grpc.server.ssl.key=src/main/resources/tls/server.key
quarkus.grpc.server.ssl.trust-store=src/main/resources/tls/ca.jks
quarkus.grpc.server.ssl.trust-store-password=*****
quarkus.grpc.server.ssl.client-auth=REQUIRED