@rsdk/core 0.14.0

package/src/config/additional-source/additional-source.initializer.ts

@@ -0,0 +1,165 @@
+import { SELF_DECLARED_DEPS_METADATA } from '@nestjs/common/constants';
+import type { Constructor } from '@rsdk/common';
+
+import { APP_NAME } from '../../app-metadata/app-metadata.const';
+import { NoInitException } from '../../exceptions';
+import { ConfigPropertyMetadataNotFound } from '../exceptions';
+import { isPropertyToken } from '../metadata';
+import type { ConfigSource } from '../sources';
+import { ConfigSourceDIException, isReloadable } from '../sources';
+import type { RawValues } from '../types';
+
+import type { AdditionalSourceOptions } from './additional-source.module';
+
+/**
+ * Содержит логику инициализации дополнительных источников конфигурации
+ */
+export class AdditionalSourceInitializer {
+  /**
+   * Промис, состояние которого отражает состояние инициализации дополнительных источников конфигурации
+   * @private
+   */
+  private initializePromise: Promise<void> | undefined;
+
+  constructor(private options: AdditionalSourceOptions) {}
+
+  /**
+   * Инициализирует дополнительные источники конфигурации
+   * ATTENTION: Можно вызывать сколько угодно раз, однако результат будет идентичным в буквальном смысле,
+   *
+   * AdditionalSourceModuleInitializer.initialize() === AdditionalSourceModuleInitializer.initialize() // true
+   *
+   * Это сделано намеренно из-за того как nestjs работает с разрешением зависимостей, а именно `Promise.all`.
+   * Соответственно провайдеров конфигурации может быть много и всем им необходимо инициализировать
+   * источники, проверка на `isInitialized` очевидно создаёт неразрешимые проблемы из-за асинхронности.
+   */
+  async initialize(): Promise<void> {
+    if (this.initializePromise) {
+      return this.initializePromise;
+    }
+    this.initializePromise = this.initializeAdditionalSources(this.options);
+    return this.initializePromise;
+  }
+
+  /**
+   * Initializing additional configuration sources.
+   * Loading values and merging them into the storage.
+   * NOTE: standalone properties from env can be used to
+   * configure additional sources
+   */
+  private async initializeAdditionalSources(
+    options: AdditionalSourceOptions,
+  ): Promise<void> {
+    if (!options.sources || options.sources.length === 0) {
+      options.logger.info('No additional sources configured');
+      return;
+    }
+    const { sources, events, logger, vars } = options;
+
+    logger.info('Initializing additional configuration sources');
+
+    for (const ctor of sources) {
+      // We should restore the order to initialize for our ctor init later
+      const args = this.getConfigSourceArguments(options, ctor);
+
+      const source = new ctor(...args);
+
+      logger.info('Loading configuration from source', {
+        source: source.name,
+      });
+
+      const loaded = await source.load();
+
+      /**
+       * Loading and merging data into storage
+       */
+      const { updatedKeys } = vars.merge(loaded);
+
+      if (updatedKeys.length > 0) {
+        logger.warn(`${updatedKeys.length} values overwritten`, {
+          keys: updatedKeys,
+          source: source.name,
+        });
+      }
+
+      /**
+       * In case the source is reloadable we subscribe to it's
+       * 'reload' event
+       */
+      if (isReloadable(source)) {
+        logger.info('Setting up configuration reload', {
+          source: source.name,
+        });
+
+        source.init();
+      }
+    }
+
+    events.on('reload', (source: ConfigSource, newValues: RawValues) => {
+      const { createdKeys, updatedKeys } = vars.merge(newValues);
+      if (createdKeys.length > 0 || updatedKeys.length > 0) {
+        events.emit('merge', source, {
+          createdKeys,
+          updatedKeys,
+        });
+      }
+    });
+
+    logger.info('Additional sources initialized successfully');
+  }
+
+  /**
+   * Returns the arguments for creating the `ConfigSource` instance
+   * @param options
+   * @param ctor
+   * @private
+   */
+  private getConfigSourceArguments(
+    options: AdditionalSourceOptions,
+    ctor: Constructor<ConfigSource>,
+  ): unknown[] {
+    // Injectable config properties!
+    const metadata = Reflect.getMetadata(SELF_DECLARED_DEPS_METADATA, ctor) as {
+      index: number;
+      param: unknown;
+    }[];
+
+    // No metadata - no args
+    if (!metadata) {
+      return [];
+    }
+
+    const sortedMetadata = [...metadata].sort((a, b) => a.index - b.index);
+
+    const { prefix, propertyMetadata, vars } = options;
+    const injectables = new Map<unknown, unknown>().set(APP_NAME, prefix);
+
+    const args = sortedMetadata.map((x) => {
+      if (injectables.has(x.param)) {
+        return injectables.get(x.param);
+      }
+
+      if (!isPropertyToken(x.param)) {
+        throw new ConfigSourceDIException(ctor, x.param);
+      }
+
+      const propMeta = propertyMetadata.get(x.param);
+      if (!propMeta) {
+        throw new ConfigPropertyMetadataNotFound(x.param);
+      }
+
+      const property = vars.extract(propMeta);
+      if (!property) {
+        throw new NoInitException(
+          'Config property',
+          x.param as string,
+          'You probably should add @DeclareProperty decorator to source class.',
+        );
+      }
+
+      return property;
+    });
+
+    return args;
+  }
+}

package/src/config/additional-source/additional-source.module.ts

@@ -0,0 +1,48 @@
+import type { DynamicModule } from '@nestjs/common';
+import type { Constructor } from '@rsdk/common';
+import type { ILogger } from '@rsdk/logging';
+
+import { ConfigReloadIndicator } from '../config-reload.indicator';
+import type { PropertyToken } from '../metadata';
+import type { ReloadEvents } from '../reload';
+import type { ConfigSource } from '../sources';
+import type { PropertyMetadata } from '../types';
+import type { Vars } from '../vars.class';
+
+import { AdditionalSourceInitializer } from './additional-source.initializer';
+
+/**
+ * Модуль реализующий работу с `AdditionalSource` указанными в конфиге.
+ * Инициализирует все `source` в хуке `onModuleInit`
+ */
+export class AdditionalSourceModule {
+  static forRoot(options: AdditionalSourceOptions): DynamicModule {
+    return {
+      imports: [
+        {
+          global: true,
+          module: AdditionalSourceModule,
+          providers: [
+            {
+              provide: AdditionalSourceInitializer,
+              useValue: new AdditionalSourceInitializer(options),
+            },
+          ],
+          exports: [AdditionalSourceInitializer],
+        },
+      ],
+      providers: [ConfigReloadIndicator],
+      module: AdditionalSourceModule,
+    };
+  }
+}
+
+export interface AdditionalSourceOptions {
+  sources: Constructor<ConfigSource>[] | undefined;
+  logger: ILogger;
+  properties: Map<PropertyToken, unknown>;
+  propertyMetadata: Map<string, PropertyMetadata>;
+  vars: Vars;
+  events: ReloadEvents;
+  prefix: string;
+}

package/src/config/config-reload.indicator.ts

@@ -0,0 +1,36 @@
+import { Injectable } from '@nestjs/common';
+
+import type { CheckDetails, HealthIndicator } from '../health';
+import { CheckResult } from '../health/helpers';
+
+import type { Config } from './config.abstract';
+import { ReloadEvents } from './reload';
+import type { ConfigSource } from './sources';
+
+@Injectable()
+export class ConfigReloadIndicator implements HealthIndicator {
+  private events = ReloadEvents.getInstance();
+  private errors = new Map<ConfigSource | Config, Error>();
+
+  constructor() {
+    this.events
+      .on('reload_failure', (source, err) => this.errors.set(source, err))
+      .on('update_failure', (config, err) => this.errors.set(config, err))
+      .on('reload', (source) => this.errors.delete(source))
+      .on('update', (config) => this.errors.delete(config));
+  }
+
+  async check(): Promise<CheckResult> {
+    if (this.errors.size === 0) {
+      return CheckResult.up({});
+    }
+
+    const details: CheckDetails = {};
+
+    for (const [key, err] of this.errors.entries()) {
+      details[key.constructor.name] = { error: err };
+    }
+
+    return CheckResult.down(details);
+  }
+}

package/src/config/config.abstract.ts

@@ -0,0 +1,70 @@
+import { intersection, isEqual } from 'lodash';
+
+import 'reflect-metadata';
+
+import { CONFIG_METADATA_KEY } from './metadata';
+import { ReloadEvents } from './reload';
+import type { PropertyMetadata, SectionMetadata } from './types';
+import type { Vars } from './vars.class';
+
+/**
+ * It is unconventional to use raw values from process.env or somewhere
+ * else because it will not be autodocumented. Instead developer is strongly
+ * encouraged to extends this abstract class and annotate all fields with
+ * @Property() decorator providing nesessary metadata.
+ */
+export class Config {
+  /**
+   * Keys are prefixed and sources are added.
+   */
+  private readonly propertiesMetadata: Record<string, PropertyMetadata>;
+  private readonly events: ReloadEvents = ReloadEvents.getInstance();
+
+  // TODO: why not to pass this.vars and event emitter?
+  constructor() {
+    const metadata = Reflect.getMetadata(
+      CONFIG_METADATA_KEY,
+      this.constructor,
+    ) as SectionMetadata;
+
+    this.propertiesMetadata = metadata.properties;
+  }
+
+  onUpdate(fn: (keys: string[]) => void): void {
+    this.events.on('update', (_: Config, updatedKeys: string[]) => {
+      const prefixedKeys = Object.keys(this.propertiesMetadata).map(
+        (x) => `${this.constructor.name}/${x}`,
+      );
+      if (intersection(prefixedKeys, updatedKeys).length > 0) {
+        fn(updatedKeys);
+      }
+    });
+  }
+
+  read(vars: Vars): string[] {
+    const updated: string[] = [];
+
+    for (const [prop, metadata] of Object.entries(this.propertiesMetadata)) {
+      const value = (this as any)[prop];
+      const newValue = vars.extract(metadata);
+
+      // FIXME: Doesn't work with object types.
+      if (!isEqual(newValue, value)) {
+        (this as any)[prop] = newValue;
+        updated.push(`${this.constructor.name}/${prop}`);
+      }
+    }
+
+    return updated;
+  }
+
+  tryUpdate(vars: Vars): void {
+    try {
+      const updated = this.read(vars);
+
+      this.events.emit('update', this, updated);
+    } catch (err: any) {
+      this.events.emit('update_failure', this, err);
+    }
+  }
+}

package/src/config/config.module.ts

@@ -0,0 +1,330 @@
+import type { DynamicModule, FactoryProvider, Provider } from '@nestjs/common';
+import { Module } from '@nestjs/common';
+import type { Constructor } from '@rsdk/common';
+import { dotenv } from '@rsdk/common';
+import { LoggerFactory } from '@rsdk/logging';
+
+import { SequenceException } from '../exceptions';
+import type { PlatformOptions } from '../types';
+
+import { AdditionalSourceInitializer } from './additional-source/additional-source.initializer';
+import { AdditionalSourceModule } from './additional-source/additional-source.module';
+import type { Config } from './config.abstract';
+import {
+  ConfigNotBootstrappedException,
+  ConfigPropertyMetadataNotFound,
+} from './exceptions';
+import type { PropertyToken } from './metadata';
+import { ConfigMetadataRegistry, getPropertyToken } from './metadata';
+import { ReloadEvents } from './reload';
+import type { ConfigSource } from './sources';
+import type { ConfigValue, PropertyMetadata } from './types';
+import { Vars } from './vars.class';
+
+export interface ConfigModuleOptions {
+  /**
+   * By convention every configuration key should have unique prefix
+   * for current service. It is inferred from application name
+   */
+  appName: string;
+
+  /**
+   * Additional asynchronous configuration sources. For example a source
+   * that loads configuration from Consul or other remote system.
+   */
+  sources?: Constructor<ConfigSource>[];
+}
+
+/**
+ * Configuration is loaded in predictable order. You should take
+ * into account chat all repeating keys will be overwritten on each step:
+ *
+ * 1. .env file if there is any
+ * 2. process environment
+ * 3. динамические source'ы (если сделать последовательно - то в порядке указания)
+ */
+
+@Module({})
+export class PlatformConfigModule {
+  private static isBootstrapped = false;
+  private static events = ReloadEvents.getInstance();
+  private static vars: Vars;
+  private static prefix: string;
+  /**
+   * Проинициализированные секции конфигов
+   * @private
+   */
+  private static initializedConfigs = new Map<Constructor<Config>, Config>();
+  /**
+   * undefined является валидным значением по умолчанию (`defaultValue`)
+   * @private
+   */
+  private static properties = new Map<PropertyToken, ConfigValue | undefined>();
+
+  /**
+   * We don't use class as context here because it is undefined if
+   * tsc target is ES2022
+   */
+  private static logger = LoggerFactory.create('PlatformConfigModule');
+
+  /**
+   * Метадата о необходимых приложению значениях конфигурации
+   * Зачем храним?
+   * Потому что пайплайн такой:
+   * 1. Собираем данные о том какие поля нам нужны
+   * 2. Приложение запрашивает поле из конфигурации
+   * 3. Ищем метаданные
+   * 4. По метаданным вытягиваем значение
+   * 5. Отдаём значение
+   *
+   * Это важно так как позволяет прозрачным образом контролировать этот процесс и инициализировать поля в тот момент когда они потребуются
+   * А не в тот момент когда их объявили
+   * Основной кейс, где это применяется - тесты
+   * @private
+   */
+  private static propertyMetadata = new Map<string, PropertyMetadata>();
+
+  /**
+   * This method should be invoked BEFORE bootstrapping nest application.
+   *
+   * It takes 2 main actions:
+   * - load environment variables
+   *
+   * - instantiates all configuration initializedConfig (classes marked with
+   *   @ConfigSection() decorator) and adds them into internal storage
+   *
+   * If any of these actions fails - application should exit.
+   *
+   * NOTE: This method should be invoked before any other interaction
+   * with ConfigurationModule
+   *
+   * ATTENTION: not load values from additional source
+   */
+  static bootstrap(options?: ConfigModuleOptions): void {
+    if (this.isBootstrapped) {
+      throw new SequenceException("Can't bootstrap ConfigurationModule twice");
+    }
+
+    this.prefix = options?.appName ?? '';
+
+    if (this.prefix) {
+      this.logger.info('Setting configuration keys prefix', {
+        prefix: this.prefix,
+      });
+    }
+
+    this.vars = new Vars(this.prefix);
+
+    this.readEnvironment();
+
+    /**
+     * Reading and validating standalone properties from env.
+     *
+     * NOTE: Splitting extraction if standalone properties into 2 phases
+     * is necessary, some configuration sources can need something
+     * from env to be instatiated.
+     */
+    const { properties } = ConfigMetadataRegistry.getMetadata();
+
+    this.extractStandaloneProperties(properties, 'expectedInEnv');
+
+    /**
+     * NOTE: That properties from .env already loaded.
+     * Now loading ones from other sources
+     */
+    this.extractStandaloneProperties(properties, 'others');
+
+    this.isBootstrapped = true;
+  }
+
+  /**
+   * Use this method to imports specific configuration property
+   * into given module
+   *
+   * @param alias It's not so easy to use plain property key because
+   * of prefix and source key issues. That's why we use aliases. Specify
+   * the same string that was used to define property in
+   * @Property() or @ExtraEnv() decorator.
+   *
+   * @returns DynamicModule
+   */
+  static forProperty(alias: string): DynamicModule {
+    const token = getPropertyToken(alias);
+    const provider = this.getPropertyProvider(token);
+
+    return {
+      module: PlatformConfigModule,
+      providers: [provider],
+      exports: [provider],
+    };
+  }
+
+  /**
+   * Use this method to import specified configuration section
+   * into given module
+   * @param ctor Pass constructor of configuration section class
+   * @returns DynamicModule
+   */
+  static forFeature(ctor: Constructor<Config>): DynamicModule {
+    /**
+     * Factory providers are used because at the point of time when
+     * forFeature() is executed Config instances don't yet exist
+     */
+    const provider: FactoryProvider = {
+      inject: [{ optional: true, token: AdditionalSourceInitializer }],
+      provide: ctor,
+      useFactory: async (
+        additionalSourceModuleInitializer?: AdditionalSourceInitializer,
+      ) => {
+        /**
+         * Да, каждый раз вызываем метод `initialize` более подробно почему так - смотри в `JSDoc` метода
+         */
+        await additionalSourceModuleInitializer?.initialize();
+        return this.resolve(ctor);
+      },
+    };
+
+    return {
+      module: PlatformConfigModule,
+      providers: [provider],
+
+      exports: [provider],
+    };
+  }
+
+  static forRoot(options: PlatformOptions): DynamicModule {
+    const providers: Provider[] = [];
+    const imports: (Promise<DynamicModule> | DynamicModule)[] = [];
+
+    if (options.config?.sources) {
+      imports.push(
+        // TODO: Эти опции в идеале добавить в сам контейнер и использовать их везде
+        AdditionalSourceModule.forRoot({
+          sources: options.config?.sources,
+          logger: this.logger,
+          properties: this.properties,
+          vars: this.vars,
+          events: this.events,
+          prefix: this.prefix,
+          propertyMetadata: this.propertyMetadata,
+        }),
+      );
+    }
+
+    return {
+      imports,
+      module: PlatformConfigModule,
+      providers,
+    };
+  }
+
+  /**
+   * Extracting specific instance of configuration section by
+   * its class reference. Throws error if called before .bootstrap()
+   *
+   * ATTENTION: Конфиг будет разрешен с доступными на данный момент переменными,
+   * то есть если дополнительные источники конфигурации ещё не были проинициализированы,
+   * они не будут учтены в разрешении конфигурации.
+   *
+   * @param ctor Pass constructor of configuration section class
+   * @returns T
+   */
+  static resolve<T extends Config>(ctor: Constructor<T>): T {
+    /**
+     * Автор уверен, что здесь не стоит делать bootstrap так как это разные зоны ответственности
+     */
+    if (!this.isBootstrapped) {
+      throw new ConfigNotBootstrappedException();
+    }
+
+    const instance = this.initializedConfigs.get(ctor);
+    if (!instance) {
+      const instantiateSection = this.instantiateSection(ctor);
+
+      this.initializedConfigs.set(ctor, instantiateSection);
+      return instantiateSection;
+    }
+
+    // We know exactly it is T
+    return instance as T;
+  }
+
+  private static getPropertyProvider(
+    token: `STANDALONE_CONFIG_PROPERTY_${string}`,
+  ): FactoryProvider<ConfigValue | undefined> {
+    return {
+      inject: [{ optional: true, token: AdditionalSourceInitializer }],
+      provide: token,
+      useFactory: async (
+        additionalSourceModuleInitializer?: AdditionalSourceInitializer,
+      ): Promise<ConfigValue | undefined> => {
+        await additionalSourceModuleInitializer?.initialize();
+        if (this.properties.has(token)) {
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          return this.properties.get(token)!;
+        }
+        const propMeta = this.propertyMetadata.get(token);
+        if (!propMeta) {
+          throw new ConfigPropertyMetadataNotFound(token);
+        }
+        const value = this.vars.extract(propMeta);
+
+        this.properties.set(token, value);
+        return value;
+      },
+    };
+  }
+
+  private static readEnvironment(): void {
+    this.logger.info('Loading variables from .env file if exists');
+    dotenv.config();
+
+    this.logger.info('Initializing raw parameters storage');
+
+    /**
+     * Copying parameters from process.env, skipping entries
+     * for which value is undefined (not sure it's possible,
+     * but @types/node says it is).
+     */
+
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== undefined) {
+        this.vars.set(key, value);
+      }
+    }
+  }
+
+  private static extractStandaloneProperties(
+    properties: Map<string, PropertyMetadata>,
+    subset: 'expectedInEnv' | 'others',
+  ): void {
+    for (const [alias, metadata] of properties.entries()) {
+      if (subset === 'expectedInEnv' && !metadata.expectedInEnv) {
+        continue;
+      }
+
+      this.propertyMetadata.set(getPropertyToken(alias), metadata);
+    }
+  }
+
+  /**
+   * Инициализирует инстанс секции конфига
+   * ATTENTION: не проверяет есть ли ещё проинициализированные, будьте внимательны во избежание неожиданного поведение
+   * @param ctor
+   * @private
+   */
+  private static instantiateSection<T extends Config>(ctor: Constructor<T>): T {
+    const instance = new ctor();
+
+    this.logger.debug('Initializing configuration section instance', {
+      ctor: ctor.name,
+    });
+
+    this.events.on('merge', () => {
+      instance.tryUpdate(this.vars);
+    });
+
+    instance.read(this.vars);
+    return instance;
+  }
+}

package/src/config/exceptions/config-not-bootstrapped.exception.ts

@@ -0,0 +1,15 @@
+import { text } from '@rsdk/common';
+
+import { BootstrapException, Exception } from '../../exceptions';
+
+@Exception({
+  description: text`
+    Occures when something is calling PlatformConfigModule functionality
+    when it is not yet bootstrapped.
+  `,
+})
+export class ConfigNotBootstrappedException extends BootstrapException {
+  constructor() {
+    super('Configuration module is not bootstrapped!');
+  }
+}

package/src/config/exceptions/config-property-metadata-not-found.ts

@@ -0,0 +1,9 @@
+import { InternalException } from '../../exceptions';
+
+export class ConfigPropertyMetadataNotFound extends InternalException {
+  constructor(configPropertyToken: string) {
+    super(`Metadata for config property ${configPropertyToken} not found`, {
+      details: configPropertyToken,
+    });
+  }
+}

package/src/config/exceptions/index.ts

@@ -0,0 +1,3 @@
+export * from './config-not-bootstrapped.exception';
+export * from './property.exception';
+export { ConfigPropertyMetadataNotFound } from './config-property-metadata-not-found';

package/src/config/exceptions/property.exception.ts

@@ -0,0 +1,15 @@
+import { PlatformException } from '../../exceptions';
+
+export class PropertyException extends PlatformException {
+  constructor(property: string, msg: string) {
+    super('CONFIG:PROPERTY', msg, {
+      details: {
+        property,
+      },
+    });
+  }
+
+  static fromError(err: any, key: string): PropertyException {
+    return new PropertyException(key, err.message || 'UNKNOWN ERROR');
+  }
+}