nestjs-grpc-reflection

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.

Supported gRPC Clients

While this library should work with any gRPC client, in practice there could be some implementation issues that cause issues with some clients. Below is the list of gRPC clients that this library has been tested against:

Client	Status	Notes
Postman	✅
grpcurl	✅
grpcui	✅
kreya	❌

If you're using a client not on this list, please add it here! If you've hit a problem with one, please open a bug!

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.

This module can either be loaded syncronously with the register method:

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

or asyncronously with the registerAsync method if you need dynamic gRPC options. This is common if you are using the @nestjs/config module to configure your gRPC server, for example.

import { GrpcReflectionModule } from 'nestjs-grpc-reflection';
...
@Module({
  imports: [GrpcReflectionModule.registerAsync({
    useFactory: async (configService: ConfigService) => {
      const grpcClientOptions: GrpcClientOptions = new GrpcClientOptions(
        configService,
      );
      return grpcClientOptions.getGRPCConfig;
    },
    inject: [ConfigService],
  }),
  ],
  ...
})


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_PACKAGES and REFLECTION_PROTOS constants to the package and protoPath lists respectively.

⚠️ 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.

Examples

There is an example of both a syncronous and asynchronously configured application in the src/sample directory, so see those for a running example

Local Development

This repository contains two simple example gRPC services 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 sample app

# development
$ npm run start register
$ npm run start registerAsync

# watch mode
$ npm run start:dev register
$ npm run start:dev registerAsync

# production mode
$ npm run start:prod register
$ npm run start:prod registerAsync

Test

# unit tests
$ npm run test

# test coverage
$ npm run test:cov

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Justin Timmons 💻 📖 🤔 🚧 📆	Cristian 💻 📖	juju 💻	Alexandr Ishchuk 🐛
Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!