Description

A pluggable gRPC Reflection Server for the excellent NestJS framework.

Adding this module to your existing NestJS-based gRPC microservice will allow clients such as postman to dynamically load your API definitions from your running application rather than needing to load each proto file manually.

Getting Started

To get started, first install the package:

$ npm install nestjs-grpc-reflection

Then simply register the GrpcReflectionModule from the root module of your application - it takes in the same GrpcOptions that are used to create your microservice. The gRPC Reflection Server module runs within your application's existing gRPC server just as any other controller in your microservice, so loading the module will add the appropriate routes to your application.

import { GrpcReflectionModule } from 'nestjs-grpc-reflection';
...
@Module({
  imports: [GrpcReflectionModule.register(grpcClientOptions)],
  ...
})
export class AppModule {}

Finally, NestJS needs to know where the reflection proto files are so that it can serialize/deserialize its message traffic. For convenience, this can be automatically added to your GrpcOptions using the addReflectionToGrpcConfig function like so:

import { addReflectionToGrpcConfig } from 'nestjs-grpc-reflection';
...
export const grpcClientOptions: GrpcOptions = addReflectionToGrpcConfig({
  transport: Transport.GRPC,
  options: {
    package: 'sample',
    protoPath: join(__dirname, 'sample/proto/sample.proto'),
  },
});

Alternatively, these paths can be added manually by appending the REFLECTION_PACKAGE and REFLECTION_PROTO constants to the package and protoPath lists respectively.

:warning: If you are using @grpc/proto-loader's keepCase option you may experience some issues with the server reflection API. This module assumes that the microservice server is running with keepCase off (the NestJS default) and will attempt to convert back to the original case if it's on but this may not be perfect in all cases.

Local Development

This repository contains a simple example gRPC service as well as the gRPC reflection module library, so new features can be tested against that service.

$ npm install

Generating Types

This repo uses ts-proto for type generation. If any of the the reflection API proto files are changed, we'll need to regenerate the types to reflect that change. This relies on the protoc compiler, so if that's not installed already you'll need to do so first - instructions can be found on their site here.

$ npm run generate # regenerate reflection types, requires 'protoc' to be installed

Running the app

# development
$ npm run start

# watch mode
$ npm run start:dev

# production mode
$ npm run start:prod

Test

# unit tests
$ npm run test

# e2e tests
$ npm run test:e2e

# test coverage
$ npm run test:cov