README.md

gRPC-Web-Rx

gRPC-Web-Rx is a TypeScript library that integrates gRPC-Web with RxJS. gRPC-Web-Rx provides a convenience from operator that you can use to wrap your gRPC call to obtain an Observable of the response. Currently unary and server streaming RPCs are supported.

gRPC Call Type	Input and Output Types
Unary	Request => Observable<Response>
Server streaming	Request => Observable<Response>
Client streaming	Not yet supported by gRPC-Web
Bidirectional streaming	Not yet supported by gRPC-Web

Usage

You can install the grpc-web-rx module via npm:

npm i grpc-web-rx

Let's look at a hypothetical Todo service, defined using Protocol Buffers as:

syntax = "proto3";
package wisetime.todo.v1;

service TodoService {
  // Use this unary RPC to create todo items.
  rpc CreateTodo(CreateTodoRequest) returns (Todo);
  
  // Subscribe to this server streaming RPC to receive todo list updates.
  rpc WatchTodos(WatchTodosRequest) returns (stream TodoList);
}

message Todo {
  string id = 1;
  string title = 2;
  bool completed = 3;
}

message CreateTodoRequest {
  string title = 1;
}

message WatchTodosRequest {}

message TodoList {
  repeated Todo todos = 1;
}

In order to use gRPC-Web, we need to generate the client library from using protoc and the gRPC-Web protoc plugin:

protoc -I=src/protobuf src/protobuf/todo.proto \
  --js_out=import_style=commonjs,binary:src/generated \
  --grpc-web_out=import_style=typescript,mode=grpcwebtext:src/generated

The from Operator

The from operator executes a gRPC call and provides an Observable of the response.

import { from } from "grpc-web-rx"
import { CreateTodoRequest, WatchTodoRequest } from "./generated/todo_pb"
import { TodoServiceClient } from "./generated/TodoServiceClientPb"

const client = new TodoServiceClient("http://localhost:8080")

// An example unary call.
from(() => client.createTodo(new CreateTodoRequest().setTitle("Buy milk")))
  .subscribe(
    response => console.log(`Todo created with ID: ${response.id}`),
    error => console.error(`Received error status code: ${error.code}`)
  )

// An example server streaming call: Subscribing to an update stream.
from(() => client.watchTodos(new WatchTodosRequest()))
  .subscribe({
    next: todos => console.log(`Received updated todo list: ${todos}`),
    error: error => console.error(`Received error status code: ${error.code}`),
    complete: () => console.log("Notification stream has ended")
  })

Automatic Retries

gRPC-Web-Rx also provides a retry operator for retrying calls that fail with a non-OK gRPC Status.

In the following example, we configure a RetryPolicy that will retry calls that fail with status code PERMISSION_DENIED. The call is retried up to 3 times with an initial delay of 200ms. The delay increases exponentially for each subsequent attempt. In this example, the refreshIdToken() function is called before each attempt.

import Grpc from "grpc-web"
import { from, retry, withExponentialDelay } from "grpc-web-rx"
import { CreateTodoRequest } from "./generated/todo_pb"

const policy = {
  shouldRetry: error => error.code == Grpc.StatusCode.PERMISSION_DENIED,
  maxRetries: 3,
  beforeRetry: withExponentialDelay(200)(refreshIdToken()),
}

from(() => client.createTodo(new CreateTodoRequest().setTitle("Very important task!")))
  .pipe(retry(policy))
  .subscribe(
    response => console.log(`Todo created with ID: ${response.id}`),
    error => console.error(`Received error status code: ${error.code}`)
  )

Contributing

You will need to install the following tools to work on gRPC-Web-Rx:

• protoc
• protoc-gen-grpc-web
• Docker is needed to run a local Envoy proxy for integration tests

Run tests by executing the following command:

$ make test-local

This starts a local gRPC node server together with an Envoy proxy (via Docker) where the tests will be run against.