node package manager
We need your input. Help make JavaScript better: Take the 2017 JavaScript Ecosystem survey »

@fresh8/nestjs-grpc-transport

Nestjs-grpc-transport

CircleCI Coverage Status styled with prettier

GRPC transport layer for the NestJS framework.

Requirements

  • Typescript 2.x
  • Node boron
  • Npm 5.x
  • NestJS v3.0.1 (there is breaking change in v3.1.1).

Installation

npm install @fresh8/nestjs-grpc-transport --save

Quickstart

Create your protobuf definition sample.proto:

syntax = "proto3";
 
package sample;
 
service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}
 
message HelloRequest {
  string name = 1;
}
 
message HelloReply {
  string message = 1;
}

Generate your Typescript interfaces using rxjs-grpc.

./node_modules/.bin/rxjs-grpc -o grpc-namespaces.ts *.proto

Create your first controller. The @rpc decorator provides some metadata needed by Nest, and takes care of providing an Observable for rxjs-grpc.

import { Controller } from '@nestjs/common'
import { rpc } from '@fresh8/nestjs-grpc-transport'
 
import { sample } from './grpc-namespaces'
 
@Controller()
export default class TestController {
  /**
   * sayHello RPC method
   */
  @rpc
  async sayHello(request: sample.HelloRequest): Promise<sample.HelloReply> {
    const res = await this.someAsyncThing()
    return { message: `Hello ${request.name}${res}` }
  }
  
  /**
   * Some dummy async method. This might be a call to a database in
   * a proper application.
   */
  someAsyncThing() {
    return Promise.resolve(`:)`)
  }
}
 

Create your GRPC server and provide it to your NestJS application.

import { Module } from '@nestjs/common'
import { NestFactory } from '@nestjs/core'
import { createServer } from '@fresh8/nestjs-grpc-transport'
 
import { sample } from './grpc-namespaces'
import { TestController } from './test-controller'
 
/**
 * Example application
 */
@Module({
  controllers: [TestController]
})
export class ApplicationModule {}
 
/**
 * Create a nest application that runs over GRPC.
 */
const app = NestFactory.createMicroservice(ApplicationModule, {
  strategy: createServer<sample.ServerBuilder>({
    host: '0.0.0.0',
    port: 50051,
    protoPath: `path/to/sample.proto`,
    packageName: 'sample',
    serviceName: 'Greeter'
  })
})
 
/**
 * Start your app as normal.
 */
app.listen(() => {
  console.log('GRPC server running on 0.0.0.0:50051')
})

Examples

A simple example project is provided here.

A note on Exceptions handling

Nestjs itself catches and handles exceptions as part of its Exception Filters feature. nestjs-grpc-transport only transforms it to the format expected by rxjs-grpc.

To the best of our understanding this implies:

  • Any exception that is not an instance of @nestjs/microservices/RpcException will be reported as Internal error (code 13).
  • To send errors other than Internal simply throw a new RpcException with the following property:
    • code : number: The exception code. Defaults to 13.
    • message : string: An additional message. Defaults to "Internal Server Error"
  • Exceptions are not logged.