gRPC-Web provides a Javascript library that lets browser clients access a gRPC service. You can find out much more about gRPC in its own website.
gRPC-Web is now Generally Available, and considered stable enough for production use.
gRPC-Web clients connect to gRPC services via a special gateway proxy: the current version of the library uses Envoy by default, in which gRPC-Web support is built-in.
In the future, we expect gRPC-Web to be supported in language-specific Web frameworks, such as Python, Java, and Node. See the roadmap doc.
You can follow the Hello World Guide to get started with gRPC-Web quickly.
From the guide, you will learn how to
- Define your service using protocol buffers
- Implement a simple gRPC Service using NodeJS
- Configure the Envoy proxy
- Generate protobuf message classes and client service stub for the client
- Compile all the JS dependencies into a static library that can be consumed by the browser easily
You can also try to run a more advanced Echo app from the browser with a streaming example.
From the repo root directory:
$ docker-compose pull prereqs common node-server envoy commonjs-client
$ docker-compose up -d node-server envoy commonjs-clientOpen a browser tab, and go to:
http://localhost:8081/echotest.html
To shutdown: docker-compose down.
The gRPC-Web runtime library is available at npm:
$ npm i grpc-webYou can compile the protoc-gen-grpc-web protoc plugin from this repo:
$ sudo make install-pluginIf you don't already have protoc installed, you may have to do this first:
$ ./scripts/init_submodules.sh
$ cd third_party/grpc/third_party/protobuf
$ ./autogen.sh && ./configure && make -j8 && sudo make installTypically, you will run the following command to generate the proto messages
and the service client stub from your .proto definitions:
$ protoc -I=$DIR echo.proto \
--js_out=import_style=commonjs:$OUT_DIR \
--grpc-web_out=import_style=commonjs,mode=grpcwebtext:$OUT_DIRYou can then use Browserify, Webpack, Closure Compiler, etc. to resolve imports at compile time.
import_style=closure: The default generated code has
Closure goog.require()
import style.
import_style=commonjs: The
CommonJS style require() is
also supported.
import_style=commonjs+dts: (Experimental) In addition to above, a .d.ts
typings file will also be generated for the protobuf messages and service stub.
import_style=typescript: (Experimental) The service stub will be generated
in TypeScript.
Note: commonjs+dts and typescript only works with --grpc-web_out= import style.
For more information about the gRPC-Web wire format, please see the specification here.
mode=grpcwebtext: The default generated code sends the payload in the
grpc-web-text format.
Content-type: application/grpc-web-text- Payload are base64-encoded.
- Both unary and server streaming calls are supported.
mode=grpcweb: A binary protobuf format is also supported.
Content-type: application/grpc-web+proto- Payload are in the binary protobuf format.
- Only unary calls are supported for now.
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.
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.
message EchoRequest {
string message = 1;
}
...
service EchoService {
rpc Echo(EchoRequest) returns (EchoResponse);
rpc ServerStreamingEcho(ServerStreamingEchoRequest)
returns (stream ServerStreamingEchoResponse);
}Next you need to have a gRPC server that implements the service interface and a gateway proxy that allows the client to connect to the server. Our example builds a simple Node gRPC backend server and the Envoy proxy.
For the Echo service: see the service implementations.
For the Envoy proxy: see the config yaml file.
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.mypackage.EchoServiceClient(
'http://localhost:8080');Make a unary RPC call
var request = new proto.mypackage.EchoRequest();
request.setMessage(msg);
var metadata = {'custom-header-1': 'value1'};
var call = echoService.echo(request, metadata, function(err, response) {
if (err) {
console.log(err.code);
console.log(err.message);
} else {
console.log(response.getMessage());
}
});
call.on('status', function(status) {
console.log(status.code);
console.log(status.details);
console.log(status.metadata);
});Server-side streaming is supported!
var stream = echoService.serverStreamingEcho(streamRequest, metadata);
stream.on('data', function(response) {
console.log(response.getMessage());
});
stream.on('status', function(status) {
console.log(status.code);
console.log(status.details);
console.log(status.metadata);
});
stream.on('end', function(end) {
// stream end signal
});You can find a more in-depth tutorial from this page.
You can set a deadline for your RPC by setting a deadline header. The value
should be a Unix timestamp, in milliseconds.
var deadline = new Date();
deadline.setSeconds(deadline.getSeconds() + 1);
client.sayHelloAfterDelay(request, {deadline: deadline.getTime()},
(err, response) => {
// err will be populated if the RPC exceeds the deadline
...
});The grpc-web module can now be imported as a TypeScript module. This is
currently an experimental feature. Any feedback welcome!
When using the protoc-gen-grpc-web protoc plugin, mentioned above, pass in
either:
import_style=commonjs+dts: existing CommonJS style stub +.d.tstypingsimport_style=typescript: full TypeScript output
import * as grpcWeb from 'grpc-web';
import {EchoServiceClient} from './echo_grpc_web_pb';
import {EchoRequest, EchoResponse} from './echo_pb';
const echoService = new EchoServiceClient('http://localhost:8080', null, null);
const request = new EchoRequest();
request.setMessage('Hello World!');
const call = echoService.echo(request, {'custom-header-1': 'value1'},
(err: grpcWeb.Error, response: EchoResponse) => {
console.log(response.getMessage());
});
call.on('status', (status: grpcWeb.Status) => {
// ...
});See a full TypeScript example here.
Multiple proxies supports the gRPC-Web protocol. Currently, the default proxy is Envoy, which supports gRPC-Web out of the box.
$ docker-compose up -d node-server envoy commonjs-clientAn alternative is to build Nginx that comes with this repository.
$ docker-compose up -d node-server nginx commonjs-clientYou can also try this gRPC-Web Go Proxy.
$ docker-compose up -d node-server grpcwebproxy binary-clientBig thanks to the following contributors for making significant contributions to this project!