@rsdk/core 0.14.0

package/src/platform.module.ts

@@ -0,0 +1,65 @@
+import type { DynamicModule } from '@nestjs/common';
+import { Module } from '@nestjs/common';
+import type { MiddlewareConsumer, NestModule } from '@nestjs/common/interfaces';
+import type { Constructor } from '@rsdk/common';
+
+import { PlatformPluginModule } from './plugin/plugin.module';
+import { PlatformTransportModule } from './transport/transport.module';
+import { AppMetadataModule } from './app-metadata';
+import { PlatformConfigModule } from './config';
+import { SequenceException } from './exceptions';
+import { LoggingModule } from './logging';
+import { TracingModule } from './tracing';
+import type { PlatformExtendedOptions } from './types';
+
+@Module({})
+export class PlatformModule implements NestModule {
+  private static options: PlatformExtendedOptions;
+
+  static forRoot(options: PlatformExtendedOptions): DynamicModule {
+    if (this.options) {
+      throw new SequenceException(
+        "Can't call PlatformModule.setup() method twice",
+      );
+    }
+    this.options = options;
+
+    const imports: (DynamicModule | Constructor)[] = [
+      // Plugins
+      PlatformPluginModule.forOptions(options),
+
+      // Infrastructure
+      AppMetadataModule.forRoot(options),
+      LoggingModule.forRoot(),
+      PlatformConfigModule.forRoot(options),
+      TracingModule.forRoot({ appName: options.name, processing: 'simple' }),
+    ];
+
+    // Adding transport module if needed
+    if (options.transports) {
+      imports.push(PlatformTransportModule.forOptions(options));
+    }
+
+    // Adding application level modules
+    if (options.modules) {
+      imports.push(...options.modules);
+    }
+
+    return {
+      module: PlatformModule,
+      imports,
+    };
+  }
+
+  configure(consumer: MiddlewareConsumer): void {
+    if (!PlatformModule.options) {
+      throw new SequenceException(
+        'Should call PlatformModule.setup() before configuring middleware!',
+      );
+    }
+
+    for (const plugin of PlatformModule.options.plugins || []) {
+      plugin?.configureMiddleware?.(consumer);
+    }
+  }
+}

package/src/plugin/plugin.module.ts

@@ -0,0 +1,24 @@
+import type { DynamicModule } from '@nestjs/common';
+import type { Constructor } from '@rsdk/common';
+
+import type { PlatformExtendedOptions } from '../types';
+
+export class PlatformPluginModule {
+  static forOptions(options: PlatformExtendedOptions): DynamicModule {
+    const modules: (DynamicModule | Constructor)[] = [];
+
+    // Adding additional modules (from plugins)
+    if (options.plugins) {
+      for (const plugin of options.plugins) {
+        if (plugin.modules) {
+          modules.push(...plugin.modules());
+        }
+      }
+    }
+
+    return {
+      module: PlatformPluginModule,
+      imports: modules,
+    };
+  }
+}

package/src/tracing/auto-instrumentations.config.ts

@@ -0,0 +1,35 @@
+import { ClientRequest, IncomingMessage } from 'http';
+
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+
+export const autoInstumentationOptions = getNodeAutoInstrumentations({
+  '@opentelemetry/instrumentation-aws-sdk': {
+    responseHook: (span, { response }) => {
+      if (response.request.commandInput?.Bucket) {
+        span.setAttribute(
+          's3.bucket.name',
+          response.request.commandInput?.Bucket,
+        );
+      }
+    },
+  },
+  '@opentelemetry/instrumentation-graphql': {
+    allowValues: true,
+  },
+  '@opentelemetry/instrumentation-http': {
+    requestHook: (span, request) => {
+      if (request instanceof IncomingMessage) {
+        if (request.method && request.url) {
+          span.updateName(`${request.method} ${request.url}`);
+        }
+      } else if (request instanceof ClientRequest) {
+        if (request.req.method && request.req.url) {
+          span.updateName(`${request.req.method} ${request.req.url}`);
+        }
+      }
+    },
+  },
+  '@opentelemetry/instrumentation-pg': {
+    enhancedDatabaseReporting: true,
+  },
+});

package/src/tracing/constants.ts

@@ -0,0 +1,6 @@
+export enum Constants {
+  TRACE_METADATA_ACTIVE = 'OPEN_TELEMETRY_TRACE_METADATA_ACTIVE',
+  NO_SPAN_METADATA = 'NO_SPAN_METADATA',
+}
+
+export const MAX_BYTES = 100 * 1024; // 100kb;

package/src/tracing/decorators/index.ts

@@ -0,0 +1,2 @@
+export * from './no-span.decorator';
+export * from './span.decorator';

package/src/tracing/decorators/no-span.decorator.ts

@@ -0,0 +1,10 @@
+import { SetMetadata } from '@nestjs/common';
+
+import { Constants } from '../constants';
+
+/**
+ * TraceInjector will ignore classes and methods annotated with
+ * this decorator.
+ */
+export const NoSpan = (): MethodDecorator =>
+  SetMetadata(Constants.NO_SPAN_METADATA, true);

package/src/tracing/decorators/span.decorator.ts

@@ -0,0 +1,20 @@
+import { SymbolKeyDecorationException } from '../../exceptions';
+import { TraceInjector } from '../services';
+
+/**
+ * Explicitly adds instrumentation to method (don't work for classes!).
+ * Use for classes that you instantiate manually.
+ * NOTE: Is redundant for injectables and other nest.js stuff
+ */
+export const Span = (): MethodDecorator =>
+  function (
+    target: object,
+    methodName: string | symbol,
+    descriptor: TypedPropertyDescriptor<any>,
+  ) {
+    if (typeof methodName === 'symbol') {
+      throw new SymbolKeyDecorationException();
+    }
+
+    TraceInjector.wrap(target, descriptor.value, descriptor);
+  };

package/src/tracing/index.ts

@@ -0,0 +1 @@
+export * from './tracing.module';

package/src/tracing/services/index.ts

@@ -0,0 +1,3 @@
+export * from './instrumentation.service';
+export * from './metadata.scanner';
+export * from './trace.injector';

package/src/tracing/services/instrumentation.service.ts

@@ -0,0 +1,145 @@
+import { Injectable } from '@nestjs/common';
+import {
+  EXCEPTION_FILTERS_METADATA,
+  GUARDS_METADATA,
+  INTERCEPTORS_METADATA,
+  PIPES_METADATA,
+} from '@nestjs/common/constants';
+import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR, APP_PIPE } from '@nestjs/core';
+import { ILogger } from '@rsdk/logging';
+
+import { InjectLogger } from '../../logging';
+
+import { ExtendedMetadataScanner } from './metadata.scanner';
+import { TraceInjector } from './trace.injector';
+
+const types = [
+  EXCEPTION_FILTERS_METADATA,
+  GUARDS_METADATA,
+  INTERCEPTORS_METADATA,
+  PIPES_METADATA,
+] as const;
+
+@Injectable()
+export class InstrumentationService {
+  constructor(
+    @InjectLogger(InstrumentationService) private readonly logger: ILogger,
+    protected readonly scanner: ExtendedMetadataScanner,
+  ) {}
+
+  public inject(): void {
+    /**
+     * Для каждого контроллера
+     */
+    for (const controller of this.scanner.getControllers()) {
+      /**
+       * Перебираем методы контроллера и оборачиваем их.
+       */
+      this.wrapMethods(controller.metatype.prototype);
+
+      this.wrapAugmentations(controller.metatype);
+
+      /**
+       * Для каждого метода контроллера
+       */
+      for (const name of this.scanner.getMethods(
+        controller.metatype.prototype,
+      )) {
+        /**
+         * Во вложенном цикле находим все гарды, интерцепторы, пайпы и фильтры,
+         * привязанные к методу.
+         * Уровни вложенности, как в цикле выше
+         */
+        const method = controller.metatype.prototype[name];
+
+        this.wrapAugmentations(method);
+      }
+    }
+
+    /**
+     * Глобальные гарды, интерцепторы, пайпы и фильтры находятся
+     * в общем списке провайдеров по injection-токенам.
+     */
+    for (const { metatype, token } of this.scanner.getProviders()) {
+      if (typeof token !== 'string') {
+        continue;
+      }
+
+      if (
+        token.includes(APP_GUARD) ||
+        token.includes(APP_PIPE) ||
+        token.includes(APP_INTERCEPTOR) ||
+        token.includes(APP_FILTER)
+      ) {
+        this.wrapMethods(metatype.prototype);
+      }
+    }
+
+    /**
+     * Глобальные гарды, интерцепторы, пайпы и фильтры находятся
+     * в общем списке провайдеров по injection-токенам.
+     */
+    for (const {
+      metatype: { name, prototype },
+    } of this.scanner.getProviders()) {
+      if (name.toLowerCase().endsWith('module')) {
+        continue;
+      }
+
+      if (
+        name === 'ModuleRef' ||
+        name === 'Reflector' ||
+        name === 'OrphanedReferenceRegistry' ||
+        name === 'TypeFieldsAccessor' ||
+        name === 'TypeMapperSevice' ||
+        name === 'TypeDefinitionsStorage' ||
+        name === 'FileSystemHelper' ||
+        name === 'TypeDefinitionsGenerator' ||
+        name === 'GraphQLSchemaFactory' ||
+        name === 'AstDefinitionNodeFactory' ||
+        name === 'UnionDefinitionFactory' ||
+        name === 'SubscriptionTypeFactory' ||
+        name === 'RootTypeFactory' ||
+        name === 'ResolveTypeFactory' ||
+        name === 'QueryTypeFactory' ||
+        name === 'OrphanedTypesFactory' ||
+        name === 'OutputTypeFactory' ||
+        name === 'ObjectTypeDefinitionFactory' ||
+        name === 'MutationTypeFactory' ||
+        name === 'InterfaceDefinitionFactory' ||
+        name === 'InputTypeFactory' ||
+        name === 'ArgsFactory' ||
+        name === 'InputTypeDefinitionFactory' ||
+        name === 'EnumDefinitionFactory'
+      ) {
+        continue;
+      }
+
+      this.wrapMethods(prototype);
+    }
+  }
+
+  private wrapAugmentations(metatype: object): void {
+    /**
+     * Перебираем во вложенных циклах все гарды, интерцепторы, пайпы и фильтры,
+     * повешенные на переданный прототип (metatype).
+     * 1-й уровень - типы сущностей: интерцепторы, гарды, пайпы, фильтры
+     * 2-й уровень - методы сущностей
+     */
+    for (const metakey of types) {
+      for (const instance of Reflect.getMetadata(metakey, metatype) || []) {
+        this.wrapMethods(instance);
+      }
+    }
+  }
+
+  private wrapMethods(obj: any): void {
+    const prototype = (obj as any).prototype ?? obj;
+
+    this.logger.trace(`Wrapping methods of ${prototype.constructor.name}...`);
+
+    for (const name of this.scanner.getMethods(prototype)) {
+      TraceInjector.wrap(prototype, prototype[name]);
+    }
+  }
+}

package/src/tracing/services/metadata.scanner.ts

@@ -0,0 +1,40 @@
+import { Injectable } from '@nestjs/common';
+import type {
+  Controller,
+  Injectable as Provider,
+} from '@nestjs/common/interfaces';
+import { MetadataScanner, ModulesContainer } from '@nestjs/core';
+import type { InstanceWrapper } from '@nestjs/core/injector/instance-wrapper';
+
+@Injectable()
+export class ExtendedMetadataScanner {
+  private readonly scanner = new MetadataScanner();
+
+  constructor(private readonly modules: ModulesContainer) {}
+
+  *getControllers(): Generator<InstanceWrapper<Controller>> {
+    for (const module of this.modules.values()) {
+      for (const controller of module.controllers.values()) {
+        if (controller && controller.metatype?.prototype) {
+          yield controller;
+        }
+      }
+    }
+  }
+
+  *getProviders(): Generator<InstanceWrapper<Provider>> {
+    for (const module of this.modules.values()) {
+      for (const provider of module.providers.values()) {
+        if (provider && provider.metatype?.prototype) {
+          yield provider;
+        }
+      }
+    }
+  }
+
+  *getMethods(prototype: any): Generator<string> {
+    for (const name of this.scanner.getAllFilteredMethodNames(prototype)) {
+      yield name;
+    }
+  }
+}

package/src/tracing/services/trace.injector.ts

@@ -0,0 +1,147 @@
+import assert from 'assert';
+
+import type { AttributeValue, Span } from '@opentelemetry/api';
+import { SpanStatusCode, trace } from '@opentelemetry/api';
+import type { ErrorLike } from '@rsdk/common';
+import { isPrimitive, isRecord, normalizer } from '@rsdk/common';
+import { redecorate } from '@rsdk/decorators';
+import { LoggerFactory } from '@rsdk/logging';
+
+import { Constants, MAX_BYTES } from '../constants';
+
+const logger = LoggerFactory.create('TraceInjector');
+
+export class TraceInjector {
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  static wrap(
+    cls: any,
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    original: Function,
+    descriptor?: TypedPropertyDescriptor<any>,
+  ): void {
+    /**
+     * Означает, что данный метод уже обёрнут
+     */
+    if (TraceInjector.isWrapped(original) || TraceInjector.nowSpan(original)) {
+      return;
+    }
+
+    logger.trace(`Wrapping method: ${cls.constructor.name}.${original.name}()`);
+
+    const spanName = TraceInjector.createSpanName(cls, original.name);
+    const wrapped = TraceInjector.createWrapper(original, spanName);
+
+    redecorate(original, wrapped);
+
+    if (descriptor) {
+      descriptor.value = wrapped;
+    } else {
+      cls[original.name] = wrapped;
+    }
+
+    /**
+     * Отмечает метод, как обёрнутый (чтобы избежать повторного оборачивания)
+     */
+    TraceInjector.setWrapped(wrapped);
+  }
+
+  // TODO: Maybe move to standalone function, because it's
+  // the only public function except for the main one
+  static 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_BYTES
+        ? serialized
+        : `data exceeds limit of ${MAX_BYTES} bytes`;
+    }
+
+    return 'data is undefined';
+  }
+
+  private static createWrapper(original: any, spanName: string): any {
+    return {
+      [original.name](...args: any[]): any {
+        const tracer = trace.getTracer('@rsdk/open-telemetry', '1.0.0');
+
+        return tracer.startActiveSpan(spanName, (span) => {
+          try {
+            logger.trace(`Wrapped function invoked: ${original.name}`);
+
+            const result = original.apply(this, args);
+
+            /**
+             * If function returns promise:
+             * - errors won't be caught with try-catch
+             * - enriching span should be don when promise is resolved
+             *
+             * That's why this extra branch exists
+             */
+            if (result instanceof Promise) {
+              return result
+                .then((result: unknown) => TraceInjector.enrich(span, result))
+                .catch((error: unknown) =>
+                  TraceInjector.recordAndRethrow(error, span),
+                )
+                .finally(() => span.end());
+            }
+
+            TraceInjector.enrich(span, result);
+            span.end();
+
+            return result;
+          } catch (error) {
+            TraceInjector.recordAndRethrow(error, span);
+            span.end();
+          }
+        });
+      },
+    }[original.name];
+  }
+
+  private static createSpanName(cls: object, methodName: string): string {
+    return `${cls.constructor.name} -> ${methodName}`;
+  }
+
+  private static isWrapped(prototype: object): boolean {
+    assert.ok(prototype);
+
+    return Reflect.hasMetadata(Constants.TRACE_METADATA_ACTIVE, prototype);
+  }
+
+  private static nowSpan(prototype: object): boolean {
+    assert.ok(prototype);
+
+    return Reflect.hasMetadata(Constants.NO_SPAN_METADATA, prototype);
+  }
+
+  private static setWrapped(prototype: object): void {
+    assert.ok(prototype);
+
+    // Value doesn't matter
+    const NOOP = 1;
+
+    Reflect.defineMetadata(Constants.TRACE_METADATA_ACTIVE, NOOP, prototype);
+  }
+
+  private static recordAndRethrow(error: unknown, span: Span): void {
+    span.recordException(error as ErrorLike);
+    span.setStatus({
+      code: SpanStatusCode.ERROR,
+      message: (error as ErrorLike).message,
+    });
+
+    throw error;
+  }
+
+  private static enrich(span: Span, data: unknown): unknown {
+    span.setAttribute('response', TraceInjector.toAttribute(data));
+    span.setStatus({ code: SpanStatusCode.OK });
+
+    return data;
+  }
+}

package/src/tracing/tracing.config.ts

@@ -0,0 +1,22 @@
+import {
+  BoolParser,
+  Config,
+  ConfigSection,
+  Property,
+  UrlParser,
+} from '../config';
+
+@ConfigSection()
+export class TracingModuleConfig extends Config {
+  @Property('TRACING_ENABLED', new BoolParser(), {
+    defaultValue: false,
+    description: 'Enable application tracing',
+  })
+  enabled!: boolean;
+
+  @Property('TRACING_COLLECTOR_URL', new UrlParser(), {
+    defaultValue: new URL('http://localhost:4318/v1/traces'),
+    description: 'Url to jaeger/zipkin/otlp collector etc.',
+  })
+  collectorUrl!: URL;
+}

package/src/tracing/tracing.module.ts

@@ -0,0 +1,120 @@
+import type { DynamicModule, Provider } from '@nestjs/common';
+import { Module } from '@nestjs/common';
+import { context, trace } from '@opentelemetry/api';
+import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
+import { CompositePropagator } from '@opentelemetry/core';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { B3InjectEncoding, B3Propagator } from '@opentelemetry/propagator-b3';
+import { Resource } from '@opentelemetry/resources';
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import type { SpanExporter } from '@opentelemetry/sdk-trace-base';
+import {
+  BatchSpanProcessor,
+  SimpleSpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
+import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
+import { ILogger, LoggerFactory } from '@rsdk/logging';
+
+import { PlatformConfigModule } from '../config';
+import { InjectLogger } from '../logging';
+
+import { InstrumentationService } from './services/instrumentation.service';
+import { ExtendedMetadataScanner } from './services/metadata.scanner';
+import { autoInstumentationOptions } from './auto-instrumentations.config';
+import { TracingModuleConfig } from './tracing.config';
+
+export interface TracingModuleOptions {
+  appName: string;
+  processing: 'simple' | 'batch';
+  exporter?: SpanExporter;
+}
+
+@Module({})
+export class TracingModule {
+  constructor(
+    @InjectLogger(TracingModule) private readonly logger: ILogger,
+    private readonly instrumentations: InstrumentationService,
+    private readonly sdk: NodeSDK,
+    private readonly config: TracingModuleConfig,
+  ) {}
+
+  static forRoot(options: TracingModuleOptions): DynamicModule {
+    return {
+      module: TracingModule,
+
+      imports: [PlatformConfigModule.forFeature(TracingModuleConfig)],
+      providers: [
+        ExtendedMetadataScanner,
+        InstrumentationService,
+        this.createSDKProvider(options),
+      ],
+    };
+  }
+
+  private static createSDKProvider(options: TracingModuleOptions): Provider {
+    return {
+      provide: NodeSDK,
+
+      inject: [TracingModuleConfig],
+      useFactory: (config: TracingModuleConfig): NodeSDK => {
+        const exporter =
+          options.exporter ||
+          new OTLPTraceExporter({
+            url: config.collectorUrl?.toString(),
+          });
+
+        const processor =
+          options.processing === 'simple'
+            ? new SimpleSpanProcessor(exporter)
+            : new BatchSpanProcessor(exporter);
+
+        return new NodeSDK({
+          autoDetectResources: true,
+          contextManager: new AsyncLocalStorageContextManager(),
+          instrumentations: [autoInstumentationOptions],
+          resource: new Resource({
+            [SemanticResourceAttributes.SERVICE_NAME]: options.appName,
+          }),
+          spanProcessor: processor,
+          textMapPropagator: new CompositePropagator({
+            propagators: [
+              new B3Propagator(),
+              new B3Propagator({
+                injectEncoding: B3InjectEncoding.MULTI_HEADER,
+              }),
+            ],
+          }),
+        });
+      },
+    };
+  }
+
+  // Можно добавить включение и выключение при изменении конфига.
+  async onModuleInit(): Promise<void> {
+    if (!this.config.enabled) {
+      this.logger.info('Tracing is disabled');
+
+      return;
+    }
+
+    this.logger.info('Tracing is enabled');
+
+    this.logger.debug('Starting Open Telemetry SDK...');
+    await this.sdk.start();
+
+    this.logger.debug('Instrumenting nest.js entities...');
+    this.instrumentations.inject();
+
+    this.logger.debug('Attaching log messages to spans...');
+    LoggerFactory.onMessage((level, msg) => {
+      const span = trace.getSpan(context.active());
+
+      span?.addEvent('log', { ...msg, level });
+    });
+  }
+
+  async beforeApplicationShutdown(): Promise<void> {
+    this.logger.info('Shutting down Open Telemetry SDK...');
+    await this.sdk.shutdown();
+  }
+}