Overview

gRPC-Web provides a Javascript client library that lets browser clients access a gRPC server. You can find out much more about gRPC in its own website.

The current release is a Beta release, mainly for early adopters to provide feedback on the JS API (both gRPC and Protobuf). The JS client library has been used for some time by Google and Alphabet projects with the Closure compiler and its TypeScript generator (which has not yet been open-sourced).

gRPC-Web clients connect to gRPC servers via a special gateway proxy: our provided version uses Nginx. However, Nginx doesn't support HTTP/2 to backends as of Q3/2017, and therefore the gateway can't be used as a reverse proxy for load balancing - if you need to use a reverse proxy as well you'll need to deploy a second gateway. We have also added gRPC-Web support to Envoy, if you wish to use this instead of an Nginx gateway. In future, we expect gRPC-Web to be supported in language-specific Web frameworks, such as Go, Java, and Node, which will eliminate the need to deploy a gateway at all.

How it works

Let's take a look at how gRPC-Web works with a simple example. You can find out how to build, run and explore the example yourself in Build and Run the Echo Example.

1. Define your service

The first step when creating any gRPC service is to define it. Like all gRPC services, gRPC-Web uses protocol buffers to define its RPC service methods and their message request and response types.

service EchoService {
  rpc Echo(EchoRequest) returns (EchoResponse);

  rpc ServerStreamingEcho(ServerStreamingEchoRequest)
      returns (stream ServerStreamingEchoResponse);
}

2. Build the server

Next you need to have a gRPC server that implements the service interface and a gateway that allows the client to connect to the server. Our example builds a simple C++ gRPC backend server and the Nginx gateway. You can find out more in the Echo Example.

3. Write your JS client

Once the server and gateway are up and running, you can start making gRPC calls from the browser!

Create your client

var echoService = new proto.grpc.gateway.testing.EchoServiceClient(
  'http://localhost:9091');

Make a unary RPC call

var unaryRequest = new proto.grpc.gateway.testing.EchoRequest();
unaryRequest.setMessage(msg);
echoService.echo(unaryRequest, {},
  function(err, response) {
    console.log(response.getMessage());
  });

Server-side streaming is supported!

var stream = echoService.serverStreamingEcho(streamRequest, {});
stream.on('data', function(response) {
  console.log(response.getMessage());
});