README.adoc

Vert.x gRPC examples

Here you will find examples demonstrating Vert.x gRPC in action.

Dependencies required

To use Vert.x gRPC in your own Maven or Gradle project add the following dependency

Group ID: io.vertx
Artifact ID: vertx-grpc

You will need to use the com.google.protobuf plugin to compile the .proto files. These examples use the io.vertx:vertx-grpc-protoc-plugin plugin that creates server and stub classes for Vert.x.

Each example shows how to use the gRPC request/response API and how to use the stub API.

The protobuf compiler is available for Maven or Gradle and is OS dependant.

Simple examples

These examples demonstrate the four gRPC RPC cardinalities using a single ExampleService proto definition.

Unary

One request, one response.

• gRPC client example

• gRPC client stub example

• gRPC server example

• gRPC server stub example

Server Streaming

The client sends one request and the server responds with a stream of messages.

• gRPC client example

• gRPC client stub example

• gRPC server example

• gRPC server stub example

Client Streaming

The client sends a stream of messages and the server responds with a single message.

• gRPC client example

• gRPC client stub example

• gRPC server example

• gRPC server stub example

Bidirectional Streaming

Both the client and server send a stream of messages to each other.

• gRPC client example

• gRPC client stub example

• gRPC server example

• gRPC server stub example

Timeout and deadlines

This example shows timeout and deadlines in action.

The server is configured to create a deadline when a request with a timeout is received.

It does not send a response purposely to trigger this deadline based on the request timeout.

gRPC server example gRPC server stub example

The client is configured to set a request with a timeout and rely on the server to respond with a deadline exceeded status.

gRPC client example gRPC client stub example

JSON wire format

This example uses JSON wire format instead of Protobuf.

gRPC server example gRPC server stub example gRPC client example gRPC client stub example

Transcoding

The transcoding examples demonstrate a gRPC service bound as REST endpoints.

Unary

• gRPC server example

• gRPC server stub example

• Client example

When the server is running you can access the service using a simple HTTP client:

> curl -H 'Content-Type: application/json' http://localhost:8080/v1/example/unary/Julien
{
  "value": "Julien"
}

Server Streaming

• gRPC server example

• gRPC server stub example

• Client example

When the server is running you can access the streaming endpoint using a simple HTTP client:

> curl -H 'Content-Type: application/json' http://localhost:8080/v1/example/serverstreaming/Julien
[
{"value":"Julien 0"}
,{"value":"Julien 1"}
,{"value":"Julien 2"}
,{"value":"Julien 3"}
,{"value":"Julien 4"}
]

Event bus transport

This example shows how to use a client/server gRPC example using the event bus transport, in a clustered fashion.

• Event bus unary client example

• Event bus unary server example

• Event bus bidi-streaming client example

• Event bus bidi-streaming server example

This example needs Java 17 or later because it uses the Hazelcast cluster manager.

Health checking

This example shows how to use the gRPC health checking protocol.

gRPC server example gRPC client example

Load balancing

Demonstrate how to use client side load balancing

Start 3 gRPC servers on port 8080/8081/8082 gRPC client load balancing example

SSL example

This example shows gRPC with SSL configuration.

• gRPC client example

• gRPC client stub example

• gRPC server example

• gRPC server stub example