## 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.2</version>
    </dependency>

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

    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.

    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