95 lines
3.8 KiB
Markdown
95 lines
3.8 KiB
Markdown
|
# @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](#usage-with-nodejs)).
|
||
|
|
|
||
|
|
*Note: This only works if the server supports [gRPC-Web](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md)*
|
||
|
|
|
||
|
|
A Golang gRPC-Web middleware and a Golang-based gRPC-Web proxy are [available here](https://github.com/improbable-eng/grpc-web).
|
||
|
|
|
||
|
|
Please see the full [gRPC-Web README](https://github.com/improbable-eng/grpc-web) 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](https://github.com/improbable-eng/grpc-web/tree/master/client/grpc-web-react-example)
|
||
|
|
|
||
|
|
## Usage Overview
|
||
|
|
* Use [`ts-protoc-gen`](https://www.npmjs.com/package/ts-protoc-gen) with [`protoc`](https://github.com/google/protobuf) 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](docs/code-generation.md)
|
||
|
|
* Make a request using [`unary()`](docs/unary.md), [`invoke()`](docs/invoke.md) or [`client()`](docs/client.md)
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
import {grpc} from "@improbable-eng/grpc-web";
|
||
|
|
|
||
|
|
// Import code-generated data structures.
|
||
|
|
import {BookService} from "./generated/proto/examplecom/library/book_service_pb_service";
|
||
|
|
import {GetBookRequest} from "./generated/proto/examplecom/library/book_service_pb";
|
||
|
|
|
||
|
|
const getBookRequest = new GetBookRequest();
|
||
|
|
getBookRequest.setIsbn(60929871);
|
||
|
|
grpc.unary(BookService.GetBook, {
|
||
|
|
request: getBookRequest,
|
||
|
|
host: host,
|
||
|
|
onEnd: res => {
|
||
|
|
const { status, statusMessage, headers, message, trailers } = res;
|
||
|
|
if (status === grpc.Code.OK && message) {
|
||
|
|
console.log("all ok. got book: ", message.toObject());
|
||
|
|
}
|
||
|
|
}
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
* Requests can be aborted/cancelled before they complete:
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
const request = grpc.unary(BookService.GetBook, { ... });
|
||
|
|
request.cancel();
|
||
|
|
```
|
||
|
|
|
||
|
|
## Available Request Functions
|
||
|
|
|
||
|
|
There are three functions for making gRPC requests:
|
||
|
|
|
||
|
|
### [`grpc.unary`](docs/unary.md)
|
||
|
|
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.
|
||
|
|
|
||
|
|
```protobuf
|
||
|
|
rpc GetBook(GetBookRequest) returns (Book) {}
|
||
|
|
```
|
||
|
|
|
||
|
|
### [`grpc.invoke`](docs/invoke.md)
|
||
|
|
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.
|
||
|
|
|
||
|
|
```protobuf
|
||
|
|
rpc GetBook(GetBookRequest) returns (Book) {}
|
||
|
|
rpc QueryBooks(QueryBooksRequest) returns (stream Book) {}
|
||
|
|
```
|
||
|
|
|
||
|
|
### [`grpc.client`](docs/client.md)
|
||
|
|
`grpc.client` returns a client. Dependant upon [transport compatibility](docs/transport.md) 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.
|
||
|
|
|
||
|
|
```protobuf
|
||
|
|
rpc GetBook(GetBookRequest) returns (Book) {}
|
||
|
|
rpc QueryBooks(QueryBooksRequest) returns (stream Book) {}
|
||
|
|
rpc LogReadPages(stream PageRead) returns (google.protobuf.Empty) {}
|
||
|
|
rpc ListenForBooks(stream QueryBooksRequest) returns (stream Book) {}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Usage with NodeJS
|
||
|
|
Refer to [grpc-web-node-http-transport](https://www.npmjs.com/package/@improbable-eng/grpc-web-node-http-transport).
|
||
|
|
|
||
|
|
## All Docs
|
||
|
|
|
||
|
|
* [unary()](docs/unary.md)
|
||
|
|
* [invoke()](docs/invoke.md)
|
||
|
|
* [client()](docs/client.md)
|
||
|
|
* [Code Generation](docs/code-generation.md)
|
||
|
|
* [Concepts](docs/concepts.md)
|
||
|
|
* [Transport](docs/transport.md)
|