gRPC-Web Basics.

grpc-web.md

gRPC-Web Basics.

Protocol

• gRPC-Web
• gRPC

Let's Create a Sample App

Create a greet service and client.

Platform

• Client
  • Chrome
• Proxy server
  • Docker for Mac
• gRPC server
  • Mac

Install Protocol Buffer Compiler

Protocol Buffer Compiler (protoc) is a compiler to generate client/server and data structure code for specific language from .proto file.

brew install protobuf
brew install protoc-gen-grpc-web # plugin for grpc-web

Define the Service

Define the service using protocol buffers.

// greet.proto

syntax = "proto3";

package greet;

service Greet {
  rpc SayHello(HelloRequest) returns (HelloReply);
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

Implement the Service

Implement the service with NodeJS.

var PROTO_PATH = __dirname + '/path/to/greet.proto';

var assert = require('assert');
var grpc = require('@grpc/grpc-js');
var protoLoader = require('@grpc/proto-loader');
var packageDefinition = protoLoader.loadSync(
    PROTO_PATH,
    {keepCase: true,
     longs: String,
     enums: String,
     defaults: true,
     oneofs: true
    });
var protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
var greet = protoDescriptor.greet;

function doSayHello(call, callback) {
  callback(null, {message: 'Hello! ' + call.request.name});
}

function getServer() {
  var server = new grpc.Server();
  server.addService(greet.Greet.service, { sayHello: doSayHello });
  return server;
}

if (require.main === module) {
  var server = getServer();
  server.bindAsync(
    '0.0.0.0:9090', grpc.ServerCredentials.createInsecure(), (err, port) => {
      assert.ifError(err);
      server.start();
  });
  console.log('Listening port 9090.');
}

exports.getServer = getServer;

Configure Proxy

We need to configure the Envoy proxy to forward the browser's gRPC-Web requests to the gRPC server.

# envoy.yaml

admin:
  access_log_path: /tmp/admin_access.log
  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.filters.network.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:
            name: local_route
            virtual_hosts:
            - name: local_service
              domains: ["*"]
              routes:
              - match: { prefix: "/" }
                route:
                  cluster: greeter_service
                  max_stream_duration:
                    grpc_timeout_header_max: 0s
              cors:
                allow_origin_string_match:
                - prefix: "*"
                allow_methods: GET, PUT, DELETE, POST, OPTIONS
                allow_headers: keep-alive,user-agent,cache-control,content-type,content-transfer-encoding,custom-header-1,x-accept-content-transfer-encoding,x-accept-response-streaming,x-user-agent,x-grpc-web,grpc-timeout
                max_age: "1728000"
                expose_headers: custom-header-1,grpc-status,grpc-message
          http_filters:
          - name: envoy.filters.http.grpc_web
          - name: envoy.filters.http.cors
          - name: envoy.filters.http.router
  clusters:
  - name: greeter_service
    connect_timeout: 0.25s
    type: logical_dns
    http2_protocol_options: {}
    lb_policy: round_robin
    # win/mac hosts: Use address: host.docker.internal instead of address: localhost in the line below
    load_assignment:
      cluster_name: cluster_0
      endpoints:
        - lb_endpoints:
            - endpoint:
                address:
                  socket_address:
                    address: host.docker.internal
                    port_value: 9090

Implement Client

First, generate protobuf message and service client stub.

DIR=/path/to/proto/directory
OUT_DIR=/path/to/output

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

Then, use generated code. This time, I will use Angular for sample.

import { Component, OnInit } from '@angular/core';
import { GreetClient } from './api/GreetServiceClientPb';
import { HelloRequest } from './api/greet_pb';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html'
})
export class AppComponent implements OnInit {
  readonly client = new GreetClient('http://localhost:8080');

  ngOnInit() {
    const request = new HelloRequest();
    request.setName('ytakagi');
    this.client.sayHello(request, {});
  }
}

Run Sample App

Run server.

node server.js

Run proxy server.

docker run -d -v "$(pwd)"/envoy.yaml:/etc/envoy/envoy.yaml:ro -p 8080:8080 -p 9901:9901 envoyproxy/envoy:v1.17.0

Run Angular app.

npm run start

Reference

• gRPC-Web example