@improbable-eng/grpc-web

Library for making gRPC-Web requests from a browser

This library is intended for both JavaScript and TypeScript usage from a web browser or NodeJS (see Usage with NodeJS).

Note: This only works if the server supports gRPC-Web

A Golang gRPC-Web middleware and a Golang-based gRPC-Web proxy are available here.

Please see the full gRPC-Web README for known limitations.

Installation

@improbable-eng/grpc-web has peer dependencies of google-protobuf and @types/google-protobuf.

npm install google-protobuf @types/google-protobuf @improbable-eng/grpc-web --save

Example Project

There is an example project available here

Usage Overview

• Use ts-protoc-gen with protoc to generate .js and .d.ts files for your request and response classes. ts-protoc-gen can also generate gRPC service definitions with the service=true argument.
  • Go to code generation docs
• Make a request using unary(), invoke() or client()

1import {grpc} from "@improbable-eng/grpc-web";
2
3// Import code-generated data structures.
4import {BookService} from "./generated/proto/examplecom/library/book_service_pb_service";
5import {GetBookRequest} from "./generated/proto/examplecom/library/book_service_pb";
6
7const getBookRequest = new GetBookRequest();
8getBookRequest.setIsbn(60929871);
9grpc.unary(BookService.GetBook, {
10  request: getBookRequest,
11  host: host,
12  onEnd: res => {
13    const { status, statusMessage, headers, message, trailers } = res;
14    if (status === grpc.Code.OK && message) {
15      console.log("all ok. got book: ", message.toObject());
16    }
17  }
18});

• Requests can be aborted/cancelled before they complete:

1const request = grpc.unary(BookService.GetBook, { ... });
2request.cancel();

Available Request Functions

There are three functions for making gRPC requests:

grpc.unary

This is a convenience function for making requests that consist of a single request message and single response message. It can only be used with unary methods.

1rpc GetBook(GetBookRequest) returns (Book) {}

grpc.invoke

This is a convenience function for making requests that consist of a single request message and a stream of response messages (server-streaming). It can also be used with unary methods.

1rpc GetBook(GetBookRequest) returns (Book) {}
2rpc QueryBooks(QueryBooksRequest) returns (stream Book) {}

grpc.client

grpc.client returns a client. Dependant upon transport compatibility this client is capable of sending multiple request messages (client-streaming) and receiving multiple response messages (server-streaming). It can be used with any type of method, but will enforce limiting the sending of messages for unary methods.

1rpc GetBook(GetBookRequest) returns (Book) {}
2rpc QueryBooks(QueryBooksRequest) returns (stream Book) {}
3rpc LogReadPages(stream PageRead) returns (google.protobuf.Empty) {}
4rpc ListenForBooks(stream QueryBooksRequest) returns (stream Book) {}

Usage with NodeJS

Refer to grpc-web-node-http-transport.

All Docs

• unary()
• invoke()
• client()
• Code Generation
• Concepts
• Transport