How to bring a gRPC defined API to the web browser

Unfortunately, there isn't any good answer for you yet.

Supporting streaming RPCs from the browser fully requires HTTP2 trailers to be supported by the browsers, and at the time of the writing of this answer, they aren't.

See this issue for the discussion on the topic.

Otherwise, yes, you'd require a full translation system between WebSockets and gRPC. Maybe getting inspiration from grpc-gateway could be the start of such a project, but that's still a very long shot.

https://github.com/tmc/grpc-websocket-proxy sounds like it may meet your needs. This translates json over web sockets to grpc (layer on top of grpc-gateway).

The grpc people at https://github.com/grpc/ are currently building a js implementation.

The repro is at https://github.com/grpc/grpc-web (gives 404 ->) which is currently (2016-12-20) in early access so you need to request access.

GRPC Bus WebSocket Proxy does exactly this by proxying all GRPC calls over a WebSocket connection to give you something that looks very similar to the Node GRPC API in the browser. Unlike GRPC-Gateway, it works with both streaming requests and streaming responses, as well as non-streaming calls.

There is both a server and client component. The GRPC Bus WebSocket Proxy server can be run with Docker by doing docker run gabrielgrant/grpc-bus-websocket-proxy

On the browser side, you'll need to install the GRPC Bus WebSocket Proxy client with npm install grpc-bus-websocket-client

and then create a new GBC object with: new GBC(<grpc-bus-websocket-proxy address>, <protofile-url>, <service map>)

For example:

var GBC = require("grpc-bus-websocket-client");


new GBC("ws://localhost:8080/", 'helloworld.proto', {helloworld: {Greeter: 'localhost:50051'}})
.connect()
.then(function(gbc) {
gbc.services.helloworld.Greeter.sayHello({name: 'Gabriel'}, function(err, res){
console.log(res);
});  // --> Hello Gabriel
});

The client library expects to be able to download the .proto file with an AJAX request. The service-map provides the URLs of the different services defined in your proto file as seen by the proxy server.

For more details, see the GRPC Bus WebSocket Proxy client README

Edit: Since Oct 23,2018 the gRPC-Web project is GA, which might be the most official/standardized way to solve your problem. (Even if it's already 2018 now... ;) )

From the GA-Blog: "gRPC-Web, just like gRPC, lets you define the service “contract” between client (web) and backend gRPC services using Protocol Buffers. The client can then be auto generated. [...]"

We recently built gRPC-Web (https://github.com/improbable-eng/grpc-web) - a browser client and server wrapper that follows the proposed gRPC-Web protocol. The example in that repo should provide a good starting point.

It requires either a standalone proxy or a wrapper for your gRPC server if you're using Golang. The proxy/wrapper modifies the response to package the trailers in the response body so that they can be read by the browser.

Disclosure: I'm a maintainer of the project.

Looking at the current solutions with gRPC over web, here is what's available out there at the time of writing this (and what I found):

• gRPC-web: requires TypeScript for client
• gRPC-web-proxy: requires Go
• gRPC-gateway: requires .proto modification and decorations
• gRPC-bus-websocket-proxy-server: as of writing this document it lacks tests and seems abandoned (edit: look at the comments by the original author!)
• gRPC-dynamic-gateway: a bit of an overkill for simple gRPC services and authentication is awkward
• gRPC-bus: requires something for the transport

I also want to shamelessly plug my own solution which I wrote for my company and it's being used in production to proxy requests to a gRPC service that only includes unary and server streaming calls:

• gRPC-express

Every inch of the code is covered by tests. It's an Express middleware so it needs no additional modifications to your gRPC setup. You can also delegate HTTP authentication to Express (e.g with Passport).

An official grpc-web (beta) implementation was released on 3/23/2018. You can find it at

https://github.com/grpc/grpc-web

The following instructions are taken from the README:

Define your gRPC service:

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


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

Build the server in whatever language you want.

Create your JS client to make calls from the browser:

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

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());
});

Streams from the server to the browser are supported:

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

Bidirectional streams are NOT supported:

This is a work in progress and on the grpc-web roadmap. While there is an example protobuf showing bidi streaming, this comment make it clear that this example doesn't actually work yet.

Hopefully this will change soon. :)

I see a lot of answers didn't point to a bidirectional solution over WebSocket, as the OP asked for browser support.

You may use JSON-RPC instead of gRPC, to get a bidirectional RPC over WebSocket, which supports a lot more, including WebRTC (browser to browser).

I guess it could be modified to support gRPC if you really need this type of serialization.

However, for browser tab to browser tab, request objects are not serializsed and are transfered natively, and the same with NodeJS cluster or thread workers, which offers a lot more performance.

Also, you can transfer "pointers" to SharedArrayBuffer, instead of serializing through the gRPC format.

JSON serialization and deserialization in V8 is also unbeatable.

https://github.com/bigstepinc/jsonrpc-bidirectional