gRPC-Core
A simple & minimal helpers for creating high performance gRPC microservices.
This package will simplify the creation of gRPC servers and services, you will just need to extend base GrpcService and implement remote functions, this library will turn your normal functions into gRPC callable functions, which makes it easy to create microservices in a clean way.
Basic microservice archticture using helpers in this library
- You need to be familiar with gRPC and protocol buffers.
- Example in this package uses the proto3 version of the protocol buffers language.
- You can find out more about gRPC and proto3 in References section.
Installation
npm install grpc-core --save
Package Components
- GrpcServer: Main entry point to gRPC microservice
- GrpcService: Service endpoint
- GrpcClient: gRPC client to call service methods remotly
1- gRPC Server
You will need to create a new instance from GrpcServer with appropriate configurations then start your server.
You can register one or more gRPC services with the same server
Example:
const GrpcServer = ;const UsersService = ;const database = ; const server = host: 'localhost' port: 3000 services: UsersService onStart: async { return database; } { console; }; serverstart;
GrpcService constructor(config)
Name | Type | Description | |
---|---|---|---|
host | string |
Server host | |
port | number |
Server port | |
services | Array.<GrpcService> |
Array of GrpcService derived classes to be exposed | |
onConnected | function |
Function to be executed after server connection | Optional |
onStart | function |
Function to be executed before server start (ex. db connection) | Optional |
onClose | function |
Function to be executed before server shutdown (ex. close db connection) | Optional |
2- gRPC Service
You will need to create your own service class which extends GrpcService class, and normal class methods will ne callable from your GrpcClient.
- Async methods are supported.
- Methods starts with _
underscore
will be ignored and considered private, so it will not be exposed into your gRPC service, even if you expose it in your protobuf schema, so it will get missing implementation error.
Example:
const path = ;const GrpcService = ;const hooks = ;const middlewares = ;const PROTO = path;const User = ; { super proto: PROTO hooks: hooks middlewares: middlewares ; } // Private method (will not be callable) async { return user_id; } async { return User; } async { try const body = ctxrequest; await ctx; return User; catcherr throw err; } async { try const _id = ctxrequest_id; // Your update code return updated: true; catcherr throw err; } async { try const _id = ctxrequest_id; // Your delete code return delete: true; catcherr throw err; }
GrpcService Hooks
Hooks are simply helper functions to be attached to request context (ctx) object, which will be passed later to callee function.
Hooks are passed to GrpcService as an object which contains all hook functions
Ex. if we need the request context object to have our own validation function, we will need to define this in hooks:
// hooks.jsmoduleexports = { // Validation logic here };
// Then use it in service definitionconst GrpcService = ;const hooks = ;const proto = path; { super proto hooks ; } // within our remote function implementation, // hook function will be attached to context object for convenience. async { try const user = ctxrequest; // validate function attached to context object ctx; // add user logic return user; catcherr throw err; } moduleexports = ;
GrpcService Middlewares
Middlewares are just functions that will be execute in order before service function and will have the request context as an argument, so inside middleware you can manipulate request data, or request context itself
Middlewares are passed to GrpcService as an array of functions
Ex. Adding middleware to parse request metadata and add it to params field:
// middlewares.jsmoduleexports = // Metadata parser { try const md = ctxmetadata; if md ctxparams = md; catch err throw err; };
// Then use it in service definitionconst GrpcService = ;const middlewares = ;const proto = path; { super proto middlewares ; } // within our remote function implementation, // ctx object should contain [params] field if caller passed any metadata async { try const params = ctxparams; return params; catcherr throw err; }
3- gRPC Client
GrpcClient instance is required to call remote GrpcService functions, It has only one function "call" which enable a simple way call remote functions.
Creating new GrpcClient:
// usersClient.jsconst path = ;const GrpcClient = ;const usersProto = path; moduleexports = proto: usersProto service: 'UsersService' url: 'localhost:3000';
Using GrpcClient:
const client = ; { try const result = await client; catcherr throw err; }
TODO
- Example - API Gateway with simple services
- gRPC errors handling
References
License
MIT