gaia (for node.js)
Gaia, the very framework to make gRPC services. Gaia defines a definitely intuitive way to write gRPC services.
- Handle Custom Errors
gRPC
does NOT provide an formal way to handle errors, even lack of documentation, whilegaia
will do it for you. - Manage
.proto
filesgaia
allows us to share proto files between server and clients.gaia
sharesgPRC
protobuf files by wrapping them into an npm package and publishing the npm tarball to npm registry. - Eggjs compatible plugins
gaia
supports to use egg plugins to extend your applications. - Restful API service made easy
gaia
provides a convenient way to define restful API routings upon the existing gRPC services.
gaia
supports both proto2 and proto3.
Install
$ npm i gaia
Table of Contents
Synopsis
const Server Client resolvePackage } = const root = path
To make better understanding the usage of gaia
, the example below is based on the demo in the
example/node/hello
directory.
Start server:
root
Run client:
const // service Greeter Greeter} = root const run = async { const message = await Greeter console} // Hello world
APIs
new Client(root)
Creates the gaia client.
- root
path
the root path to load the client from
client.connect(host):
Connects to the gRPC server and returns the service methods
- host
string
the server host to connect to which includes the server hostname and port and whose pattern is<hostname>:<port>
new Server(root, serverConfig?)
- root
path
the root path to load the server from - serverConfig?
ServerConfig={}
server configurations
server.listen(port): this
- port
number
the port which gRPC server will listen to.
Start the gaia server.
server.kill()
Forcibly shut down the gRPC server
await server.close()
Gracefully shut down the server
resolvePackage(id: string): string
- id
string
package id
Returns the root path of the package
gaia
makes .proto
files sharable and portable?
How gaia
takes full advantage of npm packages to share proto files.
A minimun gaia
service portable, as well as service hello
or package hello
, could be:
/path/to/hello/
|-- proto/
| |-- hello.proto
|-- package.json
And in proto/hello.proto
:
syntax = "proto3"; service Greeter { rpc SayHello (HelloRequest) returns (HelloReply) {}} message HelloRequest { string name = 1;} message HelloReply { string message = 1;}
package.json
"name": "hello" "gaia": ...
The the optional field "gaia"
of package.json follows the schema:
Apparently, package hello
has everything we need to create a client agent for service hello
.
And package hello
is language-independent which only contains proto files and client configurations.
hello
Create the client of Assume that we have a new project foo
, and we npm install hello
.
/path/to/foo/
|-- proto/
| |-- foo.proto
|-- node_modules/
| |-- hello/
|-- package.json
Then if the hello
service is already running on port 8000
, we could create a hello client by following lines:
const Client = const Greeter = '/path/to/foo/node_modules/hello'
.proto
files from hello
Import Since project foo
, as we introduced above, has a dependency hello
, we could import .proto
files from package hello
.
in /path/to/foo/proto/foo.proto
:
syntax = "proto3"; // We could install a package and import things from it// as well as we do in JavaScript es modules. Oh yeah! 😆import "hello/proto/hello.proto" service FooGreeter { // We could reuse message types from package `hello` rpc SayHello (HelloRequest) returns (HelloReply) {}}
In order to do that, we need to declare that hello
is a gaia
dependency of foo
by adding some fields in package.json:
"name": "foo" "gaia": // So that we could import .proto files from package `hello` "protoDependencies": // We have to add "hello" here. "hello" "dependencies": // This is generated by `npm install` "hello": "^1.0.0"
And gaia
will manage the --proto_path
s (includeDirs) for you, so that gRPC Protobuf Loader will know where to search and import .proto
files
includeDirs
More about gaia
recursively parses the protoDependencies
of project foo
, and its protoDependency
's protoDependencies
to generate the options.includeDirs
option for @grpc/proto-loader
gaia
Server
How to Write a Take the project hello
which introduced above for example.
Since we define a Greeter
service in hello.proto
, we must implement the corresponding controller by ourselves.
Service controllers should be defined in directory /path/to/hello/controller
which can be changed with by config controller_root
.
We must provide a Greeter.js
in that directory.
/path/to/hello/
|-- controller/
| |-- Greeter.js
in Greeter.js
, there should be an async/sync method named SayHello
in exports
because we defined a SayHello
rpc method in service Greeter
exports message: `Hello `
Packages and name resolution
First the innermost package scope is searched, then the next-innermost, and so on, and at last the service name.
Assume that we have the following protocol buffer.
package foo.bar; service Baz { rpc Quux (Req) returns (Res) {}}
Then in directory controller_root
, we need to create a JavaScript file foo/bar/Baz.js
whose exports
has a Quux
method.
this
object of the controller methods
There are several properties could be access by this
object of the controller methods.
Reusing other controllers
We could access other controller methods by
thiscontrollernamespace0namespace1...serviceNamemethodName
For example, we could access the Quux
method by
exports { const data = await thiscontrollerfoobarBaz // ... return something}
Using external services
If we provide serverConfig.services
for server
'/path/to/service/foo' ...otherConfig services: hello: // 'hello' is a gaia server package: 'hello'
Then, client of the service 'hello'
could be accessed from the service controller of foo by:
exports { const message = await thisservicehello return property: message }