gRPC-Web

gRPC for Web Clients

RPCProtobuf
grpc/grpc-webgrpc.iogrpc-web

README

gRPC Web · npm version


A JavaScript implementation of [gRPC][] for browser clients. For more information,
including a quick start, see the [gRPC-web documentation][grpc-web-docs].

gRPC-web clients connect to gRPC services via a special proxy; by default,
gRPC-web uses [Envoy][].

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.

Streaming Support

gRPC-web currently supports 2 RPC modes:
- Unary RPCs (example)
- Server-side Streaming RPCs (example)

Client-side and Bi-directional streaming is not currently supported (see streaming roadmap).

Quick Start


Eager to get started? Try the [Hello 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

Advanced Demo: Browser Echo App


You can also try to run a more advanced Echo app from the browser with a
streaming example.

From the repo root directory:

  1. ```sh
  2. $ docker-compose pull prereqs node-server envoy commonjs-client
  3. $ docker-compose up node-server envoy commonjs-client
  4. ```

Open a browser tab, and visit http://localhost:8081/echotest.html.

To shutdown: docker-compose down.

Runtime Library


The gRPC-web runtime library is available at npm:

  1. ```sh
  2. $ npm i grpc-web
  3. ```

Code Generator Plugin


You can download the protoc-gen-grpc-web protoc plugin from our
release page:

If you don't already have protoc installed, you will have to download it
first from here.

NOTE: Javascript output is no longer supported by protocolbuffers/protobuf package as it previously did. Please use the releases from protocolbuffers/protobuf-javascript instead.


Make sure they are both executable and are discoverable from your PATH.

For example, in MacOS, you can do:

  1. ```
  2. $ sudo mv ~/Downloads/protoc-gen-grpc-web-1.4.2-darwin-x86_64 \
  3.     /usr/local/bin/protoc-gen-grpc-web
  4. $ chmod +x /usr/local/bin/protoc-gen-grpc-web
  5. ```

Client Configuration Options


Typically, you will run the following command to generate the proto messages
and the service client stub from your .proto definitions:

  1. ```sh
  2. $ protoc -I=$DIR echo.proto \
  3.     --js_out=import_style=commonjs:$OUT_DIR \
  4.     --grpc-web_out=import_style=commonjs,mode=grpcwebtext:$OUT_DIR
  5. ```

You can then use Browserify, Webpack, Closure Compiler, etc. to resolve imports
at compile time.

Import Style


import_style=closure: The default generated code has
Closuregoog.require()
import style.

import_style=commonjs: The
CommonJS stylerequire() 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. See TypeScript Support below for information on how to
generate TypeScript files.

Note: The commonjs+dts and typescript styles are only supported by
--grpc-web_out=import_style=..., not by --js_out=import_style=....

Wire Format Mode


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 for now.

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.

  1. ```protobuf
  2. message EchoRequest {
  3.   string message = 1;
  4. }

  6. ...

  8. service EchoService {
  9.   rpc Echo(EchoRequest) returns (EchoResponse);

  11.   rpc ServerStreamingEcho(ServerStreamingEchoRequest)
  12.       returns (stream ServerStreamingEchoResponse);
  13. }
  14. ```

2. Run the server and proxy


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.

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:

  1. ``` js
  2. var echoService = new proto.mypackage.EchoServiceClient(
  3.   'http://localhost:8080');
  4. ```

Make a unary RPC call:


  1. ``` js
  2. var request = new proto.mypackage.EchoRequest();
  3. request.setMessage(msg);
  4. var metadata = {'custom-header-1': 'value1'};
  5. echoService.echo(request, metadata, function(err, response) {
  6.   if (err) {
  7.     console.log(err.code);
  8.     console.log(err.message);
  9.   } else {
  10.     console.log(response.getMessage());
  11.   }
  12. });
  13. ```

Server-side streaming:


  1. ``` js
  2. var stream = echoService.serverStreamingEcho(streamRequest, metadata);
  3. stream.on('data', function(response) {
  4.   console.log(response.getMessage());
  5. });
  6. stream.on('status', function(status) {
  7.   console.log(status.code);
  8.   console.log(status.details);
  9.   console.log(status.metadata);
  10. });
  11. stream.on('end', function(end) {
  12.   // stream end signal
  13. });

  15. // to close the stream
  16. stream.cancel()
  17. ```

For an in-depth tutorial, see [this
page](net/grpc/gateway/examples/echo/tutorial.md).

Setting Deadline


You can set a deadline for your RPC by setting a deadline header. The value
should be a Unix timestamp, in milliseconds.

  1. ``` js
  2. var deadline = new Date();
  3. deadline.setSeconds(deadline.getSeconds() + 1);

  5. client.sayHelloAfterDelay(request, {deadline: deadline.getTime().toString()},
  6.   (err, response) => {
  7.     // err will be populated if the RPC exceeds the deadline
  8.     ...
  9.   });
  10. ```

TypeScript 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.ts typings
- import_style=typescript: full TypeScript output

Do not use import_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 using mode=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

  1. ```sh
  2. $ protoc -I=$DIR echo.proto \
  3.   --js_out=import_style=commonjs,binary:$OUT_DIR \
  4.   --grpc-web_out=import_style=typescript,mode=grpcweb:$OUT_DIR
  5. ```

It will generate the following files:

echo_grpc_web_pb.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 for echo_pb.js.

  1. ```ts
  2. import * as grpcWeb from 'grpc-web';
  3. import {EchoServiceClient} from './echo_grpc_web_pb';
  4. import {EchoRequest, EchoResponse} from './echo_pb';

  6. const echoService = new EchoServiceClient('http://localhost:8080', null, null);

  8. const request = new EchoRequest();
  9. request.setMessage('Hello World!');

  11. const call = echoService.echo(request, {'custom-header-1': 'value1'},
  12.   (err: grpcWeb.RpcError, response: EchoResponse) => {
  13.     console.log(response.getMessage());
  14.   });
  15. call.on('status', (status: grpcWeb.Status) => {
  16.   // ...
  17. });
  18. ```

For the full TypeScript example, see
ts-example/client.ts.

Ecosystem


Proxy Interoperability


Multiple proxies support the gRPC-web protocol.

1. The current default proxy is [Envoy][], which supports gRPC-web out of the box.

  1. ```sh
  2. $ docker-compose up -d node-server envoy commonjs-client
  3. ```

2. You can also try the [gRPC-web Go proxy][].

  1. ```sh
  2. $ docker-compose up -d node-server grpcwebproxy binary-client
  3. ```

3. Apache APISIX has also added grpc-web support, and more details can be found here.

Web Frameworks with gRPC-Web support

- Armeria (JVM)
- Tonic (Rust)

[Envoy]: https://www.envoyproxy.io
[gRPC]: https://grpc.io
[grpc-web-docs]: https://grpc.io/docs/languages/web
[gRPC-web Go Proxy]: https://github.com/improbable-eng/grpc-web/tree/master/go/grpcwebproxy
[Hello World example]: net/grpc/gateway/examples/helloworld