egg-grpc
grpc plugin for egg
Install
$ npm i egg-grpc --save
// {app_root}/config/plugin.jsexportsgrpc = enable: true package: 'egg-grpc';
Configuration
// {app_root}/config/config.default.jsexportsgrpc = endpoint: 'localhost:50051' // dir: 'app/proto', // proto files dir, relative path // property: 'grpc', // default attach to `ctx.grpc.**` // loadOpts: { convertFieldsToCamelCase: true, }, // message field case: `string user_name` -> `userName`;
see config/config.default.js for more detail.
Usage
fixtures:
app/proto├── egg│ └── test│ ├── game.proto│ └── message.proto├── uc│ └── test.proto└── share.proto
// app/proto/share.protosyntax = "proto3"; package egg.share; message Status { string code = 1; string err_msg = 2;} service ShowCase { rpc Echo(Status) returns (Status) {}}
quickstart:
// mount by `package` define, not proto file pathconst client = ctxgrpceggshareshowCase;const result = client;console;
Folder Structure
- default to load proto files from
app/proto
. - file path is only use for file manager, it DON'T affect the proto class path at
ctx
andapp
. - such as
app/proto/share.proto
, it defined aspackage egg;
, so will visit asyield ctx.grpc.egg.share.showCase.echo(data, meta, options)
new app.grpcProto.egg.share.Status({ code: 200 })
new app.grpcProto.egg.share.ShowCase(address)
new ctx.grpcProto.egg.share.ShowCase(address)
Name Conversion
term | case at proto | case when load |
---|---|---|
package | lowercase with . |
camleCase if contains _ |
service | PascalCase | camleCase when initialize at ctx |
rpc | PascalCase | camleCase |
message | PascalCase | PascalCase at app |
field | snake_case | camleCase |
enums | CONSTANT_CASE | CONSTANT_CASE |
API
Custom Options
- {Number}
timeout
- for convenient usage ofdeadline
, equals to{ deadline: Date.now() + timeout }
Service && Message
You can get service instance and invoke rpc by ctx.mypackage.myService.myRpc({ id: 1 })
.
Usually, you don't need to instantiate a message instace, grpc will do it for you, however you can create it by new app.grpcProto.mypackage.SomeMessage({ id: 1 })
.
Unary RPC
/** * Unary RPC, such as `rpc Echo(Request) returns (Response) {}` * @param * @param * @param * @return * @see http://www.grpc.io/docs/guides/concepts.html#unary-rpc */// const client = ctx.grpc.<package>.<service>; client; client;
Client Streaming RPC
/** * Client Streaming RPC, such as `rpc EchoClientStream(stream Request) returns (Response) {}` * @param * @param * @param * @return * @see http://www.grpc.io/docs/guides/concepts.html#client-streaming-rpc */const stream = client;// const stream = client.echoClientStream(callback);// const stream = client.echoClientStream(meta, callback);// trigger order: metadata -> callback -> statusstream;stream;stream;// send data to server or endstream;stream;stream;
Server Streaming RPC
/** * Server Streaming RPC, such as `rpc EchoServerStream(Request) returns (stream Response) {}` * @param * @param * @param * @return * @see http://www.grpc.io/docs/guides/concepts.html#server-streaming-rpc */const stream = client;// trigger order: metadata -> data -> status -> endstream;stream;stream;stream;stream;
Bidirectional Streaming RPC
/** * Bidirectional Streaming RPC, such as `rpc echoStreamStream(stream Request) returns (stream Response) {}` * @param * @param * @return * @see http://www.grpc.io/docs/guides/concepts.html#bidirectional-streaming-rpc */const stream = client;// trigger order: metadata -> data -> status -> endstream;stream;stream;stream;stream;// send data to server or endstream;stream;stream;
Example
see grpc.tests.js.
Questions & Suggestions
Please open an issue here.