@rsdk/grpc.server 4.0.0-next.0 → 4.0.0-next.10

package/src/controllers/reflection/v1.controller.ts

@@ -0,0 +1,25 @@
+import type {
+  ServerReflectionGrpcController,
+  ServerReflectionRequest,
+  ServerReflectionResponse,
+} from '@rsdk/builtin-contract/dist/grpc.reflection.v1';
+import { ServerReflectionGrpcMethods } from '@rsdk/builtin-contract/dist/grpc.reflection.v1';
+import type { Observable } from 'rxjs';
+
+import { BaseV1GrpcReflectionController } from './v1.base.controller';
+
+/** Implements the 'v1' (final) version of the gRPC Reflection API spec
+ *
+ * @see {@link https://github.com/grpc/grpc/blob/master/doc/server-reflection.md}
+ */
+@ServerReflectionGrpcMethods()
+export class ReflectionV1Controller
+  extends BaseV1GrpcReflectionController
+  implements ServerReflectionGrpcController
+{
+  override serverReflectionInfo(
+    request: Observable<ServerReflectionRequest>,
+  ): Observable<ServerReflectionResponse> {
+    return super.serverReflectionInfo(request);
+  }
+}

package/src/controllers/reflection/v1alpha.controller.ts

@@ -0,0 +1,25 @@
+import { ServerReflectionGrpcMethods } from '@rsdk/builtin-contract/dist/grpc.reflection.v1';
+import type {
+  ServerReflectionGrpcController,
+  ServerReflectionRequest,
+  ServerReflectionResponse,
+} from '@rsdk/builtin-contract/dist/grpc.reflection.v1alpha';
+import type { Observable } from 'rxjs';
+
+import { BaseV1GrpcReflectionController } from './v1.base.controller';
+
+/** Implements the 'v1alpha' version of the gRPC Reflection API spec
+ *
+ * @see {@link https://github.com/grpc/grpc/blob/master/doc/server-reflection.md}
+ */
+@ServerReflectionGrpcMethods()
+export class ReflectionV1alphaController
+  extends BaseV1GrpcReflectionController
+  implements ServerReflectionGrpcController
+{
+  override serverReflectionInfo(
+    request: Observable<ServerReflectionRequest>,
+  ): Observable<ServerReflectionResponse> {
+    return super.serverReflectionInfo(request);
+  }
+}

package/src/grpc-logger.interceptor.ts

@@ -0,0 +1,72 @@
+import type {
+  CallHandler,
+  ExecutionContext,
+  NestInterceptor,
+} from '@nestjs/common/interfaces';
+import { InjectLogger } from '@rsdk/core';
+import { ILogger } from '@rsdk/logging';
+import type { Observable } from 'rxjs';
+import { catchError, tap, throwError } from 'rxjs';
+
+import { GRPCConfig } from './grpc.config';
+
+export class GrpcLoggerInterceptor implements NestInterceptor {
+  constructor(
+    @InjectLogger(GrpcLoggerInterceptor) private logger: ILogger,
+    private grpcConfig: GRPCConfig,
+  ) {}
+
+  intercept(
+    context: ExecutionContext,
+    next: CallHandler<any>,
+  ): Observable<any> | Promise<Observable<any>> {
+    if (!this.grpcConfig.requestLogging) {
+      return next.handle();
+    }
+    const isRpc = context.getType() === 'rpc';
+    if (!isRpc) {
+      return next.handle();
+    }
+
+    const rpc = context.switchToRpc();
+
+    const startDate = Date.now();
+    const rpcContext = rpc.getContext();
+    const serializedCtx = rpcContext?.toJSON?.() ?? rpcContext;
+    const requestForLog = {
+      data: rpc.getData(),
+      ctx: serializedCtx,
+    };
+
+    this.logger.trace('received rpc request', {
+      request: requestForLog,
+      timestamp: startDate,
+    });
+
+    return next.handle().pipe(
+      catchError((error) => {
+        const endDate = Date.now();
+
+        this.logger.trace('handled rpc request with error', {
+          request: requestForLog,
+          startDate,
+          endDate,
+          duration: endDate - startDate,
+          error,
+        });
+        return throwError(() => error);
+      }),
+      tap((response) => {
+        const endDate = Date.now();
+
+        this.logger.trace('handled rpc request', {
+          request: requestForLog,
+          startDate,
+          endDate,
+          duration: endDate - startDate,
+          response,
+        });
+      }),
+    );
+  }
+}

package/src/grpc.config.ts

@@ -4,6 +4,7 @@ import {
 } from '@grpc/grpc-js/build/src/constants';
 import { text } from '@rsdk/common';
 import {
+  BoolParser,
   Config,
   ConfigSection,
   ConfigTag,
@@ -36,4 +37,16 @@ export class GRPCConfig extends Config {
     description: 'Max gRPC message size (send)',
   })
   readonly maxSend!: number;
+
+  @Property('GRPC_REFLECTION', new BoolParser(), {
+    defaultValue: false,
+    description: 'Enable reflection',
+  })
+  readonly reflection!: boolean;
+
+  @Property('GRPC_REQUEST_LOGGING', new BoolParser(), {
+    defaultValue: false,
+    description: 'Enable trace logging all requests',
+  })
+  readonly requestLogging!: boolean;
 }

package/src/grpc.transport.ts

@@ -1,7 +1,10 @@
 import type { Controller } from '@nestjs/common/interfaces';
+import { APP_INTERCEPTOR } from '@nestjs/core';
 import type { MicroserviceOptions } from '@nestjs/microservices';
 import HealthGrpcPackage from '@rsdk/builtin-contract/dist/grpc.health.v1';
 import MetricsGrpcPackage from '@rsdk/builtin-contract/dist/grpc.metrics.v1';
+import ReflectionGrpcPackageV1 from '@rsdk/builtin-contract/dist/grpc.reflection.v1';
+import ReflectionGrpcPackageV1alpha from '@rsdk/builtin-contract/dist/grpc.reflection.v1alpha';
 import type { Constructor } from '@rsdk/common';
 import type {
   ConfigContext,
@@ -9,6 +12,7 @@ import type {
   IErrorsSender,
   IErrorsTransformer,
   IMicroserviceTransport,
+  NestModuleDefinitions,
 } from '@rsdk/core';
 import { SequenceException } from '@rsdk/core';
 import type { Package } from '@rsdk/grpc.loader';
@@ -17,10 +21,20 @@ import { LoggerFactory } from '@rsdk/logging';
 
 import { HealthController, MetricsController } from './controllers';
 import { GRPCConfig } from './grpc.config';
+import { isPackageNotIncluded } from './grpc.utils';
 import { GrpcErrorsFormatter } from './grpc-errors.formatter';
 import { GrpcErrorsSender } from './grpc-errors.sender';
+import { GrpcLoggerInterceptor } from './grpc-logger.interceptor';
+import { ReflectionModule } from './reflection.module';
 
 export class GrpcTransport implements IMicroserviceTransport {
+  private readonly systemPackages: Package[] = [
+    HealthGrpcPackage,
+    MetricsGrpcPackage,
+    ReflectionGrpcPackageV1,
+    ReflectionGrpcPackageV1alpha,
+  ];
+
   private readonly logger = LoggerFactory.create(GrpcTransport);
   private readonly packages: Package[];
 
@@ -58,6 +72,21 @@ export class GrpcTransport implements IMicroserviceTransport {
     return HealthController;
   }
 
+  modules(): NestModuleDefinitions {
+    return [
+      ReflectionModule.forRoot(this.packages),
+      {
+        module: GrpcTransport,
+        providers: [
+          {
+            provide: APP_INTERCEPTOR,
+            useClass: GrpcLoggerInterceptor,
+          },
+        ],
+      },
+    ];
+  }
+
   /**
    * Unfortunally we can't access GRPCConfig in constructor because
    * PlatformConfigModule is not initilalized yet
@@ -72,17 +101,7 @@ export class GrpcTransport implements IMicroserviceTransport {
   }
 
   createMicroserviceOptions(): MicroserviceOptions {
-    this.checkIsInitialized();
-
-    const packages = [...this.packages];
-
-    if (!packages.some((x) => x.name === HealthGrpcPackage.name)) {
-      packages.push(HealthGrpcPackage);
-    }
-
-    if (!packages.some((x) => x.name === MetricsGrpcPackage.name)) {
-      packages.push(MetricsGrpcPackage);
-    }
+    const packages = this.getUniquePackages();
 
     for (const pkg of packages) {
       for (const service of Object.keys(pkg.definitions['grpc-js'])) {
@@ -90,11 +109,15 @@ export class GrpcTransport implements IMicroserviceTransport {
       }
     }
 
+    this.checkIsInitialized();
+    this.assertIsDefined(this.address);
+    this.assertIsDefined(this.maxRecv);
+    this.assertIsDefined(this.maxSend);
+
     return createGrpcOptions(packages, {
-      // FIXME добавить проверку
-      address: this.address!,
-      maxRecv: this.maxRecv!,
-      maxSend: this.maxSend!,
+      address: this.address,
+      maxRecv: this.maxRecv,
+      maxSend: this.maxSend,
     });
   }
 
@@ -109,4 +132,30 @@ export class GrpcTransport implements IMicroserviceTransport {
       throw new SequenceException('You should call init() method first!');
     }
   }
+
+  /**
+   * Checks the value must be defined and not null
+   * @param value any value
+   */
+  private assertIsDefined<T>(value: T): asserts value is NonNullable<T> {
+    if (value === undefined || value === null) {
+      throw new Error(`${value} is not defined`);
+    }
+  }
+
+  /**
+   * Merge user packages with system packages
+   * @returns array of unique packages
+   */
+  private getUniquePackages(): Package[] {
+    const packages = [...this.packages];
+
+    for (const pkg of this.systemPackages) {
+      if (isPackageNotIncluded(packages, pkg)) {
+        packages.push(pkg);
+      }
+    }
+
+    return packages;
+  }
 }

package/src/grpc.utils.ts

@@ -0,0 +1,20 @@
+/**
+ * Match packages name
+ * @param pkg
+ * @returns true if names is equal
+ */
+const isEqualPackageName =
+  <T extends { name: string }>(pkg: T) =>
+  (x: T): boolean =>
+    x.name === pkg.name;
+
+/**
+ * Checks whether a pkg is in the array
+ * @param packages array of packages
+ * @param pkg package you are looking for
+ * @returns true if pkg exists in packages
+ */
+export const isPackageNotIncluded = <T extends { name: string }>(
+  packages: T[],
+  pkg: T,
+): boolean => !packages.some(isEqualPackageName(pkg));

package/src/reflection.module.ts

@@ -0,0 +1,26 @@
+import type { DynamicModule } from '@nestjs/common';
+import { Module } from '@nestjs/common';
+import type { Package } from '@rsdk/grpc.loader';
+
+import {
+  ReflectionV1alphaController,
+  ReflectionV1Controller,
+} from './controllers';
+import { ReflectionService } from './reflection.service';
+
+@Module({})
+export class ReflectionModule {
+  static forRoot(packages: Package[]): DynamicModule {
+    return {
+      module: ReflectionModule,
+      controllers: [ReflectionV1alphaController, ReflectionV1Controller],
+      providers: [
+        ReflectionService,
+        {
+          provide: 'GRPC_PACKAGES',
+          useValue: packages,
+        },
+      ],
+    };
+  }
+}

package/src/reflection.service.spec.ts

@@ -0,0 +1,86 @@
+import { FileDescriptorProto } from '@bufbuild/protobuf';
+import type { PlatformTestingModule } from '@rsdk/testing';
+import { PlatformTest } from '@rsdk/testing';
+
+import { ReflectionService } from './reflection.service';
+
+describe('ReflectionService', () => {
+  let testingModule: PlatformTestingModule;
+  let reflectionService: ReflectionService;
+
+  beforeAll(async () => {
+    const platformTesting = await PlatformTest.create({});
+
+    testingModule = await platformTesting
+      .createTestingModule({
+        providers: [
+          ReflectionService,
+          {
+            provide: 'GRPC_PACKAGES',
+            useValue: [],
+          },
+        ],
+      })
+      .compile();
+
+    reflectionService = testingModule.get(ReflectionService);
+
+    reflectionService.onModuleInit();
+  });
+
+  afterAll(async () => {
+    await testingModule.close();
+  });
+
+  describe('listServices()', () => {
+    it('lists all services', () => {
+      const services = reflectionService.listServices();
+
+      expect(services).toHaveLength(4);
+      expect(services).toContain('grpc.health.v1.Health');
+      expect(services).toContain('grpc.metrics.v1.Metrics');
+      expect(services).toContain('grpc.reflection.v1.ServerReflection');
+      expect(services).toContain('grpc.reflection.v1alpha.ServerReflection');
+    });
+  });
+
+  describe('fileByFilename()', () => {
+    it('finds files with no transitive dependencies', () => {
+      const descriptor = FileDescriptorProto.fromBinary(
+        reflectionService.fileByName('grpc/health/v1/health.proto'),
+      );
+
+      expect(descriptor.name).toEqual('grpc/health/v1/health.proto');
+    });
+
+    it('errors with no file found', () => {
+      expect(() => reflectionService.fileByName('nonexistent.proto')).toThrow(
+        'file: nonexistent.proto not found',
+      );
+    });
+  });
+
+  describe('fileContainingSymbol()', () => {
+    it('finds symbols and returns transitive file dependencies', () => {
+      const descriptor = FileDescriptorProto.fromBinary(
+        reflectionService.fileBySymbol('grpc.health.v1.HealthCheckRequest'),
+      );
+
+      expect(descriptor.name).toEqual('grpc/health/v1/health.proto');
+    });
+
+    it('resolves references to method types', () => {
+      const descriptor = FileDescriptorProto.fromBinary(
+        reflectionService.fileBySymbol('grpc.health.v1.Health.Check'),
+      );
+
+      expect(descriptor.name).toEqual('grpc/health/v1/health.proto');
+    });
+
+    it('errors with no symbol found', () => {
+      expect(() =>
+        reflectionService.fileBySymbol('non.existant.symbol'),
+      ).toThrow('symbol: non.existant.symbol not found');
+    });
+  });
+});

package/src/reflection.service.ts

@@ -0,0 +1,210 @@
+import type {
+  EnumDescriptorProto,
+  MethodDescriptorProto,
+} from '@bufbuild/protobuf';
+import {
+  DescriptorProto,
+  FileDescriptorProto,
+  FileDescriptorSet,
+  ServiceDescriptorProto,
+} from '@bufbuild/protobuf';
+import type { OnModuleInit } from '@nestjs/common';
+import { Inject, Injectable } from '@nestjs/common';
+import HealthGrpcPackage from '@rsdk/builtin-contract/dist/grpc.health.v1';
+import MetricsGrpcPackage from '@rsdk/builtin-contract/dist/grpc.metrics.v1';
+import ReflectionGrpcPackageV1 from '@rsdk/builtin-contract/dist/grpc.reflection.v1';
+import ReflectionGrpcPackageV1alpha from '@rsdk/builtin-contract/dist/grpc.reflection.v1alpha';
+import type { Package } from '@rsdk/grpc.loader';
+import { LoggerFactory } from '@rsdk/logging';
+
+@Injectable()
+export class ReflectionService implements OnModuleInit {
+  private readonly services: Set<string> = new Set();
+  private readonly files: FileDescriptorProto[] = [];
+  private readonly logger = LoggerFactory.create(ReflectionService);
+
+  constructor(@Inject('GRPC_PACKAGES') private readonly packages: Package[]) {}
+
+  onModuleInit(): void {
+    const allPackages = [
+      ...this.packages,
+      HealthGrpcPackage,
+      MetricsGrpcPackage,
+      ReflectionGrpcPackageV1,
+      ReflectionGrpcPackageV1alpha,
+    ];
+
+    const allPackagesNames = new Set(allPackages.map((pkg) => pkg.name));
+
+    for (const pkg of allPackages) {
+      if (pkg.descriptor) {
+        for (const service of Object.keys(pkg.definitions['grpc-js'])) {
+          this.logger.info(
+            `GRPC descriptor loaded for service: ${pkg.name}.${service}`,
+          );
+        }
+
+        for (const file of FileDescriptorSet.fromBinary(pkg.descriptor).file) {
+          this.files.push(file);
+
+          if (allPackagesNames.has(`${file.package}`)) {
+            for (const service of file.service) {
+              this.services.add(`${file.package}.${service.name}`);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * List the full names of registered gRPC services
+   *
+   * note: the spec is unclear as to what the 'listServices' param can be; most
+   * clients seem to only pass '*' but unsure if this should behave like a
+   * filter. Until we know how this should behave with different inputs this
+   * just always returns *all* services.
+   *
+   * @returns full-qualified service names (eg. 'sample.SampleService')
+   */
+  listServices(): string[] {
+    return [...this.services];
+  }
+
+  /**
+   * Find the proto file(s) that declares the given fully-qualified symbol name
+   *
+   * @param symbol fully-qualified name of the symbol to lookup
+   * (e.g. package.service[.method] or package.type)
+   *
+   * @returns descriptors of the file which contains this symbol and its imports
+   */
+  fileBySymbol(symbol: string): Buffer {
+    const file = this.files.find((file) => this.findSymbol(symbol, file));
+
+    if (file) {
+      return Buffer.from(file.toBinary());
+    }
+
+    throw new Error(`symbol: ${symbol} not found`);
+  }
+
+  /**
+   * Find a proto file by the file name
+   * @returns descriptors of the file which contains this symbol and its imports
+   */
+  fileByName(filename: string): Buffer {
+    const file = this.files.find((file) => file.name === filename);
+
+    if (file) {
+      return Buffer.from(file.toBinary());
+    }
+
+    throw new Error(`file: ${filename} not found`);
+  }
+
+  /**
+   * Find a proto file containing an extension to a message type
+   * @returns descriptors of the file which contains this symbol and its imports
+   */
+  fileContainingExtension(
+    containingType: string,
+    extensionNumber: number,
+  ): Buffer {
+    const extension = this.files.find((file) => {
+      const descriptor = this.findSymbol(containingType, file);
+
+      return (
+        descriptor instanceof DescriptorProto &&
+        descriptor.extension.some(
+          (extension) => extensionNumber === extension.number,
+        )
+      );
+    });
+
+    if (extension) {
+      return Buffer.from(extension.toBinary());
+    }
+
+    throw new Error(
+      `containingType: ${containingType}, extensionNumber: ${extensionNumber} not found`,
+    );
+  }
+
+  allExtensionNumbersOfType(symbol: string): number[] {
+    return [
+      ...new Set(
+        this.files.flatMap((file) =>
+          file.extension.flatMap((_fqn, _file, ext) =>
+            ext
+              .filter((e) => e.extendee === symbol)
+              .flatMap((e) => Number(e.number)),
+          ),
+        ),
+      ),
+    ];
+  }
+
+  private findSymbol(
+    symbol: string,
+    descriptor:
+      | FileDescriptorProto
+      | DescriptorProto
+      | EnumDescriptorProto
+      | ServiceDescriptorProto
+      | MethodDescriptorProto,
+    prefix = '',
+  ):
+    | DescriptorProto
+    | EnumDescriptorProto
+    | ServiceDescriptorProto
+    | MethodDescriptorProto
+    | undefined {
+    if (descriptor instanceof FileDescriptorProto) {
+      const packageName = descriptor.package;
+
+      const packagePrefix = packageName ? `${packageName}.` : '';
+
+      return (
+        descriptor.messageType.find((type) =>
+          this.findSymbol(symbol, type, packagePrefix),
+        ) ??
+        descriptor.enumType.find((type) =>
+          this.findSymbol(symbol, type, packagePrefix),
+        ) ??
+        descriptor.service.find((type) =>
+          this.findSymbol(symbol, type, packagePrefix),
+        )
+      );
+    }
+
+    const fullName = prefix + descriptor.name;
+
+    if (symbol === fullName) {
+      return descriptor;
+    }
+
+    if (descriptor instanceof DescriptorProto) {
+      const messagePrefix = `${fullName}.`;
+
+      return (
+        descriptor.nestedType.find((type) =>
+          this.findSymbol(symbol, type, messagePrefix),
+        ) ??
+        descriptor.enumType.find((type) =>
+          this.findSymbol(symbol, type, messagePrefix),
+        )
+      );
+    }
+
+    if (descriptor instanceof ServiceDescriptorProto) {
+      const servicePrefix = `${fullName}.`;
+
+      return descriptor.method.find((method) =>
+        this.findSymbol(symbol, method, servicePrefix),
+      );
+    }
+
+    return undefined;
+  }
+}