@rsdk/core 0.14.0

package/src/logging/logging.module.ts

@@ -0,0 +1,48 @@
+/* eslint-disable sort-keys */
+
+import type { DynamicModule, Provider } from '@nestjs/common';
+import { Module } from '@nestjs/common';
+import type { Constructor } from '@rsdk/common';
+import { LoggerFactory } from '@rsdk/logging';
+
+import { PlatformConfigModule } from '../config';
+
+import { LoggingConfig } from './logging.config';
+
+@Module({})
+export class LoggingModule {
+  private static providers = new Map<string, Provider>();
+  private static logger = LoggerFactory.create('LoggingModule');
+
+  constructor(config: LoggingConfig) {
+    const cfg = (): void => {
+      LoggingModule.logger.info(`Setting log level: <${config.level}>`, {
+        logLevel: config.level,
+      });
+
+      LoggerFactory.reconfigure(config);
+    };
+
+    config.onUpdate(cfg);
+    cfg();
+  }
+
+  static register(context: string | Constructor, token: string): void {
+    this.providers.set(token, {
+      provide: token,
+      useValue: LoggerFactory.create(context),
+    });
+  }
+
+  static forRoot(): DynamicModule {
+    const providers = [...this.providers.values()];
+
+    return {
+      module: LoggingModule,
+      imports: [PlatformConfigModule.forFeature(LoggingConfig)],
+      exports: providers,
+      providers: providers,
+      global: true,
+    };
+  }
+}

package/src/logging/types.ts

@@ -0,0 +1,3 @@
+import type { Provider } from '@nestjs/common';
+
+export type InstancesRegistry = Map<string, Provider>;

package/src/manifest/manifest.ts

@@ -0,0 +1,23 @@
+import { join } from 'path';
+import { cwd } from 'process';
+
+import { assertAppName } from '../app-metadata';
+import type { ManifestData } from '../types';
+
+/**
+ * Утилитарный класс для вывода данных из `package.json`
+ */
+export class Manifest {
+  static getData(manifestPath?: string): ManifestData {
+    /**
+     * Reading and validating metadata from package.json
+     */
+    const path = manifestPath || join(cwd(), 'package.json');
+
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { name, description, version } = require(path) as ManifestData;
+
+    assertAppName(name);
+    return { name, description, version };
+  }
+}

package/src/metrics/index.ts

@@ -0,0 +1,4 @@
+export { Counter, Gauge, Histogram, Summary, register } from 'prom-client';
+export * from './metrics.module';
+export * from './types';
+export * from './metadata';

package/src/metrics/metadata/decorators/index.ts

@@ -0,0 +1 @@
+export * from './metric.decorator';

package/src/metrics/metadata/decorators/metric.decorator.ts

@@ -0,0 +1,45 @@
+/* eslint-disable @typescript-eslint/ban-types */
+import type { Constructor } from '@rsdk/common';
+
+import type {
+  CounterMetadata,
+  GaugeMetadata,
+  HistogramMetadata,
+  MetricMetadata,
+  OmitType,
+  SummaryMetadata,
+} from '../../types';
+import { MetricsRegistry } from '../metrics.registry';
+
+/**
+ * Registers metric's metadata, which allows
+ * MetricsModule to instantiate it and export as
+ * a provider
+ *
+ * @param type type of metric
+ * @param metadata respective metadata
+ */
+export function Metric(
+  type: 'counter',
+  metadata: OmitType<CounterMetadata>,
+): ClassDecorator;
+export function Metric(
+  type: 'gauge',
+  metadata: OmitType<GaugeMetadata>,
+): ClassDecorator;
+export function Metric(
+  type: 'histogram',
+  metadata: OmitType<HistogramMetadata>,
+): ClassDecorator;
+export function Metric(
+  type: 'summary',
+  metadata: OmitType<SummaryMetadata>,
+): ClassDecorator;
+export function Metric(
+  type: 'counter' | 'gauge' | 'histogram' | 'summary',
+  metadata: OmitType<MetricMetadata>,
+): ClassDecorator {
+  return function (target: Function): void {
+    MetricsRegistry.register(target as Constructor, { ...metadata, type });
+  };
+}

package/src/metrics/metadata/index.ts

@@ -0,0 +1,2 @@
+export * from './metrics.registry';
+export * from './decorators';

package/src/metrics/metadata/metrics.registry.ts

@@ -0,0 +1,35 @@
+import type { Constructor } from '@rsdk/common';
+
+import { DoubleInitException, NoInitException } from '../../exceptions';
+import type { AnyMetric, MetricMetadata } from '../types';
+
+// separate class because we don't want to expose this
+export class MetricsRegistry {
+  private static metadata = new Map<Constructor<AnyMetric>, MetricMetadata>();
+
+  static register(
+    target: Constructor<AnyMetric>,
+    metric: MetricMetadata,
+  ): void {
+    if (this.metadata.has(target)) {
+      throw new DoubleInitException('Metric', target.name);
+    }
+
+    this.metadata.set(target, metric);
+  }
+
+  static getOne(ctor: Constructor<AnyMetric>): Readonly<MetricMetadata> {
+    const metadata = this.metadata.get(ctor);
+    if (!metadata) {
+      throw new NoInitException('Metric', ctor.name);
+    }
+
+    return metadata;
+  }
+
+  static getAll(): Readonly<Map<Constructor<AnyMetric>, MetricMetadata>> {
+    return this.metadata;
+  }
+
+  // TODO Metadata for autodoc
+}

package/src/metrics/metrics.config.ts

@@ -0,0 +1,16 @@
+import { BoolParser, Config, ConfigSection, Property } from '../config';
+
+@ConfigSection({ name: 'Metrics configuration' })
+export class MetricsModuleConfig extends Config {
+  @Property('METRICS_ENABLED', new BoolParser(), {
+    defaultValue: true,
+    description: 'Enables or disables metrics all together',
+  })
+  isEnabled!: boolean;
+
+  @Property('METRICS_INCLUDE_DEFAULT', new BoolParser(), {
+    defaultValue: true,
+    description: 'Indicates that default Node.js metrics should be included',
+  })
+  includeDefault!: boolean;
+}

package/src/metrics/metrics.module.ts

@@ -0,0 +1,100 @@
+import type {
+  DynamicModule,
+  OnApplicationBootstrap,
+  Provider,
+} from '@nestjs/common';
+import { Module } from '@nestjs/common';
+import type { Constructor } from '@rsdk/common';
+import client from 'prom-client';
+
+import { PlatformConfigModule } from '../config';
+
+import { MetricsRegistry } from './metadata';
+import { MetricsModuleConfig } from './metrics.config';
+import type { AnyMetric, MetricsModuleOptions } from './types';
+
+/**
+ * Metrics module exposes metrics interface (depending on transport)
+ * and gives convenient ways to register and inject custom prom-client
+ * metrics.
+ *
+ * @willsoto/nestjs-prometheus was an alternative, but it didn't really
+ * fit
+ */
+@Module({
+  imports: [PlatformConfigModule.forFeature(MetricsModuleConfig)],
+})
+export class MetricsModule implements OnApplicationBootstrap {
+  private static isBootstrapped = false;
+  private static metrics = new Map<Constructor<AnyMetric>, Provider>();
+
+  constructor(private readonly config: MetricsModuleConfig) {}
+
+  /**
+   * Adds metrics controller provided as options
+   *
+   * @returns dynamic module
+   */
+  static forRoot(options: MetricsModuleOptions): DynamicModule {
+    return {
+      controllers: [...options.controllers],
+      module: MetricsModule,
+    };
+  }
+
+  /**
+   * Use this to inject specified metric into target module
+   *
+   * @param other Not empty List of metric classes
+   * @returns dynamic module
+   */
+  static forFeature(
+    first: Constructor<AnyMetric>,
+    ...other: Constructor<AnyMetric>[]
+  ): DynamicModule {
+    const providers: Provider[] = [];
+
+    for (const ctor of [first, ...other]) {
+      const existing = this.metrics.get(ctor);
+
+      if (existing) {
+        providers.push(existing);
+
+        continue;
+      }
+
+      const metadata = MetricsRegistry.getOne(ctor);
+
+      providers.push({
+        provide: ctor,
+        useValue: new ctor(metadata),
+      });
+    }
+
+    return {
+      module: MetricsModule,
+
+      exports: providers,
+      providers,
+    };
+  }
+
+  /**
+   * Configures prom-client
+   */
+  onApplicationBootstrap(): void {
+    /**
+     * This module initializes many times: forRoot, forFeature
+     * but real prom-client should occur only once.
+     */
+    if (MetricsModule.isBootstrapped) {
+      return;
+    }
+
+    if (this.config.includeDefault) {
+      client.collectDefaultMetrics();
+    }
+
+    MetricsModule.isBootstrapped = true;
+  }
+}

package/src/metrics/types.ts

@@ -0,0 +1,39 @@
+import type { Controller } from '@nestjs/common/interfaces';
+import type { Constructor } from '@rsdk/common';
+import type {
+  CounterConfiguration,
+  GaugeConfiguration,
+  HistogramConfiguration,
+  SummaryConfiguration,
+} from 'prom-client';
+
+export { Metric as AnyMetric } from 'prom-client';
+
+export interface MetricsModuleOptions {
+  controllers: Constructor<Controller>[];
+}
+
+export interface MetricMetadata {
+  name: string;
+  type: 'counter' | 'gauge' | 'histogram' | 'summary';
+  description?: string;
+}
+
+export type OmitType<T extends MetricMetadata> = Omit<T, 'type'>;
+
+export type CounterMetadata = CounterConfiguration<string> & MetricMetadata;
+export const isCounterMetadata = (x: MetricMetadata): x is CounterMetadata =>
+  x.type === 'counter';
+
+export type GaugeMetadata = GaugeConfiguration<string> & MetricMetadata;
+export const isGaugeMetadata = (x: MetricMetadata): x is GaugeMetadata =>
+  x.type === 'gauge';
+
+export type HistogramMetadata = HistogramConfiguration<string> & MetricMetadata;
+export const isHistogramMetadata = (
+  x: MetricMetadata,
+): x is HistogramMetadata => x.type === 'histogram';
+
+export type SummaryMetadata = SummaryConfiguration<string> & MetricMetadata;
+export const isSummaryMetadata = (x: MetricMetadata): x is SummaryMetadata =>
+  x.type === 'summary';

package/src/noop.http-adapter.ts

@@ -0,0 +1,126 @@
+/* eslint-disable @typescript-eslint/ban-types */
+import { AbstractHttpAdapter } from '@nestjs/core';
+
+import { NoHttpException } from './exceptions';
+
+// Just do nothing
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+const noop = (): void => {};
+
+export class NoopHttpAdapter<T> extends AbstractHttpAdapter<T> {
+  override get(): void {
+    throw new NoHttpException();
+  }
+
+  override post(): void {
+    throw new NoHttpException();
+  }
+
+  override put(): void {
+    throw new NoHttpException();
+  }
+
+  override patch(): void {
+    throw new NoHttpException();
+  }
+
+  override head(): void {
+    throw new NoHttpException();
+  }
+
+  override delete(): void {
+    throw new NoHttpException();
+  }
+
+  override all(): void {
+    throw new NoHttpException();
+  }
+
+  override use(): void {
+    throw new NoHttpException();
+  }
+
+  close(): any {
+    noop();
+  }
+
+  initHttpServer(): any {
+    noop();
+  }
+
+  useStaticAssets(): any {
+    noop();
+  }
+
+  setViewEngine(): any {
+    noop();
+  }
+
+  getRequestHostname(): any {
+    noop();
+  }
+
+  getRequestMethod(): any {
+    noop();
+  }
+
+  getRequestUrl(): any {
+    noop();
+  }
+
+  status(): any {
+    noop();
+  }
+
+  reply(): any {
+    noop();
+  }
+
+  end(): any {
+    noop();
+  }
+
+  render(): any {
+    noop();
+  }
+
+  redirect(): any {
+    noop();
+  }
+
+  setErrorHandler(): any {
+    noop();
+  }
+
+  setNotFoundHandler(): any {
+    noop();
+  }
+
+  isHeadersSent(): any {
+    noop();
+  }
+
+  setHeader(): any {
+    noop();
+  }
+
+  registerParserMiddleware(): any {
+    noop();
+  }
+
+  enableCors(): any {
+    noop();
+  }
+
+  createMiddlewareFactory(): (path: string, callback: Function) => any {
+    return noop;
+  }
+
+  getType(): string {
+    return 'noop';
+  }
+
+  applyVersionFilter(): (req: any, res: any, next: () => void) => Function {
+    return () => noop;
+  }
+}

package/src/platform.context.ts

@@ -0,0 +1,214 @@
+import type { DynamicModule, INestMicroservice } from '@nestjs/common';
+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 { LoggerFactory } from '@rsdk/logging';
+import { groupBy, intersection } from 'lodash';
+
+import { Manifest } from './manifest/manifest';
+import { ConfigMetadataRegistry, PlatformConfigModule } from './config';
+import {
+  DuplicateProtocolException,
+  NoMatchingTransportException,
+} from './exceptions';
+import { NestLoggerAdapter } from './logging';
+import { NoopHttpAdapter } from './noop.http-adapter';
+import { PlatformModule } from './platform.module';
+import type {
+  IHttpTransport,
+  IMicroserviceTransport,
+  PlatformAppMetadata,
+  PlatformExtendedOptions,
+  PlatformOptions,
+} from './types';
+import {
+  hasSpecifiedTransports,
+  isHttpTransport,
+  isMicroserviceTransport,
+  serializePropertyMetadata,
+  transformSectionMetadata,
+} from './types';
+
+/**
+ * Агрегат для хранения опций приложения, а также методы для конфигурации и запуска приложения
+ */
+export class PlatformContext {
+  readonly logger = LoggerFactory.create('App');
+  readonly root: DynamicModule;
+
+  private microservices: Map<INestMicroservice, IMicroserviceTransport>;
+  private readonly httpTransport: IHttpTransport | undefined;
+  private readonly httpAdapter: AbstractHttpAdapter;
+  private readonly extendedOptions: PlatformExtendedOptions;
+
+  /**
+   * Создаёт контекст проводя базовые проверки
+   * - все транспорты совместимы между собой
+   * - подключенные плагины могут работать с таким набором транспортов
+   *
+   * А также инициализирует конфигурацию согласно требованиям платформы
+   * @param options
+   */
+  constructor(readonly options: PlatformOptions) {
+    PlatformContext.assertTransportCompatability(options);
+    PlatformContext.assertPluginCompatability(options);
+
+    const { name, description, version } = Manifest.getData(
+      options.manifestPath,
+    );
+
+    const extendedOptions: PlatformExtendedOptions = {
+      description,
+      name,
+      version,
+      ...options,
+    };
+
+    this.extendedOptions = extendedOptions;
+
+    PlatformConfigModule.bootstrap({
+      ...(extendedOptions.config ?? {}),
+      appName: extendedOptions.name,
+    });
+    this.httpTransport = options.transports?.find?.(isHttpTransport);
+    this.httpAdapter =
+      this.httpTransport?.getAdapter() ?? new NoopHttpAdapter();
+
+    this.root = PlatformModule.forRoot(this.extendedOptions);
+  }
+
+  private static assertPluginCompatability(options: PlatformOptions): void {
+    if (!options.plugins) {
+      return;
+    }
+    const protocols = (options.transports ?? []).map((x) => x.getProtocol());
+
+    for (const plugin of options.plugins) {
+      if (!hasSpecifiedTransports(plugin)) {
+        continue;
+      }
+
+      if (intersection(plugin.forTransports(), protocols).length === 0) {
+        throw new NoMatchingTransportException(plugin);
+      }
+    }
+  }
+
+  private static assertTransportCompatability(options: PlatformOptions): void {
+    const grouped = groupBy(options.transports, (x) => x.getProtocol());
+
+    for (const [protocol, implementations] of Object.entries(grouped)) {
+      if (implementations.length > 1) {
+        throw new DuplicateProtocolException(protocol, implementations.length);
+      }
+    }
+  }
+
+  /**
+   * Get all important information about PlatformApp instance
+   * @returns Readonly metadata
+   */
+  getMetadata(): Readonly<PlatformAppMetadata> {
+    const confMetadata = ConfigMetadataRegistry.getMetadata();
+    const options = this.extendedOptions;
+    const protocols = (options?.transports ?? []).map((x) => x.getProtocol());
+
+    return {
+      name: options.name,
+
+      description: options.description,
+      protocols: protocols,
+
+      config: {
+        prefix: options.name,
+        sections: [...confMetadata.sections.values()].map(
+          transformSectionMetadata,
+        ),
+        sources: [...confMetadata.sources.values()],
+
+        properties: [...confMetadata.properties.values()].map(
+          serializePropertyMetadata,
+        ),
+      },
+    };
+  }
+
+  /**
+   * Сделано прежде всего для совместимости с тестами.
+   * Производит все необходимые проверки и инициализации транспортов, не запускает приложение
+   */
+  async configureApp(app: INestApplication): Promise<void> {
+    const awaiter = this.httpTransport?.configure(app);
+    if (awaiter instanceof Promise) {
+      await awaiter;
+    }
+
+    app.enableShutdownHooks();
+
+    this.microservices = new Map<INestMicroservice, IMicroserviceTransport>();
+
+    const transports = this.options.transports ?? ([] as any[]);
+
+    for (const transport of transports.filter(isMicroserviceTransport)) {
+      transport.init();
+
+      const options = transport.createMicroserviceOptions();
+      const microservice = app.connectMicroservice(options, {
+        inheritAppConfig: true,
+      });
+
+      this.microservices.set(microservice, transport);
+    }
+  }
+
+  /**
+   * Сделано прежде всего для совместимости с тестами
+   * @param app просто запускает приложение (не применяет никакую конфигурацию)
+   */
+  async runConfiguredApplication(app: INestApplication): Promise<void> {
+    try {
+      this.logger.info('Mapping controllers...');
+      if (this.httpTransport) {
+        const { host, port } = this.httpTransport.createHttpOptions();
+
+        await app.listen(port, host, () =>
+          this.logger.info(`Http server started on ${host}:${port}`),
+        );
+      } else {
+        await app.init();
+      }
+
+      if (this.microservices.size > 0) {
+        for (const [microservice, transport] of this.microservices) {
+          await microservice.listen();
+          transport.onStart();
+        }
+      }
+    } catch (err) {
+      this.logger.fatal(err as Error);
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Возвращает аргументы для `createNestApplication`.
+   * Немедленно возникает вопрос, а почему бы не просто `createNestApplication`
+   * Ответ: Потому что как минимум в тестах приложение создаётся хитрым способом не поддающемуся логике с точки зрения последовательности решений
+   *
+   * testingModuleRef.createApplication(...context.getNestFactoryCreateOptions())
+   * NestFactory.create(context.root, ...context.getNestFactoryCreateOptions())
+   */
+  getNestFactoryCreateOptions(): [
+    httpAdapter: AbstractHttpAdapter,
+    options?: NestApplicationOptions,
+  ] {
+    return [
+      this.httpAdapter,
+      {
+        // Leave body parser configuration to httpTransport implementation
+        bodyParser: false,
+        logger: new NestLoggerAdapter(this.logger),
+      },
+    ];
+  }
+}