This tutorial provides a basic introduction on how to usegRPC-Web from browsers.

By walking through this example you’ll learn how to:

• Define a service in a .proto file.
• Generate client code using the protocol buffer compiler.
• Use the gRPC-Web API to write a simple client for your service.

It assumes a passing familiarity with.

With gRPC you can define your service once in a .proto file and implementclients and servers in any of gRPC’s supported languages, which in turn can berun in environments ranging from servers inside Google to your own tablet - allthe complexity of communication between different languages and environments ishandled for you by gRPC. You also get all the advantages of working withprotocol buffers, including efficient serialization, a simple IDL, and easyinterface updating. gRPC-Web lets you access gRPC services built in this mannerfrom browsers using an idiomatic API.

Define the Service

The first step when creating a gRPC service is to define the service methodsand their request and response message types using protocol buffers. In thisexample, we define our in a file called.For more information about protocol buffers and proto3 syntax, please see theprotobuf documentation.

Next, we implement our EchoService interface using Node in the backend gRPCEchoServer. This will handle requests from clients. See the filefor details.

function doEcho(call, callback) {
  callback(null, {message: call.request.message});
}

Configure the Envoy Proxy

In this example, we will use theproxy to forward the gRPC browser request to the backend server. You can seethe complete config file inenvoy.yaml

To forward the gRPC requests to the backend server, we need a block likethis:

  listeners:
  - name: listener_0
    address:
      socket_address: { address: 0.0.0.0, port_value: 8080 }
    filter_chains:
    - filters:
      - name: envoy.http_connection_manager
          codec_type: auto
          stat_prefix: ingress_http
          route_config:
            name: local_route
            virtual_hosts:
            - name: local_service
              domains: ["*"]
              routes:
                route: { cluster: echo_service }
          http_filters:
          - name: envoy.grpc_web
          - name: envoy.router
  clusters:
  - name: echo_service
    connect_timeout: 0.25s
    type: logical_dns
    http2_protocol_options: {}
    lb_policy: round_robin

You may also need to add some CORS setup to make sure the browser can requestcross-origin content.

In this simple example, the browser makes gRPC requests to port :8080. Envoyforwards the request to the backend gRPC server listening on port :9090.

To generate the protobuf message classes from our echo.proto, run thefollowing command:

The import_style option passed to the —js_out flag makes sure thegenerated files will have CommonJS style require() statements.

$ cd grpc-web
$ sudo make install-plugin

To generate the service client stub file, run this command:

$ protoc -I=$DIR echo.proto \
  --grpc-web_out=import_style=commonjs,mode=grpcwebtext:$OUT_DIR

In the param above:

• mode can be grpcwebtext (default) or grpcweb
• import_style can be closure (default) or commonjs

Our command generates the client stub, by default, to the fileecho_grpc_web_pb.js.

Write JS Client Code

Now you are ready to write some JS client code. Put this in a client.js file.

You will need a package.json file

{
  "name": "grpc-web-commonjs-example",
  "dependencies": {
    "google-protobuf": "^3.6.1",
    "grpc-web": "^0.4.0"
  },
  "devDependencies": {
    "browserify": "^16.2.2",
    "webpack": "^4.16.5",
    "webpack-cli": "^3.1.0"
  }
}

Finally, putting all these together, we can compile all the relevant JS filesinto one single JS library that can be used in the browser.

$ npm install