tenebrous-dicebot/api/node_modules/@improbable-eng/grpc-web/README.md

95 lines
3.8 KiB
Markdown
Raw Normal View History

# @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)