Skip to main content

Gaia, the very framework to make gRPC services

Project description

Build Status Coverage


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, while gaia will do it for you.
  • Manage .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.
  • 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.


$ npm i gaia

Table of Contents


const {
} = 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/hello directory.

Start server:

new Server(root).listen(50051)

Run client:

const {
  // service Greeter
} = new Client(root).connect('localhost:50051')

const run = async () => {
  const {message} = await Greeter.sayHello({name: 'world'})


// Hello world


new Client(root)

Creates the gaia client.

  • root path the root path to load the client from


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
interface 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

server.listen(port): this

  • port number the port which gRPC server will listen to.

Start the gaia server.


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

new Client(resolvePackage('foo')).connect(host)

How 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:

  |-- 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;


  "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.

Create the client of hello

Assume that we have a new project foo, and we npm install hello.

  |-- 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')

Import .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.
  "dependencies": {
    // This is generated by `npm install`
    "hello": "^1.0.0"

And gaia will manage the --proto_paths (includeDirs) for you, so that gRPC Protobuf Loader will know where to search and import .proto files

More about includeDirs

gaia recursively parses the protoDependencies of project foo, and its protoDependency's protoDependencies to generate the options.includeDirs option for @grpc/proto-loader

How to Write a gaia Server

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.

  |-- 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}`

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.


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


For example, we could access the Quux method by

exports.OtherMethodsOfSomeService = async function (request) {
  const data = await
  // ...
  return something

Using external services

If we provide for server

new Server('/path/to/service/foo', {
  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.Quux = async function ({name}) {
  const {message} = await this.service.hello.SayHello({name})
  return {
    property: message

Using plugins



Project details

Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for, version 0.1.0
Filename, size File type Python version Upload date Hashes
Filename, size (6.9 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size (7.8 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page