Basics tutorial

This tutorial provides a basic introduction on how to use gRPC-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 protocol buffers.

Why use gRPC and gRPC-Web?

With gRPC you can define your service once in a .proto file and implement clients and servers in any of gRPC’s supported languages, which in turn can be run in environments ranging from servers inside a large data center to your own tablet - all the complexity of communication between different languages and environments is handled for you by gRPC. You also get all the advantages of working with protocol buffers, including efficient serialization, a simple IDL, and easy interface updating. gRPC-Web lets you access gRPC services built in this manner from browsers using an idiomatic API.

Define the Service

The first step when creating a gRPC service is to define the service methods and their request and response message types using protocol buffers. In this example, we define our EchoService in a file called echo.proto. For more information about protocol buffers and proto3 syntax, please see the protobuf documentation.

message EchoRequest {
  string message = 1;
}

message EchoResponse {
  string message = 1;
}

service EchoService {
  rpc Echo(EchoRequest) returns (EchoResponse);
}

Implement gRPC Backend Server

Next, we implement our EchoService interface using Node in the backend gRPC EchoServer. This will handle requests from clients. See the file node-server/server.js for details.

You can implement the server in any language supported by gRPC. Please see the main page for more details.

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

Configure the Envoy Proxy

In this example, we will use the Envoy proxy to forward the gRPC browser request to the backend server. You can see the complete config file in envoy.yaml

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

admin:
  address:
    socket_address: { address: 0.0.0.0, port_value: 9901 }

static_resources:
  listeners:
  - name: listener_0
    address:
      socket_address: { address: 0.0.0.0, port_value: 8080 }
    filter_chains:
    - filters:
      - name: envoy.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          codec_type: auto
          stat_prefix: ingress_http
          route_config: