Name: grpc-web
Owner: Improbable Engineering
Description: gRPC Web implementation for Golang and TypeScript
Created: 2016-07-28 15:58:43.0
Updated: 2018-01-18 21:16:46.0
Pushed: 2018-01-18 23:41:58.0
Size: 403
Language: TypeScript
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
gRPC is a modern, HTTP2-based protocol, that provides RPC semantics using the strongly-typed binary data format of protocol buffers across multiple languages (C++, C#, Golang, Java, Python, NodeJS, ObjectiveC, etc.)
gRPC-Web is a cutting-edge spec that enables invoking gRPC services from modern browsers.
If you are looking for gRPC support for Node.js there is an official Node.js gRPC library. This package supports Node.js, but requires that the server has the gRPC-Web compatibility layer (read on to understand more).
Components of the stack are based on Golang and TypeScript:
grpcweb
- a Go package that wraps an existing grpc.Server
as a gRPC-Web http.Handler
for both HTTP2 and HTTP/1.1.grpcwebproxy
- a Go-based stand-alone reverse proxy for classic gRPC servers (e.g. in Java or C++) that exposes their services over gRPC-Web to modern browsers.ts-protoc-gen
- a TypeScript plugin for the protocol buffers compiler that provides strongly typed message classes and method definitions.grpc-web-client
- a TypeScript gRPC-Web client library for browsers (and Node.js).With gRPC-Web, it is extremely easy to build well-defined, easy to reason about APIs between browser frontend code and microservices. Frontend development changes significantly:
.proto
is the canonical format for API contracts.grpc.invoke
.In short, gRPC-Web moves the interaction between frontend code and microservices from the sphere of hand-crafted HTTP requests to well-defined user-logic methods.
Note: You'll need to add gRPC-Web compatibility to your server through either grpcweb
or grpcwebproxy
.
API Docs for grpc-web-client
can be found here
For a self-contained demo of a Golang gRPC service called from a TypeScript project, see example. It contains most of the initialization code that performs the magic. Here's the application code extracted from the example:
You use .proto
files to define your service. In this example, one normal RPC (GetBook
) and one server-streaming RPC (QueryBooks
):
ax = "proto3";
age Book {
t64 isbn = 1;
ring title = 2;
ring author = 3;
age GetBookRequest {
t64 isbn = 1;
age QueryBooksRequest {
ring author_prefix = 1;
ice BookService {
c GetBook(GetBookRequest) returns (Book) {}
c QueryBooks(QueryBooksRequest) returns (stream Book) {}
And implement it in Go (or any other gRPC-supported language):
rt pb_library "../_proto/examplecom/library"
bookService struct{
books []*pb_library.Book
(s *bookService) GetBook(ctx context.Context, bookQuery *pb_library.GetBookRequest) (*pb_library.Book, error) {
for _, book := range s.books {
if book.Isbn == bookQuery.Isbn {
return book, nil
}
}
return nil, grpc.Errorf(codes.NotFound, "Book could not be found")
(s *bookService) QueryBooks(bookQuery *pb_library.QueryBooksRequest, stream pb_library.BookService_QueryBooksServer) error {
for _, book := range s.books {
if strings.HasPrefix(s.book.Author, bookQuery.AuthorPrefix) {
stream.Send(book)
}
}
return nil
You will be able to access it in a browser using TypeScript (and equally JavaScript after transpiling):
rt {grpc} from "grpc-web-client";
mport code-generated data structures.
rt {BookService} from "../_proto/examplecom/library/book_service_pb_service";
rt {QueryBooksRequest, Book, GetBookRequest} from "../_proto/examplecom/library/book_service_pb";
t queryBooksRequest = new QueryBooksRequest();
yBooksRequest.setAuthorPrefix("Geor");
.invoke(BookService.QueryBooks, {
quest: queryBooksRequest,
st: "https://example.com",
Message: (message: Book) => {
console.log("got book: ", message.toObject());
End: (code: grpc.Code, msg: string | undefined, trailers: grpc.Metadata) => {
if (code == grpc.Code.OK) {
console.log("all ok")
} else {
console.log("hit an error", code, msg, trailers);
}
The grpc-web-client
uses multiple techniques to efficiently invoke gRPC services. Most modern browsers support the Fetch API, which allows for efficient reading of partial, binary responses. For older browsers, it automatically falls back to XMLHttpRequest
.
The gRPC semantics encourage you to make multiple requests at once. With most modern browsers supporting HTTP2, these can be executed over a single TLS connection. For older browsers, gRPC-Web falls back to HTTP/1.1 chunk responses.
This library is tested against:
grpc-web-client
also supports Node.js through a transport that uses the http
and https
packages. Usage does not vary from browser usage as transport is determined at runtime.
Please note - There is an official Node.js gRPC library that does not require the server to support gRPC-Web
It is very important to note that the gRPC-Web spec currently does not support client-side streaming. This is unlikely to change until new whatwg fetch/streams API lands in browsers. As such, if you plan on using gRPC-Web you're limited to:
This, however, is useful for a lot of frontend functionality.
The code here is alpha
quality. It is being used for a subset of Improbable's frontend single-page apps in production.
Browsers that don't support Fetch with body.getReader
(Currently only supported by Edge 14+, Chrome 43+ - full ReadableStream was added in Chrome 52, but only body.getReader()
is used) or XMLHttpRequest.responseType = moz-chunked-arraybuffer
(Firefox 38+) use XmlHttpRequest (XHR).
XHR keeps the entire server response in memory. This means that a long-lived or otherwise large streaming response will consume a large amount of memory in the browser and may cause instability. Fetch does not suffer from this issue. It is therefore advised that you don't use open-ended or large payload server streaming if you intend to support browsers that do not support Fetch.
You can read more about how grpc-web-client determines and uses transports here.