grpc-web

gRPC Web · A JavaScript implementation of gRPC for browser clients. For more information, including a quick start, see the gRPC-web documentation. gRPC-web clients connect to gRPC services via a special proxy; by default, gRPC-web uses Envoy. In the future, we expect gRPC-web to be supported in language-specific web frameworks for languages such as Python, Java, and Node. For details, see the roadmap. Streaming Support gRPC-web currently supports 2 RPC modes: Unary RPCs (example) Server-side Streaming RPCs (example) (NOTE: Only when grpcwebtext mode is used.) Client-side and Bi-directional streaming is not currently supported (see streaming roadmap). Quick Start Eager to get started? Try the Hello World example. From this example, you'll learn how to do the following: Define your service using protocol buffers Implement a simple gRPC Service using Node.js Configure the Envoy proxy Generate protobuf message classes and client service stub for the client Compile all the JS dependencies into a static library that can be consumed by the browser easily Advanced Demo: Browser Echo App You can also try to run a more advanced Echo app from the browser with a streaming example. From the repo root directory: $ docker-compose pull prereqs node-server envoy commonjs-client $ docker-compose up node-server envoy commonjs-client Open a browser tab, and visit http://localhost:8081/echotest.html. To shutdown: docker-compose down. Runtime Library The gRPC-web runtime library is available on npm: $ npm i grpc-web Code Generator Plugins (Prerequisite) 1. Protobuf (protoc) If you don't already have protoc installed, download it first from here and install it on your PATH. If you use Homebrew (on macOS), you could run: brew install protobuf (Prerequisite) 2. Protobuf-javascript (protoc-gen-js) If you don't have protoc-gen-js installed, download it from protocolbuffers/protobuf-javascript and install it on your PATH. Or, use the third-party npm installer: npm install -g protoc-gen-js 3. Install gRPC-Web Code Generator You can download the protoc-gen-grpc-web protoc plugin from our release page: Make sure all executables are discoverable from your PATH. For example, on macOS, you can do: sudo mv protoc-gen-grpc-web-2.0.2-darwin-aarch64 \ /usr/local/bin/protoc-gen-grpc-web chmod +x /usr/local/bin/protoc-gen-grpc-web Note: If you are using our Docker setup, the prereqs image already includes both protoc and the protoc-gen-grpc-web plugin on the PATH. (Optional) 4. Verify Installations You can optionally verify the plugins work by following our Hello World example: cd net/grpc/gateway/examples/helloworld protoc -I=. helloworld.proto \ --js_out=import_style=commonjs:. \ --grpc-web_out=import_style=commonjs,mode=grpcwebtext:. After the command runs successfully, you should now see two new files generated in the current directory. By running: ls -1 *_pb.js Installation is successful if you see the following 2 files: helloworld_pb.js — Generated by protoc-gen-js plugin helloworld_grpc_web_pb.js - Generated by gRPC-Web plugin Client Configuration Options Typically, you will run the following command to generate the proto messages and the service client stub from your .proto definitions: protoc -I=$DIR echo.proto \ --js_out=import_style=commonjs:$OUT_DIR \ --grpc-web_out=import_style=commonjs,mode=grpcwebtext:$OUT_DIR You can then use Browserify, Webpack, Closure Compiler, etc. to resolve imports at compile time. Import Style import_style=closure: The default generated code has Closure goog.require() import style. import_style=commonjs: The CommonJS style require() is also supported. import_style=commonjs+dts: In addition to above, a .d.ts typings file will also be generated for the protobuf messages and service stub import_style=typescript: The service stub will be generated in TypeScript. See TypeScript Support below for information on how to generate TypeScript files. Note: The commonjs+dts and typescript styles are only supported by --grpc-web_out=import_style=..., not by --js_out=import_style=.... Wire Format Mode For more information about the gRPC-web wire format, see the specification. mode=grpcwebtext: The default generated code sends the payloads in the grpc-web-text format. Content-Type: application/grpc-web-text Payloads are base64-encoded. Both unary and server streaming calls are supported. mode=grpcweb: A binary protobuf format is also supported. Content-Type: application/grpc-web+proto Payloads are in the binary protobuf format. Only unary calls are supported. How It Works Let's take a look at how gRPC-web works with a simple example. You can find out how to build, run and explore the example yourself in Build and Run the Echo Example. 1. Define your service The first step when creating any gRPC service is to define it. Like all gRPC services, gRPC-web uses protocol buffers to define its RPC service methods and their message request and response types. message EchoRequest { string message = 1; } ... service EchoService { rpc Echo(EchoRequest) returns (EchoResponse); rpc ServerStreamingEcho(ServerStreamingEchoRequest) returns (stream ServerStreamingEchoResponse); } 2. Run the server and proxy Next you need to have a gRPC server that implements the service interface and a gateway proxy that allows the client to connect to the server. Our example builds a simple Node gRPC backend server and the Envoy proxy. For the Echo service: see the service implementation. For the Envoy proxy: see the config YAML file. 3. Write your JS client Once the server and gateway are up and running, you can start making gRPC calls from the browser! Create your client: var echoService = new proto.mypackage.EchoServiceClient( 'http://localhost:8080'); Make a unary RPC call: var request = new proto.mypackage.EchoRequest(); request.setMessage(msg); var metadata = {'custom-header-1': 'value1'}; echoService.echo(request, metadata, function(err, response) { if (err) { console.log(err.c