gaea v6.0.0
gaea
The manager to wrap grpc services and hold .proto files.
- Handle Custom Errors
gRPC
does NOT provide an formal way to handle errors, even lack of documentation, whilegaea
will do it for you. - Manage .proto files
gaea
allows us to share proto files between server and clients.gaea
sharesgPRC
protobuf files by wrapping them into an npm package and publishing the npm tarball to npm registry. - Eggjs compatible plugins
gaea
supports to use egg plugins to extend your applications. - Restful API service made easy
gaea
provides a convenient way to define restful API routings upon the existing gRPC services.
Install
$ npm i gaea
APIs
const {
Server, Client
} = require('gaea')
const root = path.join(__dirname, 'example')
To make better understanding the usage of gaea
, the example below is based on the demo in the example/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
APIs
new Client(root, clientConfig?)
Creates the gaea client.
- root
path
the root path to load the client from - clientConfig?
BaseConfig
client configuration. If not specified,gaea
will load configuration from${root}/config.js
interface BaseConfig {
// Tells `gaea` which properties of error should be
// - collected, serialized and transmitted to the clients.
// - or deseriialized from server
// `error_props` defaults to `['code', 'message']`
error_props: Array<string>
// specifies where to load proto files.
proto_root: string
// Proto filenames inside `proto_root`.
// If not specified, gaea will use all `.proto` files inside `proto_root`.
protos?: Array<string>
}
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. If not specified,gaea
will load configuration from${root}/config.js
interface ServerConfig extends BaseConfig {
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
}
const g = gaea({
// if the server throws an `error`, gaea will collect
// - `error.code`,
// - `error.message`
// - `error.stack`,
// and send them to its clients, while other properties will be omitted.
error_props: ['code', 'message', 'stack'],
proto_root: '/path/to/example/proto'
// and read all .proto files
})
server.listen(port): void
- port
number
the port which gRPC server will listen to.
Start the gaea server.
License
If we have a foo
package in a proto file, and inside the foo
package there is a Bar
service, then we must put a foo/Bar.js
file in /path/to/example/service/
.
And if there is a Baz
rpc method in the Bar
service, we must set a Baz
function as one of the exports of the foo/Bar.js
. The Baz
function might have one argument(or no arguments) which accepts the data from the client.
Or there will be errors.
Besides, if there is a Quux
service which not in any package, we should just put a Quux.js
file in /path/to/example/service/
.
5 years ago
5 years ago
5 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago