Vert.x gRPC/IO Server

Vert.x gRPC/IO Server extends the Vert.x gRPC server with grpc-java integration.

This server provides compatibility with the grpc-java generated stub approach with a service bridge.

Using Vert.x gRPC/IO Server

To use Vert.x gRPC/IO Server, add the following dependency to the dependencies section of your build descriptor:

  • Maven (in your pom.xml):

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-grpcio-server</artifactId>
  <version>5.0.1-SNAPSHOT</version>
</dependency>
  • Gradle (in your build.gradle file):

dependencies {
  compile 'io.vertx:vertx-grpcio-server:5.0.1-SNAPSHOT'
}

Service bridge

The Vert.x gRPC Server can bridge a gRPC service to use with grpc-java generated server classes.

GrpcIoServer grpcServer = GrpcIoServer.server(vertx);

GreeterGrpc.GreeterImplBase service = new GreeterGrpc.GreeterImplBase() {
  @Override
  public void sayHello(HelloRequest request, StreamObserver<HelloReply> responseObserver) {
    responseObserver.onNext(HelloReply.newBuilder().setMessage("Hello " + request.getName()).build());
    responseObserver.onCompleted();
  }
};

// Bind the service in the gRPC server
grpcServer.addService(service);

// Start the HTTP/2 server
vertx.createHttpServer(options)
  .requestHandler(grpcServer)
  .listen();

The bridge supports deadline automatic cancellation: when a gRPC request carrying a timeout is received, a deadline is associated with the io.grpc.Context an can be obtained from the current context. This deadline automatically cancels the request in progress when its associated timeout fires.

Idiomatic gRPC/IO service

The Vert.x gRPC protoc plugin supports the generation of gRPC/IO client code:

  • examples/Greeter.java

  • examples/GreeterService.java

  • examples/GreeterGrpcIo.java

By default, GreeterGrpcIo is not generated, to activate it you need to tell the Vert.x gRPC protoc plugin to generate it:

<protocPlugin>
  <id>vertx-grpc-protoc-plugin2</id>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-grpc-protoc-plugin2</artifactId>
  <version>${stack.version}</version>
  <mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
  <args>
    <arg>--grpc-io</arg>
  </args>
</protocPlugin>

The GreeterGrpcIo provides a bindable service that uses the Vert.x gRPC/IO Server to expose the service:

GrpcIoServer grpcServer = GrpcIoServer.server(vertx);

BindableService service = GreeterGrpcIo.bindableServiceOf(new GreeterService() {
  @Override
  public Future<HelloReply> sayHello(HelloRequest request) {
    return Future.succeededFuture(HelloReply.newBuilder().setMessage("Hello " + request.getName()).build());
  }
});

// Bind the service in the gRPC server
grpcServer.addService(service);

// Start the HTTP/2 server
vertx.createHttpServer(options)
  .requestHandler(grpcServer)
  .listen();

You can read the idiomatic server section to learn more about it.

gRPC Reflection APIs

Support for the gRPC reflection APIs can be added to your Vert.x gRPC Server.

GrpcIoServer grpcServer = GrpcIoServer.server(vertx);

// Add reflection service
grpcServer.addService(ReflectionService.v1());

GreeterGrpc.GreeterImplBase greeterService = new GreeterGrpc.GreeterImplBase() {
  @Override
  public void sayHello(HelloRequest request, StreamObserver<HelloReply> responseObserver) {
    responseObserver.onNext(HelloReply.newBuilder().setMessage("Hello " + request.getName()).build());
    responseObserver.onCompleted();
  }
};

// Bind the service in the gRPC server
grpcServer.addService(greeterService);

// Start the HTTP/2 server
vertx.createHttpServer(options)
  .requestHandler(grpcServer)
  .listen();

You can then use tools like gRPCurl to explore and invoke your gRPC APIs.

grpcurl -plaintext localhost:50051 list

grpcurl -plaintext localhost:50051 describe .helloworld.HelloRequest

grpcurl -plaintext -d '{"name": "Vert.x"}' localhost:50051 helloworld.Greeter