@fresh8/nestjs-grpc-transport
v2.2.0
Published
GRPC transport layer for the NestJS framework
Downloads
8
Maintainers
Keywords
Readme
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 asInternal
error (code 13). - To send errors other than
Internal
simply throw a new RpcException with the following property:code : number
: The exception code. Defaults to13
.message : string
: An additional message. Defaults to "Internal Server Error"
- Exceptions are not logged.