GRPC transport layer for the NestJS framework
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
example
src
test
.gitignore
.npmignore
LICENSE
README.md
circle.yml
package-lock.json
package.json
tsconfig-base.json
tsconfig-build.json
tsconfig.json

README.md

Nestjs-grpc-transport (deprecated)

THIS PACKAGE IS NO LONGER ACTIVELY MAINTAINED

We recommend using the officially supported gRPC Transport for Nest.

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.