@rsdk/core 5.0.0-next.1 → 5.0.0-next.3

package/src/tracing/opentelemetry/opentelemetry.helpers.ts

@@ -0,0 +1,89 @@
+import type { AttributeValue, Span } from '@opentelemetry/api';
+import { SpanStatusCode } from '@opentelemetry/api';
+import { isPrimitive, isRecord, normalizer, Size } from '@rsdk/common';
+import { catchError, mergeMap, type Observable, of, throwError } from 'rxjs';
+
+/**
+ * Maximum span attribute size
+ */
+export const MAX_ATTRIBUTE_SIZE = new Size(100, 'kb');
+
+/**
+ * Makes correct opentelemetry span attribute from any value
+ * @param data unknown value of any type
+ * @returns AttributeValue
+ */
+export const toAttribute = (data: unknown): AttributeValue => {
+  if (isPrimitive(data)) {
+    return data;
+  }
+
+  if (isRecord(data) || Array.isArray(data)) {
+    const serialized = JSON.stringify(normalizer()(data));
+
+    return serialized.length <= MAX_ATTRIBUTE_SIZE.bytes()
+      ? serialized
+      : `data exceeds limit of ${MAX_ATTRIBUTE_SIZE.bytes()} bytes`;
+  }
+
+  return 'data is undefined';
+};
+
+/**
+ * Adds data to span with key "result" and ends it.
+ * @param span Span
+ * @param data Any piece of data
+ */
+export const endWithResult = (span: Span, data: unknown): void => {
+  span.setAttribute('result', toAttribute(data));
+  span.setStatus({ code: SpanStatusCode.OK });
+  span.end();
+};
+
+/**
+ * Adds error object to span and ends it
+ * @param span Span
+ * @param error Error
+ */
+export const endWithError = (span: Span, error: Error): void => {
+  span.recordException(error);
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message: error.message,
+  });
+  span.end();
+};
+
+export const processSyncResult = <T = unknown>(result: T, span: Span): T => {
+  endWithResult(span, result);
+  return result;
+};
+
+export const processObservableResult = <T = unknown>(
+  result: Observable<T>,
+  span: Span,
+): Observable<T> =>
+  result.pipe(
+    mergeMap((result) => {
+      endWithResult(span, result);
+      return of(result);
+    }),
+    catchError((error) => {
+      endWithError(span, error);
+      return throwError(() => error);
+    }),
+  );
+
+export const processPromiseResult = <T = unknown>(
+  result: Promise<T>,
+  span: Span,
+): Promise<T> =>
+  result
+    .then((result) => {
+      endWithResult(span, result);
+      return result;
+    })
+    .catch((error) => {
+      endWithError(span, error);
+      throw error;
+    });

package/src/tracing/opentelemetry/opentelemetry.metadata.ts

@@ -0,0 +1,24 @@
+import assert from 'node:assert';
+
+export const OTEL_METADATA = {
+  NO_SPAN: 'NO_SPAN_METADATA',
+  IS_WRAPPED: 'OPEN_TELEMETRY_TRACE_METADATA_ACTIVE',
+};
+
+export const isNoSpan = (prototype: object): boolean => {
+  assert.ok(prototype);
+
+  return Reflect.hasMetadata(OTEL_METADATA.NO_SPAN, prototype);
+};
+
+export const isWrapped = (prototype: object): boolean => {
+  assert.ok(prototype);
+
+  return Reflect.hasMetadata(OTEL_METADATA.IS_WRAPPED, prototype);
+};
+
+export const setWrapped = (prototype: object): void => {
+  assert.ok(prototype);
+
+  Reflect.defineMetadata(OTEL_METADATA.IS_WRAPPED, true, prototype);
+};

package/src/tracing/opentelemetry/opentelemetry.wrapper.ts

@@ -0,0 +1,90 @@
+import type { TraceAPI } from '@opentelemetry/api';
+import { Assert, text } from '@rsdk/common';
+import { redecorate } from '@rsdk/decorators';
+import type { ILogger } from '@rsdk/logging';
+import { LoggerFactory } from '@rsdk/logging';
+import { Observable } from 'rxjs';
+
+import {
+  endWithError,
+  processObservableResult,
+  processPromiseResult,
+  processSyncResult,
+  toAttribute,
+} from './opentelemetry.helpers';
+import { isNoSpan, isWrapped, setWrapped } from './opentelemetry.metadata';
+
+export class OpentelemetryWrapper {
+  private readonly logger: ILogger = LoggerFactory.create(OpentelemetryWrapper);
+  private readonly trace: TraceAPI | null;
+
+  constructor() {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const { trace } = require('@opentelemetry/api');
+
+      this.trace = trace;
+    } catch {
+      this.trace = null;
+      this.logger.debug(text`
+        @opentelemetry/api is not installed.
+        @Span() decorator will not make any effect.`);
+    }
+  }
+
+  wrap(
+    cls: any,
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    original: Function,
+    descriptor?: TypedPropertyDescriptor<any>,
+  ): void {
+    if (!this.trace || isWrapped(original) || isNoSpan(original)) {
+      return;
+    }
+
+    const spanName = `${cls.constructor.name} -> ${original.name}`;
+
+    this.logger.debug(`Wrapping method: ${spanName}`);
+
+    const tracer = this.trace.getTracer(`rsdk:${cls.constructor.name}`);
+
+    const wrapped = {
+      [original.name](...args: unknown[]): unknown {
+        return tracer.startActiveSpan(spanName, (span) => {
+          span.setAttribute('args', toAttribute(args));
+
+          try {
+            const result = original.apply(this, args);
+
+            if (result instanceof Promise) {
+              return processPromiseResult(result, span);
+            }
+
+            if (result instanceof Observable) {
+              return processObservableResult(result, span);
+            }
+
+            return processSyncResult(result, span);
+          } catch (error) {
+            Assert.isError(error);
+            endWithError(span, error);
+            throw error;
+          }
+        });
+      },
+    }[original.name];
+
+    redecorate(original, wrapped);
+
+    if (descriptor) {
+      descriptor.value = wrapped;
+    } else {
+      cls[original.name] = wrapped;
+    }
+
+    /**
+     * Отмечает метод, как обёрнутый (чтобы избежать повторного оборачивания)
+     */
+    setWrapped(wrapped);
+  }
+}

package/src/tracing/tracing.actx.ts

@@ -0,0 +1,8 @@
+import { createAsyncContextProvider } from '@rsdk/actx';
+
+export const TracingHeaders = createAsyncContextProvider<
+  Record<string, string>
+>({
+  name: 'TracingHeaders',
+  rewritable: false,
+});

package/src/tracing/tracing.interceptor.ts

@@ -3,22 +3,79 @@ import type {
   ExecutionContext,
   NestInterceptor,
 } from '@nestjs/common';
-import { Injectable } from '@nestjs/common';
-import { RequestIdProvider } from '@rsdk/tracing';
+import { Inject, Injectable } from '@nestjs/common';
 import type { Observable } from 'rxjs';
 
-import { TracingHeadersExtractor } from '../types/tracing.headers-extractor';
+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 { X_REQUEST_ID } from './constants';
+import { HEADER_MAPPINGS } from './constants';
+import { TracingHeaders } from './tracing.actx';
+import type { TracingHeaderMappings } from './types';
 
+/**
+ * Extracts headers that should be passed to all logging messages
+ * and external calls
+ */
 @Injectable()
 export class TracingInterceptor implements NestInterceptor {
-  constructor(private headersExtractor: TracingHeadersExtractor) {}
+  /**
+   * Extractors can be either transports or additional strategies
+   * supplied by plugins
+   */
+  private readonly extractors = new Map<string, WithGenericHeaders>();
+
+  constructor(
+    @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);
+      }
+    }
+  }
+
+  intercept(ctx: ExecutionContext, next: CallHandler): Observable<any> {
+    const protocol = this.detector.getProtocol(ctx) ?? ctx.getType();
+
+    const extractor = this.extractors.get(protocol);
+    if (!extractor) {
+      throw new InternalException(
+        `No headers extractor for protocol: ${protocol}`,
+      );
+    }
+
+    const headers: Record<string, string> = {};
+
+    for (const aliases of this.mappings) {
+      const key = aliases[0];
+      const value = aliases
+        .map((x) => extractor.extractHeaders(ctx).get(x))
+        .filter((x) => x)
+        .at(0);
+
+      headers[key] = value || '[missing]';
+    }
+
+    this.logger.trace('Extracted traceable headers', { headers });
 
-  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
-    const h = this.headersExtractor.extract(context).getHeaders();
+    TracingHeaders.set(headers);
 
-    RequestIdProvider.set(h[X_REQUEST_ID]);
     return next.handle();
   }
 }

package/src/tracing/tracing.module.ts

@@ -1,56 +1,97 @@
 import type { DynamicModule, OnModuleInit } from '@nestjs/common';
 import { Module } from '@nestjs/common';
 import { APP_INTERCEPTOR } from '@nestjs/core';
-import type { SpanContext } from '@opentelemetry/api';
-import { context, trace } from '@opentelemetry/api';
+import type { ContextAPI, TraceAPI } from '@opentelemetry/api';
+import { text } from '@rsdk/common';
 import { ILogger, LoggerFactory } from '@rsdk/logging';
-import { RequestIdProvider } from '@rsdk/tracing';
 
 import { InjectLogger } from '../logging';
-import { TracingHeadersExtractor } from '../types/tracing.headers-extractor';
+import type { PlatformOptions } from '../types';
 
-import { RequestMetadataModule } from './request-metadata.module';
-import { TracingModuleConfig } from './tracing.config';
+import {
+  DEFAULT_TRACING_HEADERS,
+  DEFAULT_TRACING_OPTIONS,
+  HEADER_MAPPINGS,
+} from './constants';
+import { TracingHeaders } from './tracing.actx';
 import { TracingInterceptor } from './tracing.interceptor';
+import type { TracingHeaderMappings } from './types';
+
+export interface TracingOptions {
+  includeDefault: boolean;
+  additionalMappings?: TracingHeaderMappings[];
+}
 
 @Module({})
 export class TracingModule implements OnModuleInit {
-  constructor(
-    @InjectLogger(TracingModule) private readonly logger: ILogger,
-    private readonly config: TracingModuleConfig,
-  ) {}
+  private trace: TraceAPI | null = null;
+  private context: ContextAPI | null = null;
+
+  constructor(@InjectLogger(TracingModule) private readonly logger: ILogger) {}
+
+  static forRoot({
+    tracing = DEFAULT_TRACING_OPTIONS,
+    plugins = [],
+  }: PlatformOptions): DynamicModule {
+    const mappings: TracingHeaderMappings[] = [];
+
+    if (tracing?.includeDefault) {
+      mappings.push(...DEFAULT_TRACING_HEADERS);
+    }
+
+    for (const plugin of plugins) {
+      mappings.push(...(plugin.additionalTracingHeaders?.() ?? []));
+    }
+
+    mappings.push(...(tracing.additionalMappings ?? []));
 
-  static forRoot(): DynamicModule {
     return {
+      global: true,
       module: TracingModule,
-      imports: [RequestMetadataModule],
       providers: [
         { provide: APP_INTERCEPTOR, useClass: TracingInterceptor },
-        TracingHeadersExtractor,
+        { provide: HEADER_MAPPINGS, useValue: mappings },
       ],
     };
   }
 
   // Можно добавить включение и выключение при изменении конфига.
   async onModuleInit(): Promise<void> {
-    LoggerFactory.applyInstrumentations((record) => {
-      record['request_id'] = RequestIdProvider.get();
-      const span = trace.getSpan(context.active());
-      if (!span) {
-        return;
+    if (!this.context || !this.trace) {
+      try {
+        const { context, trace } = await import('@opentelemetry/api');
+
+        this.context = context;
+        this.trace = trace;
+      } catch {
+        this.logger.debug(text`
+          @opentelemetry/api is not installed. Opentelemetry metadata will
+          not appear in log messages.
+        `);
       }
-      const spanContext: SpanContext = span.spanContext();
+    }
+
+    LoggerFactory.applyInstrumentations((record) => {
+      Object.assign(record, TracingHeaders.get() || {});
+
+      if (this.trace && this.context) {
+        const { traceId, spanId } =
+          this.trace.getSpan(this.context.active())?.spanContext() ?? {};
 
-      record['trace_id'] = spanContext.traceId;
-      record['span_id'] = spanContext.spanId;
+        record['trace_id'] = traceId;
+        record['span_id'] = spanId;
+      }
     });
+
     this.logger.info('Tracing is enabled');
 
     this.logger.debug('Attaching log messages to spans...');
     LoggerFactory.onMessage((level, msg) => {
-      const span = trace.getSpan(context.active());
+      if (this.trace && this.context) {
+        const span = this.trace.getSpan(this.context.active());
 
-      span?.addEvent('log', { ...msg, level });
+        span?.addEvent('log', { ...msg, level });
+      }
     });
   }
 }

package/src/tracing/types.ts

@@ -1,28 +1,9 @@
-import { randomUUID } from 'node:crypto';
-
-import { X_REQUEST_ID } from './constants';
-
-export type Headers = {
-  [X_REQUEST_ID]: string;
-};
-
-export const tracingHeaders = [X_REQUEST_ID] as const;
-
-export class TracingHeaders {
-  constructor(headers: Partial<Headers>) {
-    this.headers = {
-      ...headers,
-      [X_REQUEST_ID]: headers[X_REQUEST_ID] ?? this.createRequestId(),
-    } as Headers;
-  }
-
-  getHeaders(): Headers {
-    return this.headers;
-  }
-
-  private createRequestId(): string {
-    return randomUUID();
-  }
-
-  private headers: Headers;
-}
+/**
+ * The idea of this mappings is to enable aliases. Ex:
+ * ['requestId', 'X-Request-Id', 'X-Requestid] means that first of this
+ * headers found will be taken. And then the first one will be used.
+ *
+ * In other way, the first element is main header name, and other are
+ * possible aliases.
+ */
+export type TracingHeaderMappings = [string, ...string[]];

package/src/transport/protocol.detector.ts

@@ -1,36 +1,30 @@
 import type { ArgumentsHost } from '@nestjs/common';
 
-import { InternalException } from '../exceptions';
 import type { ITransport } from '../types';
 
+/**
+ * This class is used to detect current protocol (transport type).
+ * Mostly used in global enhancers to decide: "to work of not to work"
+ */
 export class ProtocolDetector {
   constructor(private transports: ITransport[]) {}
 
-  getTransport(context: ArgumentsHost): ITransport | undefined {
-    if (this.transports.length === 0) {
-      return;
-    }
-    const matchers = this.transports.map((tr) => ({
-      matched: tr.matchByContext(context),
-      tr,
-    }));
-    const matched = matchers.filter((matched) => matched.matched);
-    if (matched.length > 1) {
-      throw new InternalException('So many matchers for transports', {
-        cause: {
-          matchers,
-          matched,
-          context,
-        },
-      });
-    }
-    if (matched.length === 0) {
-      return;
-    }
-    return matched[0].tr;
-  }
-
+  /**
+   * Detects transport's protocol by ArgumentHost (context)
+   */
   getProtocol(context: ArgumentsHost): string | undefined {
     return this.getTransport(context)?.getProtocol();
   }
+
+  /**
+   * Checks that transport's protocol matches the provided one.
+   * (just convenience method)
+   */
+  matchProtocol(context: ArgumentsHost, protocol: string): boolean {
+    return this.getProtocol(context) === protocol;
+  }
+
+  private getTransport(context: ArgumentsHost): ITransport | undefined {
+    return this.transports.filter((x) => x.matchByContext(context)).pop();
+  }
 }

package/src/types/index.ts

@@ -1,5 +1,3 @@
-export { getTransportId, TransportId } from '../transport/get-transport-id';
-
 export * from './metadata';
 export * from './options';
 export * from './transports';

package/src/types/options.ts

@@ -2,6 +2,7 @@ import type { RequiredFields } from '@rsdk/common';
 import type { NestModuleDefinition } from '@rsdk/common.nestjs';
 
 import type { ConfigModuleOptions } from '../config';
+import type { TracingOptions } from '../tracing';
 
 import type { PlatformAppPlugin } from './plugins';
 import type { IPrimaryTransport, ITransport } from './transports';
@@ -77,6 +78,8 @@ export interface PlatformOptions extends PlatformManifestPathOptions {
    * Plugins extend application functionality.
    */
   plugins?: PlatformAppPlugin[];
+
+  tracing?: TracingOptions;
 }
 
 export type PlatformAppOptions = RequiredFields<

package/src/types/plugins.ts

@@ -7,8 +7,9 @@ import type {
   IErrorsSender,
   IErrorsTransformer,
 } from '../exceptions.handling';
+import type { TracingHeaderMappings } from '../tracing';
 
-import type { ProtocolTracingHeadersExtractor } from './transports';
+import type { WithGenericHeaders } from './transports';
 
 export type SpecifiedTransports = Readonly<string[]>;
 export type AppropriateTransports = SpecifiedTransports | 'any';
@@ -34,9 +35,10 @@ export interface PlatformAppPlugin<
   extractors?(): ResourceExtractor[];
 
   tracingHeadersExtractors?(): {
-    extractor: ProtocolTracingHeadersExtractor;
     protocol: string;
+    extractor: WithGenericHeaders;
   }[];
+
   /**
    * Returns list of appropriate transports.
    *
@@ -79,4 +81,9 @@ export interface PlatformAppPlugin<
    * @param consumer MiddlewareConsumer
    */
   configureMiddleware?(consumer: MiddlewareConsumer): void;
+
+  /**
+   * Additional header mappings
+   */
+  additionalTracingHeaders?(): TracingHeaderMappings[];
 }

package/src/types/transports.ts

@@ -1,5 +1,9 @@
-import type { ArgumentsHost, ExecutionContext } from '@nestjs/common';
-import type { Controller, INestApplication } from '@nestjs/common/interfaces';
+import type { ArgumentsHost } from '@nestjs/common';
+import type {
+  Controller,
+  ExecutionContext,
+  INestApplication,
+} from '@nestjs/common/interfaces';
 import type { AbstractHttpAdapter } from '@nestjs/core';
 import type { MicroserviceOptions } from '@nestjs/microservices';
 import type { Constructor } from '@rsdk/common';
@@ -10,14 +14,32 @@ import type {
   IErrorsSender,
   IErrorsTransformer,
 } from '../exceptions.handling';
-import type { TracingHeaders } from '../tracing/types';
 
 import type { NestModuleDefinitions } from './options';
 
+export interface GenericHeaders {
+  get(key: string): string | undefined;
+}
+
+/**
+ * Every transport has generic some sort of headers/metadata
+ * that can be represented as key/value pairs. But implementation
+ * differs. This interface is made to generalize this headers
+ *
+ * NOTE: Not only transports but also plugins can implement
+ * this interface
+ */
+export interface WithGenericHeaders {
+  extractHeaders(context: ExecutionContext): GenericHeaders;
+}
+
+export const hasGenericHeaders = (x: unknown): x is WithGenericHeaders =>
+  typeof (x as any)?.getHeaders === 'function';
+
 /**
  * Base functionality of HTTP or microservice transport
  */
-export interface ITransport {
+export interface ITransport extends WithGenericHeaders {
   /**
    * @returns protocol in text format
    */
@@ -54,8 +76,6 @@ export interface ITransport {
    * Modules for register metrics, healthchecks, configs and supporting tools, such as clients
    */
   modules?(): NestModuleDefinitions;
-
-  getHeaderExtractor(): ProtocolTracingHeadersExtractor;
 }
 
 /**
@@ -75,7 +95,7 @@ export interface IPrimaryTransport extends ITransport {
  */
 export interface IMicroserviceTransport extends ITransport {
   /**
-   * @retures options ready to be passed to
+   * @returns options ready to be passed to
    * NestFactory.createMicroservice() or
    * app.connectMicroservice()
    */
@@ -137,7 +157,3 @@ export const isMicroserviceTransport = (
   t: ITransport,
 ): t is IMicroserviceTransport =>
   typeof (t as IMicroserviceTransport).createMicroserviceOptions === 'function';
-
-export interface ProtocolTracingHeadersExtractor {
-  extract(ctx: ExecutionContext): TracingHeaders;
-}

package/dist/tracing/decorators/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tracing/decorators/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sDAAoC;AACpC,mDAAiC"}

package/dist/tracing/decorators/no-span.decorator.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"no-span.decorator.js","sourceRoot":"","sources":["../../../src/tracing/decorators/no-span.decorator.ts"],"names":[],"mappings":";;;AAAA,2CAA6C;AAE7C,4CAAyC;AAEzC;;;GAGG;AACI,MAAM,MAAM,GAAG,GAAoB,EAAE,CAC1C,IAAA,oBAAW,EAAC,qBAAS,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;AADnC,QAAA,MAAM,UAC6B"}

package/dist/tracing/decorators/span.decorator.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"span.decorator.js","sourceRoot":"","sources":["../../../src/tracing/decorators/span.decorator.ts"],"names":[],"mappings":";;;AAAA,uCAA+C;AAE/C,iDAAgE;AAChE,0CAA4C;AAE5C,MAAM,eAAe,GAAG,IAAI,sBAAe,EAAE,CAAC;AAE9C;;;;GAIG;AACI,MAAM,IAAI,GAAG,GAAqC,EAAE;AACzD,+DAA+D;AAC/D,UACE,MAAc,EACd,UAA4B,EAC5B,UAAyC;IAEzC,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;QACnC,MAAM,IAAI,yCAA4B,EAAE,CAAC;IAC3C,CAAC;IACD,IAAI,UAAU,IAAI,UAAU,EAAE,CAAC;QAC7B,wBAAa,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;QACzD,OAAO;IACT,CAAC;IACD,MAAM,SAAS,GAAI,MAAc,CAAC,SAAS,IAAI,MAAM,CAAC;IAEtD,KAAK,MAAM,IAAI,IAAI,eAAe,CAAC,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC;QAChE,IAAI,IAAI,EAAE,CAAC;YACT,wBAAa,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;AACH,CAAC,CAAC;AArBS,QAAA,IAAI,QAqBb"}

package/dist/tracing/request-metadata.module.d.ts

@@ -1,5 +0,0 @@
-/**
- * Модуль для хранения и получения данных из аскин локал стораджа
- */
-export declare class RequestMetadataModule {
-}