@fresh8/nestjs-grpc-transport

Nestjs-grpc-transport

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.