A JavaScript implementation ofgRPCfor browser clients. For more information, including aquick start,see thegRPC-web documentation.
gRPC-web clients connect to gRPC services via a special proxy; by default, gRPC-web usesEnvoy.
In the future, we expect gRPC-web to be supported in language-specific web frameworks for languages such as Python, Java, and Node. For details, see the roadmap.
gRPC-web currently supports 2 RPC modes:
- Unary RPCs (example)
- Server-side Streaming RPCs (example) (NOTE: Only when
grpcwebtext
mode is used.)
Client-side and Bi-directional streaming is not currently supported (seestreaming roadmap).
Eager to get started? Try theHello World example.From this example, you'll learn how to do the following:
- 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 node-server envoy commonjs-client
$ docker-compose up node-server envoy commonjs-client
Open a browser tab, and visithttp://localhost:8081/echotest.html.
To shutdown:docker-compose down
.
The gRPC-web runtime library is available atnpm
:
$ npm i grpc-web
If you don't already haveprotoc
installed, download it first fromhereand install it on your PATH.
If you use Homebrew (on macOS), you could run:
brew install protobuf
If you don't haveprotoc-gen-js
installed, download it fromprotocolbuffers/protobuf-javascriptand install it on your PATH.
Or, use thethird-partyNPM installer:
npm install -g protoc-gen-js
You can download theprotoc-gen-grpc-web
protoc plugin from our
releasepage:
Make sure all executables are discoverable from your PATH.
For example, on MacOS, you can do:
sudo mv protoc-gen-grpc-web-1.5.0-darwin-aarch64 \
/usr/local/bin/protoc-gen-grpc-web
chmod +x /usr/local/bin/protoc-gen-grpc-web
You can optionally verify the plugins works follwoing ourHello world example:
cdnet/grpc/gateway/examples/helloworld
protoc -I=. helloworld.proto \
--js_out=import_style=commonjs:. \
--grpc-web_out=import_style=commonjs,mode=grpcwebtext:.
After the command runs successfully, you should now see two new files generated in the current directory. By running:
ls -1 *_pb.js
Installation is successful if you see the following 2 files:
helloworld_pb.js
# Generated byprotoc-gen-js
pluginhelloworld_grpc_web_pb.js
- Generated by gRPC-Web plugin
Typically, you will run the following command to generate the proto messages
and the service client stub from your.proto
definitions:
protoc -I=$DIRecho.proto \
--js_out=import_style=commonjs:$OUT_DIR\
--grpc-web_out=import_style=commonjs,mode=grpcwebtext:$OUT_DIR
You can then use Browserify, Webpack, Closure Compiler, etc. to resolve imports at compile time.
import_style=closure
:The default generated code has
Closuregoog.require()
import style.
import_style=commonjs
:The
CommonJSstylerequire()
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. SeeTypeScript Supportbelow for information on how to
generate TypeScript files.
Note:The
commonjs+dts
andtypescript
styles are only supported by--grpc-web_out=import_style=...
,not by--js_out=import_style=...
.
For more information about the gRPC-web wire format, see the specification.
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.
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 buffersto define its RPC service methods and their message request and response types.
messageEchoRequest{
stringmessage=1;
}
...
serviceEchoService{
rpcEcho(EchoRequest)returns(EchoResponse);
rpcServerStreamingEcho(ServerStreamingEchoRequest)
returns(streamServerStreamingEchoResponse);
}
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:
varechoService=newproto.mypackage.EchoServiceClient(
'http://localhost:8080');
varrequest=newproto.mypackage.EchoRequest();
request.setMessage(msg);
varmetadata={'custom-header-1':'value1'};
echoService.echo(request,metadata,function(err,response){
if(err){
console.log(err.code);
console.log(err.message);
}else{
console.log(response.getMessage());
}
});
varstream=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
});
// to close the stream
stream.cancel()
For an in-depth tutorial, seethis page.
You can set a deadline for your RPC by setting adeadline
header. The value
should be a Unix timestamp, in milliseconds.
vardeadline=newDate();
deadline.setSeconds(deadline.getSeconds()+1);
client.sayHelloAfterDelay(request,{deadline:deadline.getTime().toString()},
(err,response)=>{
// err will be populated if the RPC exceeds the deadline
...
});
Thegrpc-web
module can now be imported as a TypeScript module. This is
currently an experimental feature. Any feedback welcome!
When using theprotoc-gen-grpc-web
protoc plugin, mentioned above, pass in
either:
import_style=commonjs+dts
:existing CommonJS style stub +.d.ts
typingsimport_style=typescript
:full TypeScript output
Donotuseimport_style=typescript
for--js_out
,it will silently be
ignored. Instead you should use--js_out=import_style=commonjs
,or
--js_out=import_style=commonjs,binary
if you are usingmode=grpcweb
.The
--js_out
plugin will generate JavaScript code (echo_pb.js
), and the
-grpc-web_out
plugin will generate a TypeScript definition file for it
(echo_pb.d.ts
). This is a temporary hack until the--js_out
supports
TypeScript itself.
For example, this is the command you should use to generate TypeScript code using the binary wire format
protoc -I=$DIRecho.proto \
--js_out=import_style=commonjs,binary:$OUT_DIR\
--grpc-web_out=import_style=typescript,mode=grpcweb:$OUT_DIR
It will generate the following files:
EchoServiceClientPb.ts
- Generated by--grpc-web_out
,contains the TypeScript gRPC-web code.echo_pb.js
- Generated by--js_out
,contains the JavaScript Protobuf code.echo_pb.d.ts
- Generated by--grpc-web_out
,contains TypeScript definitions forecho_pb.js
.
import*asgrpcWebfrom'grpc-web';
import{EchoServiceClient}from'./EchoServiceClientPb';
import{EchoRequest,EchoResponse}from'./echo_pb';
constechoService=newEchoServiceClient('http://localhost:8080',null,null);
constrequest=newEchoRequest();
request.setMessage('Hello World!');
constcall=echoService.echo(request,{'custom-header-1':'value1'},
(err:grpcWeb.RpcError,response:EchoResponse)=>{
console.log(response.getMessage());
});
call.on('status',(status:grpcWeb.Status)=>{
//...
});
(Seeherefull list of possible.on(...)
callbacks)
NOTE:It is not possible to access the
.on(...)
callbacks (e.g. formetadata
andstatus
) when Promise is used.
// Create a Promise client instead
constechoService=newEchoServicePromiseClient('http://localhost:8080',null,null);
...(sameasabove)
this.echoService.echo(request,{'custom-header-1':'value1'})
.then((response:EchoResponse)=>{
console.log(`Received response:${response.getMessage()}`);
}).catch((err:grpcWeb.RpcError)=>{
console.log(`Received error:${err.code},${err.message}`);
});
For the full TypeScript example, see ts-example/client.tswith theinstructionsto run.
Custom interceptors can be implemented and chained, which could be useful for features like auth, retries, etc.
There are 2 types of interceptors (interfaces):
UnaryInterceptor
(doc,example) - Intercept Unary RPCs; can only be used with Promise clients.StreamInterceptor
(doc,example) - More versatile; can be used with regular clients.
For more details, seethis blog post.
Multiple proxies support the gRPC-web protocol.
-
The currentdefault proxyisEnvoy,which supports gRPC-web out of the box.
$ docker-compose up -d node-server envoy commonjs-client
-
You can also try thegRPC-web Go proxy.
$ docker-compose up -d node-server grpcwebproxy binary-client
-
ApacheAPISIXhas also added grpc-web support, and more details can be foundhere.
-
Nginxhas a grpc-web module (doc,announcement)), and seems to work with simple configs, according to userfeedback.