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

package/src/logging/{logging.module.ts → logging-instances.module.ts}

@@ -1,5 +1,3 @@
-/* eslint-disable sort-keys */
-
 import type { DynamicModule } from '@nestjs/common';
 import { Module } from '@nestjs/common';
 import type { Constructor } from '@rsdk/common';
@@ -15,7 +13,7 @@ import { getLoggerToken } from './helpers';
 import type { LoggingRsdkMetadata } from './types';
 
 @Module({})
-export class LoggingModule {
+export class LoggerInstancesModule {
   static register(
     target: object,
     context: string | Constructor,
@@ -73,7 +71,7 @@ export class LoggingModule {
   ): DynamicModule {
     return {
       global: true,
-      module: LoggingModule,
+      module: LoggerInstancesModule,
       providers: [
         {
           provide: token,

package/src/logging/logging.config.ts

@@ -1,14 +1,12 @@
-import { DEFAULT_LEVEL, LogLevel } from '@rsdk/logging';
-
 import {
   ArrayParser,
   BoolParser,
-  Config,
-  ConfigSection,
   EnumParser,
-  Property,
   StringParser,
-} from '../config';
+} from '@rsdk/common';
+import { DEFAULT_LEVEL, LogLevel } from '@rsdk/logging';
+
+import { Config, ConfigSection, Property } from '../config';
 import { ConfigTag } from '../config/config.const';
 
 @ConfigSection({
@@ -41,4 +39,22 @@ export class LoggingConfig extends Config {
     description: 'Enable OpenTelemetry exporter',
   })
   readonly otelEnabled!: boolean;
+
+  @Property('LOG_EXCLUDE_ZONES', new ArrayParser(new StringParser()), {
+    defaultValue: [],
+    description: 'Disable request/response logging for zones',
+  })
+  readonly excludeZones!: string[];
+
+  @Property('LOG_REQUEST_BODY', new BoolParser(), {
+    description: 'Enable request body (content) logging',
+    defaultValue: false,
+  })
+  readonly logRequestBody!: boolean;
+
+  @Property('LOG_RESPONSE_BODY', new BoolParser(), {
+    description: 'Enable response body (content) logging',
+    defaultValue: false,
+  })
+  readonly logResponseBody!: boolean;
 }

package/src/logging/logging.interceptor.ts

@@ -0,0 +1,138 @@
+import type {
+  CallHandler,
+  ExecutionContext,
+  NestInterceptor,
+} from '@nestjs/common';
+import { Inject, Injectable } from '@nestjs/common';
+import { ILogger } from '@rsdk/logging';
+import { Zone } from '@rsdk/zones';
+import type { Observable } from 'rxjs';
+import { catchError, tap, throwError } from 'rxjs';
+
+import { PipelineException } from '../exceptions';
+import { ProtocolDetector } from '../transport/protocol.detector';
+
+import { InjectLogger } from './decorators/inject-logger.decorator';
+import { LOG_FORMATTERS } from './constants';
+import { DefaultLogFormatter, LogFormatter } from './formatters';
+import { LoggingConfig } from './logging.config';
+
+/**
+ * LOG_LEVEL=
+ * LOG_REDACT=
+ * LOG_SYNC=
+ * LOG_OTEL_ENABLED=
+ *
+ * 1. Я хочу, чтобы сообщения в логе писались можно было писать
+ * с большим или меньшим количество подробностей. В зависимости
+ * от уровня логирования.
+ *
+ * 2. Я хочу, чтобы логирование успешных ответов и логирование ошибок
+ * было в принципе унифицировано. Сейчас этим занимаются разные интерцепторы.
+ * а мог бы один, отвечающий за логирование.
+ *
+ * 3. Логирование бинарных данных должны быть исключено.
+ * Возможность исключать логи запросов по ApiZone... кроме ошибок.
+ *
+ * 4. В логе ошибок писать больше о контексте запроса.
+ *
+ * РАЗОБРАТЬСЯ, ПОЧЕМУ kicker мы не можем сделать контроллером?
+ */
+
+@Injectable()
+export class LoggingInterceptor implements NestInterceptor {
+  private readonly defaultFormatter = new DefaultLogFormatter();
+
+  constructor(
+    @InjectLogger(LoggingInterceptor)
+    private readonly logger: ILogger,
+    @Inject(LOG_FORMATTERS)
+    private readonly formatters: Map<string, LogFormatter>,
+    private detector: ProtocolDetector,
+    private config: LoggingConfig,
+  ) {}
+
+  intercept(
+    context: ExecutionContext,
+    next: CallHandler<any>,
+  ): Observable<any> {
+    const receivedAt = Date.now();
+
+    const protocol = this.detector.getProtocol(context);
+
+    const formatter: LogFormatter = protocol
+      ? this.getFormatter(protocol)
+      : this.defaultFormatter;
+
+    const shouldLog = formatter.shouldLog?.(context) ?? true;
+    if (!shouldLog) {
+      return next.handle();
+    }
+
+    const { logRequestBody, logResponseBody, excludeZones, level } =
+      this.config;
+
+    const path = formatter.getPath(context);
+    const requestDetails = formatter.formatRequest(context, logRequestBody);
+
+    const zone = Zone.getForContext(context);
+    const isExcluded = !!zone && excludeZones.includes(zone);
+
+    if (!isExcluded) {
+      this.logger.debug(`>>> Received [${protocol.toUpperCase()}] ${path}`, {
+        details: requestDetails,
+        path,
+        zone,
+      });
+    }
+
+    return next.handle().pipe(
+      catchError((ex: PipelineException) => {
+        /**
+         * Добавляем параметры запроса, если они не были залогированы ранее.
+         */
+        const request =
+          isExcluded || !['trace', 'debug'].includes(level)
+            ? requestDetails
+            : '[ALREADY LOGGED]';
+
+        this.logger.error(`Failed [${protocol.toUpperCase()}] ${path}`, {
+          request,
+          cause: ex,
+          path,
+          zone,
+        });
+
+        return throwError(() => ex);
+      }),
+      tap((body) => {
+        if (isExcluded) {
+          return;
+        }
+
+        const responseDetails = formatter.formatResponse(
+          context,
+          logResponseBody ? body : undefined,
+        );
+
+        this.logger.debug(`<<< Handled [${protocol.toUpperCase()}] ${path}`, {
+          details: responseDetails,
+          executionTime: Date.now() - receivedAt,
+          path,
+          zone,
+        });
+      }),
+    );
+  }
+
+  private getFormatter(protocol: string): LogFormatter {
+    const formatter = this.formatters.get(protocol);
+
+    if (!formatter) {
+      this.logger.warn(`no formatter for protocol <${protocol}>...`);
+      return this.defaultFormatter;
+    }
+
+    return formatter;
+  }
+}

package/src/metrics/metrics.config.ts

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

package/src/platform.context.ts

@@ -3,7 +3,8 @@ import type { INestApplication } from '@nestjs/common/interfaces';
 import type { NestApplicationOptions } from '@nestjs/common/interfaces/nest-application-options.interface';
 import type { AbstractHttpAdapter } from '@nestjs/core';
 import type { Constructor } from '@rsdk/common';
-import { LoggerFactory } from '@rsdk/logging';
+import type { ILogger } from '@rsdk/logging';
+import { LoggerFactory, NoopLogger } from '@rsdk/logging';
 import type { RsdkMetadataProvider } from '@rsdk/metadata';
 import { groupBy, intersection } from 'lodash';
 
@@ -39,7 +40,7 @@ import {
  * Агрегат для хранения опций приложения, а также методы для конфигурации и запуска приложения
  */
 export class PlatformContext {
-  private readonly logger = LoggerFactory.create('App');
+  private readonly logger: ILogger;
   private readonly microservices = new Map<
     INestMicroservice,
     IMicroserviceTransport
@@ -68,12 +69,14 @@ export class PlatformContext {
       // force set appName
       forceAppName?: string;
     },
+    silent?: boolean,
   ) {
     this.assertTransportCompatibility(options);
     this.assertPluginCompatibility(options);
 
     this.httpTransport = options.transports?.find?.(isHttpTransport);
     this.aggregator = new ContextAggregator(this);
+    this.logger = silent ? new NoopLogger() : LoggerFactory.create('App');
   }
 
   get extendedOptions(): PlatformExtendedOptions {

package/src/platform.module.ts

@@ -8,7 +8,8 @@ import { PlatformPluginModule } from './plugin/plugin.module';
 import { PlatformTransportModule } from './transport/transport.module';
 import { AppMetadataModule } from './app-metadata';
 import { PlatformConfigModule } from './config';
-import { LoggerInitializingModule } from './logging';
+import { GlobalExceptionsModule } from './exceptions.handling';
+import { LoggingCoreModule } from './logging';
 import { TracingModule } from './tracing';
 import type { PlatformAppPlugin, PlatformExtendedOptions } from './types';
 import { APP_PLUGINS, APP_TRANSPORTS } from './types';
@@ -19,21 +20,41 @@ export class PlatformModule implements NestModule {
   static forRoot(options: PlatformExtendedOptions): DynamicModule {
     const imports: (DynamicModule | Constructor)[] = [
       /**
-       * Последовательность принципиально важна так как в этом модуле происходит
-       * инициализация глобального асинхронного контекста (AsyncLocalStorage)
+       * Последовательность принципиально важна так как от порядка подключения будет зависеть
+       * порядок отработки глобальных интерцепторов
        */
+
+      // Interceptor: инициализация асинхронного контекста
       AsyncContextModule,
+
+      // Interceptor: Извлечение трассируемых заголовков из запроса
       TracingModule.forRoot(options),
 
-      // Plugins
+      // Interceptor: LoggingInterceptor
+      LoggingCoreModule.forRoot(options),
+
+      // Interceptor: Форматирование ошибок
+      GlobalExceptionsModule.forRoot(options),
+
+      // Interceptor: из конкретных реализаций транспортов (если есть)
+      PlatformTransportModule.forOptions(options),
+
+      /**
+       * Далее порядок не важен, т. к. интерцепторов нет. Последовательность
+       * инициализации провайдеров Nest.js разрулит самостоятельно.
+       */
+
+      // Инициализация плагинов
       PlatformPluginModule.forOptions(options),
 
-      // Infrastructure
+      // Метаданные сервиса
       AppMetadataModule.forRoot(options),
+
+      // Чтение и валидация конфигурации приложения
       PlatformConfigModule.forRoot(options),
-      LoggerInitializingModule,
+
+      // Прикладные модули
       ...(options.modules ?? []),
-      PlatformTransportModule.forOptions(options),
     ];
 
     const providers = [

package/src/tracing/constants.ts

@@ -1,4 +1,3 @@
-import type { TracingOptions } from './tracing.module';
 import type { TracingHeaderMappings } from './types';
 
 /**
@@ -7,13 +6,15 @@ import type { TracingHeaderMappings } from './types';
 export const HEADER_MAPPINGS = Symbol('HEADER_MAPPINGS');
 
 /**
- * Default mappings for tracing headers
+ * Header extractors injection token
  */
-export const DEFAULT_TRACING_HEADERS: TracingHeaderMappings[] = [
-  ['requestId', 'X-Request-Id', 'X-Requestid'],
-];
+export const HEADER_EXTRACTORS = Symbol('HEADER_EXTRACTORS');
 
 /**
- * Default tracing options
+ * Default mappings for tracing headers
  */
-export const DEFAULT_TRACING_OPTIONS: TracingOptions = { includeDefault: true };
+export const REQUEST_ID_HEADERS: TracingHeaderMappings = [
+  'requestId',
+  'X-Request-Id',
+  'X-Requestid',
+];

package/src/tracing/index.ts

@@ -2,3 +2,4 @@ export * from './tracing.module';
 export * from './tracing.actx';
 export * from './opentelemetry';
 export * from './types';
+export * from './request-id';

package/src/tracing/request-id/index.ts

@@ -0,0 +1,4 @@
+export * from './request-id-gen.decorator';
+export * from './metadata.helpers';
+export * from './types';
+export * from './with-prefix.fn';

package/src/tracing/request-id/metadata.helpers.ts

@@ -0,0 +1,24 @@
+import type { GenerateRequestId } from './types';
+
+const REQUEST_ID_GEN_STRATEGY_KEY = Symbol('REQUEST_ID_GEN_STRATEGY');
+
+/**
+ * Sets the requestId generation strategy for a class
+ * @param {object} target - The target object to set the strategy on
+ * @param {GenerateRequestId} strategy - The strategy to use for generating requestIds
+ */
+export const setStrategy = (
+  target: object,
+  strategy: GenerateRequestId,
+): void => {
+  Reflect.defineMetadata(REQUEST_ID_GEN_STRATEGY_KEY, strategy, target);
+};
+
+/**
+ * Gets the requestId generation strategy for a class
+ * @param {object} target - The target object to get the strategy from
+ * @returns {GenerateRequestId | undefined} The requestId generation strategy for the class
+ */
+export const getStrategy = (target: object): GenerateRequestId | undefined => {
+  return Reflect.getMetadata(REQUEST_ID_GEN_STRATEGY_KEY, target);
+};

package/src/tracing/request-id/request-id-gen.decorator.ts

@@ -0,0 +1,16 @@
+import { setStrategy } from './metadata.helpers';
+import type { GenerateRequestId } from './types';
+
+/**
+ * Decorator that sets the requestId generation strategy for
+ * all controller methods
+ * @param {GenerateRequestId} strategy - The strategy to use for generating requestIds
+ * @returns {ClassDecorator} A decorator that sets the requestId generation strategy for a class
+ */
+export const RequestIdGenStrategy = (
+  strategy: GenerateRequestId,
+): ClassDecorator => {
+  return (target: object) => {
+    setStrategy(target, strategy);
+  };
+};

package/src/tracing/request-id/types.ts

@@ -0,0 +1,6 @@
+import type { ExecutionContext } from '@nestjs/common';
+
+export type GenerateRequestId = (
+  ctx: ExecutionContext,
+  protocol: string,
+) => string;

package/src/tracing/request-id/with-prefix.fn.ts

@@ -0,0 +1,44 @@
+import { randomBytes } from 'node:crypto';
+
+import type { GenerateRequestId } from './types';
+
+/**
+ * Generates a random hex string of the given length
+ * @param {number} length - The length of the random hex string to generate
+ * @returns {string} A random hex string of the given length
+ */
+export const randomHex = (length: number): string =>
+  randomBytes(length).toString('hex');
+
+/**
+ * Default length of the generated requestId
+ * random bytes part
+ */
+export const DEFAULT_LENGTH = 8;
+
+/**
+ * Default prefix of the generated requestId
+ */
+export const DEFAULT_PREFIX = 'gen';
+
+/**
+ * Creates a function that generates a requestId with
+ * a static prefix and a random bytes part.
+ * Ex: {prefix}:{randomHex(length)}
+ *
+ * @param {string} [prefix=DEFAULT_PREFIX] - The prefix to use for the generated requestId.
+ * @param {number} [length=DEFAULT_LENGTH] - The length of the random bytes part of the requestId.
+ * @returns {GenerateRequestId} A function that generates a requestId in the format {prefix}:{randomHex(length)}.
+ */
+export const withPrefix =
+  (
+    prefix: string = DEFAULT_PREFIX,
+    length: number = DEFAULT_LENGTH,
+  ): GenerateRequestId =>
+  () =>
+    `${prefix}:${randomHex(length)}`;
+
+/**
+ * Default requestId generator function
+ */
+export const generateDefault = withPrefix();

package/src/tracing/tracing.config.ts

@@ -0,0 +1,23 @@
+import { BoolParser, text } from '@rsdk/common';
+
+import { Config, ConfigSection, Property } from '../config';
+import { ConfigTag } from '../config/config.const';
+
+@ConfigSection({ tags: [ConfigTag.tracing] })
+export class TracingConfig extends Config {
+  @Property('TRACING_REQUEST_ID', new BoolParser(), {
+    description: 'Add requestId (X-Request-ID) tracing',
+    defaultValue: true,
+  })
+  traceRequestId!: boolean;
+
+  @Property('TRACING_REQUEST_ID_AUTOGENERATE', new BoolParser(), {
+    description: text`
+      Automatically generate requestId (correlationId) if it
+      is not set in the headers. It will be created as
+      some random bytes (hex) string with "gen:" prefix.
+    `,
+    defaultValue: false,
+  })
+  autogenerate!: boolean;
+}

package/src/tracing/tracing.interceptor.ts

@@ -9,15 +9,12 @@ import type { Observable } from 'rxjs';
 import { InternalException } from '../exceptions';
 import { ILogger, InjectLogger } from '../logging';
 import { ProtocolDetector } from '../transport/protocol.detector';
-import type {
-  ITransport,
-  PlatformAppPlugin,
-  WithGenericHeaders,
-} from '../types';
-import { APP_PLUGINS, APP_TRANSPORTS } from '../types';
+import type { WithGenericHeaders } from '../types';
 
-import { HEADER_MAPPINGS } from './constants';
+import { HEADER_EXTRACTORS, HEADER_MAPPINGS } from './constants';
+import { generateDefault, getStrategy } from './request-id';
 import { TracingHeaders } from './tracing.actx';
+import { TracingConfig } from './tracing.config';
 import type { TracingHeaderMappings } from './types';
 
 /**
@@ -26,29 +23,15 @@ import type { TracingHeaderMappings } from './types';
  */
 @Injectable()
 export class TracingInterceptor implements NestInterceptor {
-  /**
-   * Extractors can be either transports or additional strategies
-   * supplied by plugins
-   */
-  private readonly extractors = new Map<string, WithGenericHeaders>();
-
   constructor(
+    /* eslint-disable prettier/prettier */
     @InjectLogger(TracingInterceptor) private logger: ILogger,
-    @Inject(APP_TRANSPORTS) private transports: Set<ITransport>,
-    @Inject(APP_PLUGINS) private plugins: Set<PlatformAppPlugin>,
     @Inject(HEADER_MAPPINGS) private mappings: TracingHeaderMappings[],
-    private detector: ProtocolDetector,
-  ) {
-    for (const transport of this.transports) {
-      this.extractors.set(transport.getProtocol(), transport);
-    }
-
-    for (const plugin of this.plugins) {
-      for (const x of plugin.tracingHeadersExtractors?.() ?? []) {
-        this.extractors.set(x.protocol, x.extractor);
-      }
-    }
-  }
+    @Inject(HEADER_EXTRACTORS) private readonly extractors: Map<string, WithGenericHeaders>,
+    private readonly detector: ProtocolDetector,
+    private readonly config: TracingConfig,
+    /* eslint-enable prettier/prettier */
+  ) {}
 
   intercept(ctx: ExecutionContext, next: CallHandler): Observable<any> {
     const protocol = this.detector.getProtocol(ctx) ?? ctx.getType();
@@ -60,6 +43,24 @@ export class TracingInterceptor implements NestInterceptor {
       );
     }
 
+    const headers = this.extractHeaders(ctx, extractor);
+
+    const { traceRequestId, autogenerate } = this.config;
+    if (!headers.requestId && traceRequestId && autogenerate) {
+      headers.requestId = this.generateRequestId(ctx, protocol);
+    }
+
+    this.logger.trace('Extracted traceable headers', { headers });
+
+    TracingHeaders.set(headers);
+
+    return next.handle();
+  }
+
+  private extractHeaders(
+    ctx: ExecutionContext,
+    extractor: WithGenericHeaders,
+  ): Record<string, string> {
     const headers: Record<string, string> = {};
 
     for (const aliases of this.mappings) {
@@ -68,13 +69,17 @@ export class TracingInterceptor implements NestInterceptor {
         .map((x) => extractor.extractHeaders(ctx).get(x))
         .find((x) => x);
 
-      headers[key] = value || '[missing]';
+      if (value) {
+        headers[key] = value;
+      }
     }
 
-    this.logger.trace('Extracted traceable headers', { headers });
+    return headers;
+  }
 
-    TracingHeaders.set(headers);
+  private generateRequestId(ctx: ExecutionContext, protocol: string): string {
+    const generate = getStrategy(ctx.getClass()) ?? generateDefault;
 
-    return next.handle();
+    return generate(ctx, protocol);
   }
 }