@fresh8/nestjs-grpc-transport
TypeScript icon, indicating that this package has built-in type declarations

2.2.0 • Public • Published

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.

Dependents (0)

Package Sidebar

Install

npm i @fresh8/nestjs-grpc-transport

Weekly Downloads

11

Version

2.2.0

License

MIT

Last publish

Collaborators

  • t-leung-sportradar
  • jbellsr
  • toby_c_sr
  • domdo.es
  • sraugier
  • markdavies618
  • joestefan
  • maxweston
  • f8
  • samstefan
  • mattdaviesf8
  • gabriellfsouza
  • phl3bas