Building a gRPC Web service

This document will show you how to build a browser/server application with Vert.x and gRPC Web.

What you will build

The application involves a client, the browser, and a Vert.x server:

• the user types a name in a text field and clicks the send button

• the browser sends the name to the server using the gRPC Web protocol

• the server replies with a greeting

• the browser displays the greeting

On the server side, you will create a Vert.x gRPC server service that:

• implements a gRPC server stub

• configures an HTTP server replying to both gRPC Web and static file requests

On the client side, you will create a web page that uses the gRPC Web Javascript client.

What you need

• A text editor or an IDE

• Java 17 or higher

• The protoc Javascript plugin

• The protoc gRPC Web plugin

The protoc Javascript and gRPC Web plugin files must be installed somewhere on your PATH and be executable.

Tip

On several Linux systems, you can install the plugins like this: mkdir --parents "$HOME/.local/bin" curl -sL https://github.com/protocolbuffers/protobuf-javascript/releases/download/v3.21.4/protobuf-javascript-3.21.4-linux-x86_64.tar.gz | tar xzfO - bin/protoc-gen-js > "$HOME/.local/bin/protoc-gen-js" chmod u+x "$HOME/.local/bin/protoc-gen-js" curl -sL https://github.com/grpc/grpc-web/releases/download/1.5.0/protoc-gen-grpc-web-1.5.0-linux-x86_64 > "$HOME/.local/bin/protoc-gen-grpc-web" chmod u+x "$HOME/.local/bin/protoc-gen-grpc-web"

You don’t have to install protoc or the Java plugin. They will be managed by a Maven plugin.

Create the project

gRPC service definition

The gRPC Greeter service consists in a single SayHello rpc method. The HelloRequest message contains the name sent by the client. The HelloReply message contains the greeting generated by the server.

service.proto file

Code generation

From the service definition, several files must be generated:

• Java message and server classes

• Javascript files

• gRPC Web specific (Javascript) files.

The protoc invocation is managed with the protobuf-maven-plugin.

Maven POM file

The server side

We need some dependencies for the project to compile:

Maven POM file

The server side code fits in a single ServerVerticle class.

First, the gRPC server stub implementation.

Verticle file

There is nothing specific to gRPC Web here.

Note	GrpcServer enables the gRPC Web protocol support by default.

Then we have to configure a Vert.x Web Router to accept both gRPC Web and static file requests.

Verticle file

The client side

Before writing code, we must set up the project to build client side code. For simplicity, we choose to use the esbuild-maven-plugin. In a few words, it’s a Maven plugin that wraps esbuild, a fast bundler for the web.

A couple of dependencies are required, which we grab as Maven dependencies thanks to mvnpm:

• google-protobuf

• grpc-web

Maven POM file

The user interface code fits in a single index.html file.

HTML file

Last but not least, let’s implement the sayHello function:

Application JS file

Running the application

You can run the application with Maven:

./mvnw compile exec:java

You should see:

Server started, browse to http://localhost:8080

You can now browse to http://localhost:8080 and follow the instructions.

Use the dev tools of your browser to inspect the gRPC Web traffic.

Summary

This document covered:

1. implementing a Vert.x web server that replies to both static file and gRPC Web requests,

2. creating a web page that uses the gRPC Web client.

See also

• Vert.x gRPC documentation

• gRPC Web project