@rsdk/core 5.7.0-next.2 → 6.0.0-next.0

package/src/config/types.ts

@@ -1,3 +1,5 @@
+import type { PropertyParser } from '@rsdk/common';
+
 export type SourceType = 'static' | 'reloadable';
 
 export interface Changes {
@@ -54,29 +56,6 @@ export interface ParserMetadata {
   description: string;
 }
 
-/**
- * Implement this interface to create more parsers.
- * For example: email, BigInt, guid etc.
- *
- * NOTE: In other modules it is more common to define metadata
- * via decorators. But this case is a bit different.
- *
- * 1. Parser implementations can have constructors with parameters
- * which will affect it's behaviour. It's will be nice to have it
- * in metadata, and decorators won't provide this.
- *
- * 2. Metadata will be extracted via type() and description() methods
- * mostly during decorator factories (such as @Property()) code is
- * executed. Thus output **can** be used in autodoc
- */
-export interface PropertyParser<T = any> {
-  type(): string;
-
-  description(): string;
-
-  parse(value: unknown): T;
-}
-
 export type RawValues = Map<string, unknown>;
 
 export enum AppNameStrategyType {

package/src/exceptions.handling/default.formatter.ts

@@ -0,0 +1,11 @@
+import type { IErrorsFormatter } from './types';
+
+export class DefaultFormatter implements IErrorsFormatter {
+  readonly protocol = 'default';
+
+  format(ex: unknown, verbose: boolean): unknown {
+    return verbose ? ex : { message: 'NO FORMATTER' };
+  }
+}
+
+export const DEFAULT_FORMATTER = new DefaultFormatter();

package/src/exceptions.handling/default.sender.ts

@@ -0,0 +1,15 @@
+import type { ArgumentsHost } from '@nestjs/common';
+import type { Observable } from 'rxjs';
+import { throwError } from 'rxjs';
+
+import type { IErrorsSender } from './types';
+
+export class DefaultSender implements IErrorsSender {
+  readonly protocol = 'default';
+
+  send(_: ArgumentsHost, ex: unknown): Observable<any> {
+    return throwError(() => ex);
+  }
+}
+
+export const DEFAULT_SENDER = new DefaultSender();

package/src/exceptions.handling/global-exceptions.config.ts

@@ -1,6 +1,6 @@
-import { text } from '@rsdk/common';
+import { BoolParser, text } from '@rsdk/common';
 
-import { BoolParser, Config, ConfigSection, Property } from '../config';
+import { Config, ConfigSection, Property } from '../config';
 import { ConfigTag } from '../config/config.const';
 
 @ConfigSection({

package/src/exceptions.handling/global-exceptions.filter.ts

@@ -1,109 +1,77 @@
 import type { ArgumentsHost, ExceptionFilter } from '@nestjs/common';
 import { Catch, Inject } from '@nestjs/common';
-import { normalizer, sortErrorKeys } from '@rsdk/common';
-import { ILogger } from '@rsdk/logging';
+import { normalizer, sortErrorKeys, text } from '@rsdk/common';
 import type { Observable } from 'rxjs';
-import { throwError } from 'rxjs';
 
-import { InternalException, PipelineException } from '../exceptions';
-import { InjectLogger } from '../logging';
+import { PipelineException } from '../exceptions';
+import { ILogger, InjectLogger } from '../logging';
 import { ProtocolDetector } from '../transport/protocol.detector';
 
-import { FORMATTERS, SENDERS, TRANSFORMERS } from './constants';
+import { FORMATTERS, SENDERS } from './constants';
+import { DEFAULT_FORMATTER } from './default.formatter';
+import { DEFAULT_SENDER } from './default.sender';
 import { GlobalExceptionsConfig } from './global-exceptions.config';
-import type {
-  IErrorsFormatter,
-  IErrorsSender,
-  IErrorsTransformer,
-} from './types';
+import type { IErrorsFormatter, IErrorsSender } from './types';
 
 @Catch()
 export class GlobalExceptionsFilter implements ExceptionFilter {
   constructor(
-    @Inject(FORMATTERS) private readonly formatters: IErrorsFormatter[],
-    @Inject(TRANSFORMERS) private readonly transformers: IErrorsTransformer[],
-    @Inject(SENDERS) private readonly senders: IErrorsSender[],
-    @InjectLogger(GlobalExceptionsFilter)
-    private readonly logger: ILogger,
-    private readonly config: GlobalExceptionsConfig,
+    /* eslint-disable prettier/prettier */
+    @Inject(SENDERS) private readonly senders: Map<string, IErrorsSender>,
+    @Inject(FORMATTERS) private readonly formatters: Map<string, IErrorsFormatter>,
+    @InjectLogger(GlobalExceptionsFilter) private readonly logger: ILogger,
     private readonly detector: ProtocolDetector,
+    private readonly config: GlobalExceptionsConfig,
+    /* eslint-enable prettier/prettier */
   ) {}
 
-  catch(ex: any, host: ArgumentsHost): Observable<any> {
-    const transformed =
-      ex instanceof PipelineException ? ex : this.transform(ex);
-
-    // Error is transformed to standard PipelineException
-    this.logger.error(transformed);
-
-    const formatted = this.format(host, transformed);
-
-    return this.send(host, formatted);
-  }
-
-  private transform(ex: any): PipelineException {
-    const transformer = this.transformers.find((x) => x.match(ex));
-    if (transformer) {
-      return transformer.transform(ex);
-    }
+  catch(ex: PipelineException, host: ArgumentsHost): Observable<any> {
+    const protocol = this.detector.getProtocol(host);
 
-    const err = new InternalException(ex.message ?? 'UNKNOWN ERROR', ex);
+    const sender = this.getSender(host, protocol);
+    const formatter = this.getFormatter(host, protocol);
 
-    err.stack = ex.stack;
+    const formatted = formatter.format(ex, this.config.verbose);
+    const normalized = normalizer()(formatted, {
+      filterKeys: ['stack'],
+      sortKeys: sortErrorKeys,
+    });
 
-    return err;
+    return sender.send(host, normalized);
   }
 
-  private format(host: ArgumentsHost, ex: unknown): unknown {
-    const protocol = this.detector.getProtocol(host);
-    const formatter = this.getFormatter(host, protocol);
+  private getSender(host: ArgumentsHost, protocol: string): IErrorsSender {
+    const sender =
+      this.senders.get(protocol) ?? this.senders.get(host.getType());
 
-    if (formatter) {
-      this.logger.trace(`Found formatter: ${formatter.constructor.name}`);
-
-      return formatter.format(ex, this.config.verbose);
+    if (sender) {
+      this.logger.trace(`Found sender: ${sender.constructor.name}`);
+      return sender;
     }
 
-    this.logger.trace('No formatter for error!');
-
-    if (this.config.verbose) {
-      return normalizer()(ex, {
-        // This means stacktrace will never be sent to user
-        filterKeys: ['stack'],
-        sortKeys: sortErrorKeys,
-      }) as object;
-    }
+    this.logger.warn(text`
+      No sender for protocol = ${protocol}
+      (hostType = ${host.getType()})`);
 
-    return { message: 'NO FORMATTER' };
+    return DEFAULT_SENDER;
   }
 
   private getFormatter(
     host: ArgumentsHost,
-    protocol: string | undefined,
-  ): IErrorsFormatter | undefined {
-    return (
-      this.formatters.find((x) => x.protocol === protocol) ??
-      this.formatters.find((x) => x.protocol === host.getType())
-    );
-  }
+    protocol: string,
+  ): IErrorsFormatter {
+    const formatter =
+      this.formatters.get(protocol) ?? this.formatters.get(host.getType());
 
-  private send(host: ArgumentsHost, ex: any): Observable<unknown> {
-    const protocol = this.detector.getProtocol(host);
-    const sender = this.getSender(host, protocol);
+    if (formatter) {
+      this.logger.trace(`Found formatter: ${formatter.constructor.name}`);
+      return formatter;
+    }
 
-    return sender?.send(host, ex) ?? throwError(() => ex);
-  }
+    this.logger.warn(text`
+      No formatter for protocol = ${protocol}
+      (hostType = ${host.getType()})`);
 
-  private getSender(
-    host: ArgumentsHost,
-    protocol: string | undefined,
-  ): IErrorsSender | undefined {
-    const s: IErrorsSender | undefined = this.senders.find(
-      (x) => x.protocol === protocol,
-    );
-    if (!s) {
-      return this.senders.find((x) => x.protocol === host.getType());
-    }
-    return s;
+    return DEFAULT_FORMATTER;
   }
 }

package/src/exceptions.handling/global-exceptions.interceptor.ts

@@ -0,0 +1,57 @@
+import type {
+  CallHandler,
+  ExecutionContext,
+  NestInterceptor,
+} from '@nestjs/common';
+import { Inject, Injectable } from '@nestjs/common';
+import type { Observable } from 'rxjs';
+import { catchError, throwError } from 'rxjs';
+
+import { InternalException, PipelineException } from '../exceptions';
+
+import { TRANSFORMERS } from './constants';
+import type { IErrorsTransformer } from './types';
+
+/**
+ * Обработка ошибки состоит из трёх этапов:
+ * 1. Трансформация ошибки в PipelineException
+ * 2. Логирование ошибки
+ * 3. Отправка ошибки клиенту, в зависимости от транспорта.
+ *
+ * Этот интерцептор отвечает за 1-й этап. Важно, что в пайплайне обработки
+ * он должен стоять перед LoggingInterceptor, который обеспечивает логирование
+ */
+@Injectable()
+export class GlobalExceptionsInterceptor implements NestInterceptor {
+  constructor(
+    @Inject(TRANSFORMERS) private readonly transformers: IErrorsTransformer[],
+  ) {}
+
+  intercept(
+    _: ExecutionContext,
+    next: CallHandler<any>,
+  ): Observable<any> | Promise<Observable<any>> {
+    return next.handle().pipe(
+      catchError((error) => {
+        // Error is transformed to standard PipelineException
+        const transformed =
+          error instanceof PipelineException ? error : this.transform(error);
+
+        return throwError(() => transformed);
+      }),
+    );
+  }
+
+  private transform(ex: any): PipelineException {
+    const transformer = this.transformers.find((x) => x.match(ex));
+    if (transformer) {
+      return transformer.transform(ex);
+    }
+
+    const err = new InternalException(ex.message ?? 'UNKNOWN ERROR', ex);
+
+    err.stack = ex.stack;
+
+    return err;
+  }
+}

package/src/exceptions.handling/global-exceptions.module.ts

@@ -1,60 +1,73 @@
 import type { DynamicModule } from '@nestjs/common';
 import { Module } from '@nestjs/common';
-import { APP_FILTER } from '@nestjs/core';
+import { APP_FILTER, APP_INTERCEPTOR } from '@nestjs/core';
+
+import { PlatformExtendedOptions } from '../types';
 
 import { FORMATTERS, SENDERS, TRANSFORMERS } from './constants';
 import { GlobalExceptionsFilter } from './global-exceptions.filter';
-import type {
-  IErrorsFormatter,
-  IErrorsSender,
-  IErrorsTransformer,
-} from './types';
+import { GlobalExceptionsInterceptor } from './global-exceptions.interceptor';
+import { IErrorsFormatter, IErrorsSender } from './types';
 
-export interface GlobalExceptionModuleOptions {
-  /**
-   * Formatters are used to transform exceptions to transport specific
-   * final implementations. Usually formatter expects transport agnostic
-   * subclasses of BaseException.
-   */
-  formatters: IErrorsFormatter[];
+@Module({})
+export class GlobalExceptionsModule {
+  static forRoot(options: PlatformExtendedOptions): DynamicModule {
+    const entities = [
+      ...(options.transports || []),
+      ...(options.plugins || []),
+    ];
 
-  /**
-   * Senders are used to actually respond to client (algorithm
-   * is transport specific)
-   */
-  senders: IErrorsSender[];
+    /**
+     * Formatters are used to transform exceptions to transport specific
+     * final implementations. Usually formatter expects transport agnostic
+     * subclasses of BaseException.
+     */
+    const formatters: Map<string, IErrorsFormatter> = entities
+      .flatMap((x) => x.errorFormatter?.() || [])
+      .reduce((acc, x) => acc.set(x.protocol, x), new Map());
 
-  /**
-   * Sometimes application throws a lot of unconventional
-   * (not inheriting BaseExceptions). Usually they are throw by
-   * libraries: typeorm, axios, etc. Transformers are used to
-   * catch them and convert to any subtype of BaseException which
-   * will be processed further by transport specific formatters.
-   */
-  transformers?: IErrorsTransformer[];
-}
+    /**
+     * Senders are used to actually respond to client (algorithm
+     * is transport specific)
+     */
+    const senders: Map<string, IErrorsSender> = entities
+      .flatMap((x) => x.errorSender?.() || [])
+      .reduce((acc, x) => acc.set(x.protocol, x), new Map());
+
+    /**
+     * Sometimes application throws a lot of unconventional
+     * (not inheriting BaseExceptions). Usually they are throw by
+     * libraries: typeorm, axios, etc. Transformers are used to
+     * catch them and convert to any subtype of BaseException which
+     * will be processed further by transport specific formatters.
+     *
+     * NOTE: Unlike formatters and senders, transformers can't be grouped
+     * by protocol, because their matchers are a bit more complex.
+     */
+    const transformers = entities.flatMap((x) => x.errorTransformers?.() || []);
 
-@Module({})
-export class GlobalExceptionsModule {
-  static forRoot(options: GlobalExceptionModuleOptions): DynamicModule {
     return {
       module: GlobalExceptionsModule,
       providers: [
+        {
+          provide: APP_INTERCEPTOR,
+          useClass: GlobalExceptionsInterceptor,
+        },
         {
           provide: APP_FILTER,
           useClass: GlobalExceptionsFilter,
         },
         {
           provide: FORMATTERS,
-          useValue: options.formatters,
+          useValue: formatters,
         },
         {
           provide: SENDERS,
-          useValue: options.senders,
+          useValue: senders,
         },
         {
           provide: TRANSFORMERS,
-          useValue: options.transformers || [],
+          useValue: transformers,
         },
       ],
     };

package/src/exceptions.handling/types.ts

@@ -5,7 +5,7 @@ import type { PipelineException } from '../exceptions/base';
 
 /**
  * Errors formatter is used to map transport-agnostic
- * buisiness exception to transport-specific on (with appropriate
+ * business exception to transport-specific on (with appropriate
  * status code and other attributes)
  *
  * @implementme Implement this interface if you need to create a
@@ -73,7 +73,7 @@ export interface IErrorsTransformer {
   match(ex: any): boolean;
 
   /**
-   * Transformating algorithm
+   * Transformation algorithm
    *
    * @param ex Exception itself
    */

package/src/index.ts

@@ -37,7 +37,7 @@ export * from './exceptions';
 
 export * from './exceptions.handling';
 
-export { InjectLogger } from './logging';
+export { InjectLogger, LogFormatter, LogLevel } from './logging';
 
 export {
   AnyMetric,
@@ -58,4 +58,55 @@ export * from './app-metadata/decorators';
 
 export * from './app-metadata/app-metadata.const';
 
-export { TracingHeaders } from './tracing';
+export {
+  withPrefix,
+  generateDefault,
+  RequestIdGenStrategy,
+  TracingHeaders,
+} from './tracing';
+
+/**
+ * FIXME: Remove this after migration to @rsdk/common
+ */
+
+export {
+  // eslint-disable-next-line prettier/prettier
+  /** @deprecated Import from @rsdk/common instead */
+  ArrayParser,
+
+  /** @deprecated Import from @rsdk/common instead */
+  BoolParser,
+
+  /** @deprecated Import from @rsdk/common instead */
+  EnumParser,
+
+  /** @deprecated Import from @rsdk/common instead */
+  IntParser,
+
+  /** @deprecated Import from @rsdk/common instead */
+  JsonParser,
+
+  /** @deprecated Import from @rsdk/common instead */
+  NumberParser,
+
+  /** @deprecated Import from @rsdk/common instead */
+  PropertyParser,
+
+  /** @deprecated Import from @rsdk/common instead */
+  SizeParser,
+
+  /** @deprecated Import from @rsdk/common instead */
+  StringParser,
+
+  /** @deprecated Import from @rsdk/common instead */
+  UrlParser,
+
+  /** @deprecated Import from @rsdk/common instead */
+  TimespanParser,
+} from '@rsdk/common';
+
+export {
+  // eslint-disable-next-line @stylistic/lines-around-comment
+  /** @deprecated Import from @rsdk/common.node instead */
+  FsPathParser,
+} from '@rsdk/common.node';

package/src/logging/constants.ts

@@ -0,0 +1 @@
+export const LOG_FORMATTERS = Symbol('LOG_FORMATTERS');

package/src/logging/decorators/inject-logger.decorator.ts

@@ -2,7 +2,7 @@ import { Inject } from '@nestjs/common';
 import type { Constructor } from '@rsdk/common';
 
 import { getLoggerToken } from '../helpers';
-import { LoggingModule } from '../logging.module';
+import { LoggerInstancesModule } from '../logging-instances.module';
 
 export const InjectLogger = (
   context: string | Constructor,
@@ -11,6 +11,6 @@ export const InjectLogger = (
     const token = getLoggerToken(context);
 
     Inject(token)(target, propertyKey, parameterIndex);
-    LoggingModule.register(target, context, token);
+    LoggerInstancesModule.register(target, context, token);
   };
 };

package/src/logging/formatters/default.formatter.ts

@@ -0,0 +1,17 @@
+import type { LogFormatter } from './interfaces';
+
+export class DefaultLogFormatter implements LogFormatter {
+  readonly protocol = '__default';
+
+  getPath(): string {
+    return 'unknown';
+  }
+
+  formatRequest(): Record<string, unknown> {
+    return {};
+  }
+
+  formatResponse(): Record<string, unknown> {
+    return {};
+  }
+}

package/src/logging/formatters/index.ts

@@ -0,0 +1,2 @@
+export * from './default.formatter';
+export * from './interfaces';

package/src/logging/formatters/interfaces.ts

@@ -0,0 +1,34 @@
+import type { ExecutionContext } from '@nestjs/common';
+
+export interface LogFormatter {
+  readonly protocol: string;
+
+  /**
+   * Получает путь запроса - строку, по которой будет проще всего идентифицировать запрос
+   * Например для GRPC это будет путь запроса, для HTTP это будет url, для Kafka - топик
+   */
+  getPath(context: ExecutionContext): string;
+
+  /**
+   * Форматирует запрос
+   */
+  formatRequest(
+    context: ExecutionContext,
+    includeBody: boolean,
+  ): Record<string, unknown>;
+
+  /**
+   * Форматирует ответ
+   */
+  formatResponse(
+    context: ExecutionContext,
+    body: unknown | undefined,
+  ): Record<string, unknown>;
+
+  /**
+   * Определяет, нужно ли логировать запрос. Строго говоря,
+   * это костыль исключительно под graphql, чтобы не логировать
+   * отдельно вызов каждого резолвера.
+   */
+  shouldLog?(context: ExecutionContext): boolean;
+}

package/src/logging/index.ts

@@ -1,7 +1,8 @@
 export * from '@rsdk/logging';
-export * from './logging.module';
 export * from './adapters';
 export * from './decorators';
+export * from './formatters';
 export { LOGGING_RSDK_METADATA_SCOPE } from './metadata/constants';
 export { LoggingRsdkMetadata } from './types';
-export { LoggerInitializingModule } from './logger-initializing.module';
+export { LoggerInstancesModule } from './logging-instances.module';
+export { LoggingCoreModule } from './logging-core.module';

package/src/logging/logging-core.module.ts

@@ -0,0 +1,102 @@
+import { DynamicModule, Module } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { LoggerFactory } from '@rsdk/logging';
+import type { TransportMultiOptions, TransportTargetOptions } from 'pino';
+import pino from 'pino';
+
+import { SequenceException } from '../exceptions';
+import type { PlatformExtendedOptions } from '../types';
+
+import { LOG_FORMATTERS } from './constants';
+import { LogFormatter } from './formatters';
+import { LoggingConfig } from './logging.config';
+import { LoggingInterceptor } from './logging.interceptor';
+
+@Module({})
+export class LoggingCoreModule {
+  private static logger = LoggerFactory.create(LoggingCoreModule);
+
+  constructor(config: LoggingConfig) {
+    const cfg = (): void => {
+      LoggingCoreModule.logger.info(`Setting log level: <${config.level}>`, {
+        logLevel: config.level,
+      });
+
+      LoggerFactory.reconfigure({
+        ...config,
+        stream: pino.transport(this.buildTransportOptions(config)),
+      });
+    };
+
+    config.onUpdate(cfg);
+    cfg();
+  }
+
+  static forRoot(options: PlatformExtendedOptions): DynamicModule {
+    return {
+      module: LoggingCoreModule,
+      providers: [
+        {
+          provide: APP_INTERCEPTOR,
+          useClass: LoggingInterceptor,
+        },
+        {
+          provide: LOG_FORMATTERS,
+          useValue: this.buildFormattersMap(options),
+        },
+      ],
+    };
+  }
+
+  private static buildFormattersMap(
+    options: PlatformExtendedOptions,
+  ): Map<string, LogFormatter> {
+    const transports = options.transports || [];
+    const plugins = options.plugins || [];
+
+    const array: LogFormatter[] = [
+      ...transports.map((x) => x.logFormatter()),
+      ...plugins.flatMap((x) => x.logFormatter?.() || []),
+    ];
+
+    const formatters = new Map<string, LogFormatter>();
+
+    for (const formatter of array) {
+      if (formatters.has(formatter.protocol)) {
+        throw new SequenceException(
+          `log formatter for ${formatter.protocol} already registered`,
+        );
+      }
+
+      formatters.set(formatter.protocol, formatter);
+      this.logger.debug(`registered log formatter for ${formatter.protocol}`);
+    }
+
+    return formatters;
+  }
+
+  private buildTransportOptions(config: LoggingConfig): TransportMultiOptions {
+    const targets: TransportTargetOptions[] = [
+      {
+        target: 'pino/file',
+        options: { destination: process.stdout.fd },
+        level: config.level,
+      },
+    ];
+
+    if (config.otelEnabled) {
+      targets.push({
+        target: 'pino-opentelemetry-transport',
+
+        /**
+         * NOTE: {} required to avoid runtime error "Cannot read property 'xxx' of undefined"
+         * (unsafe destructuring in pino-opentelemetry-transport)
+         */
+        options: {},
+        level: config.level,
+      });
+    }
+
+    return { targets };
+  }
+}