grpc
gRPC-Web Client Runtime Library
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.
The current release is a Beta release, and we expect to announce General-Availability by Oct. 2018.
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.
Quick Start
This example is using the echo.proto file from the
Echo Example.
- Add
grpc-webas a dependency usingnpm.
$ npm i grpc-web- Download
protocand theprotoc-gen-grpc-webprotoc plugin.
You can download the protoc binary from the official
protocolbuffers
release page.
You can download the protoc-gen-grpc-web protoc plugin from our Github
release page.
Make sure they are both executable and are discoverable from your PATH.
For example, in MacOS, you can do:
$ sudo mv ~/Downloads/protoc-gen-grpc-web-1.0.7-darwin-x86_64 \
/usr/local/bin/protoc-gen-grpc-web
$ chmod +x /usr/local/bin/protoc-gen-grpc-web- Generate your proto messages and the service client stub classes with
protocand theprotoc-gen-grpc-webplugin. You can set theimport_style=commonjsoption for both--js_outand--grpc-web_out.
$ protoc -I=$DIR echo.proto \
--js_out=import_style=commonjs:generated \
--grpc-web_out=import_style=commonjs,mode=grpcwebtext:generated- Start using your generated client!
const {EchoServiceClient} = require('./generated/echo_grpc_web_pb.js');
const {EchoRequest} = require('./generated/echo_pb.js');
const client = new EchoServiceClient('localhost:8080');
const request = new EchoRequest();
request.setMessage('Hello World!');
const metadata = {'custom-header-1': 'value1'};
client.echo(request, metadata, (err, response) => {
// ...
});What's Next
To complete the example, you need to run a proxy that understands the gRPC-Web protocol between your browser client and your gRPC service. The default proxy currently is Envoy. Please visit our Github repo for more information.
Here's a quick way to get started!
$ git clone https://github.com/grpc/grpc-web
$ cd grpc-web
$ docker-compose up node-server envoy commonjs-clientOpen a browser tab, and go to:
http://localhost:8081/echotest.htmlTypeScript Support
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.
Run Tests
Pre-requisites:
protocprotoc-gen-grpc-webplugin
$ npm test