== 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`):

[source,xml,subs="+attributes"]
----
<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-grpcio-server</artifactId>
  <version>5.0.2</version>
</dependency>
----

* Gradle (in your `build.gradle` file):

[source,groovy,subs="+attributes"]
----
dependencies {
  compile 'io.vertx:vertx-grpcio-server:5.0.2'
}
----

=== Service bridge

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

[source,java]
----
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 <<vertx-grpc-protoc-plugin,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:

[source,xml]
----
<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:

[source,java]
----
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, idiomatic server>> section to learn more about it.

=== gRPC Reflection APIs

Support for the https://grpc.io/docs/guides/reflection/[gRPC reflection APIs] can be added to your Vert.x gRPC Server.

[source,java]
----
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 https://github.com/fullstorydev/grpcurl[gRPCurl] to explore and invoke your gRPC APIs.

[source,bash]
----
grpcurl -plaintext localhost:50051 list

grpcurl -plaintext localhost:50051 describe .helloworld.HelloRequest

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