Gaia, the very framework to make gRPC services. Gaia defines a definitely intuitive way to write gRPC services.
gRPC
does NOT provide an formal way to handle errors, even lack of documentation, while gaia
will do it for you..proto
files gaia
allows us to share proto files between server and clients. gaia
shares gPRC
protobuf files by wrapping them into an npm package and publishing the npm tarball to npm registry.gaia
supports to use egg plugins to extend your applications.gaia
provides a convenient way to define restful API routings upon the existing gRPC services.gaia
supports both proto2 and proto3.
$ npm i gaia
const {
Server,
Client,
resolvePackage
} = require('gaia')
const root = path.join(__dirname, 'example', 'hello')
To make better understanding the usage of gaia
, the example below is based on the demo in the
example/node/hello
directory.
Start server:
new Server(root).listen(50051)
Run client:
const {
// service Greeter
Greeter
} = new Client(root).connect('localhost:50051')
const run = async () => {
const {message} = await Greeter.sayHello({name: 'world'})
console.log(message)
}
run()
// Hello world
Creates the gaia client.
path
the root path to load the client fromConnects to the gRPC server and returns the service methods
string
the server host to connect to which includes the server hostname and port and whose pattern is <hostname>:<port>
path
the root path to load the server fromServerConfig={}
server configurationsinterface ServerConfig {
// Defines where to load controllers
controller_root?: string = 'controller'
plugins?: Array<Plugin>
services?: Services
}
interface Package {
// The root path of the package
path?: string
// The package name of the package
package?: string
// Either path or package should be defined.
}
interface Plugin extends Package {
// Configurations for the plugin
config: object
}
interface Service extends Package {
// the host param of `client.connect(host)`
host: string
}
interface Services {
[name: string]: Service
}
number
the port which gRPC server will listen to.Start the gaia server.
Forcibly shut down the gRPC server
Gracefully shut down the server
string
package idReturns the root path of the package
new Client(resolvePackage('foo')).connect(host)
gaia
makes .proto
files sharable and portable?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:
interface FieldGaia {
// Tells `gaia` which properties of error should be
// - collected, serialized and transmitted to the clients.
// - or deseriialized from server
// `errorProps` defaults to `['code', 'message']`
// if the server throws an `error`, by default, gaia will collect
// - `error.code`,
// - `error.message`
// and send them to its clients, while other properties will be omitted.
errorProps?: Array<string> = ['code', 'message']
// Specifies where to load proto files.
// `protoPath` should be a relative path to `root`
protoPath?: string = 'proto'
// Proto filenames inside `protoPath`.
// If not specified, gaia will search all `*.proto` files inside `protoPath`.
protos?: Array<string> | string = '*.proto'
// See section #import-proto-files-from-hello below
protoDependencies?: Array<string> = []
}
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
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} = require('gaia')
const {Greeter} = new Client('/path/to/foo/node_modules/hello').connect('localhost:8000')
.proto
files from hello
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
gaia
recursively parses the protoDependencies
of project foo
, and its protoDependency
's protoDependencies
to generate the options.includeDirs
option for @grpc/proto-loader
gaia
ServerTake 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.sayHello = ({name}) => ({
message: `Hello ${name}`
})
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 methodsThere are several properties could be access by this
object of the controller methods.
We could access other controller methods by
this.controller[namespace0][namespace1]...[serviceName][methodName]
For example, we could access the Quux
method by
exports.OtherMethodsOfSomeService = async function (request) {
const data = await this.controller.foo.bar.Baz.Quux(request)
// ...
return something
}
If we provide serverConfig.services
for server
new Server('/path/to/service/foo', {
...otherConfig,
services: {
hello: {
// 'hello' is a gaia server
package: 'hello'
}
}
})
.listen(port)
Then, client of the service 'hello'
could be accessed from the service controller of foo by:
exports.Quux = async function ({name}) {
const {message} = await this.service.hello.SayHello({name})
return {
property: message
}
}