@rsdk/core 1.0.12 → 2.0.0

package/src/config/context/config.context.ts

@@ -0,0 +1,209 @@
+/**
+ * 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'ы (если сделать последовательно - то в порядке указания)
+ */
+import type { Constructor } from '@rsdk/common';
+import { dotenv } from '@rsdk/common';
+import { LoggerFactory } from '@rsdk/logging';
+import type { RsdkMetadataProvider } from '@rsdk/metadata';
+
+import type { Config } from '../config.abstract';
+import type { ConfigModuleOptions } from '../config.module';
+import { ConfigPropertyMetadataNotFound } from '../exceptions';
+import type { PropertyToken } from '../metadata';
+import { getPropertyToken } from '../metadata';
+import { ConfigMetadataProvider } from '../metadata/config-metadata.provider';
+import { ReloadEvents } from '../reload';
+import type { ConfigValue, PropertyMetadata } from '../types';
+import { Vars } from '../vars.class';
+
+export class ConfigContext {
+  readonly events = new ReloadEvents();
+  readonly vars: Vars;
+  readonly prefix: string;
+
+  /**
+   * Метадата о необходимых приложению значениях конфигурации
+   * Зачем храним?
+   * Потому что пайплайн такой:
+   * 1. Собираем данные о том какие поля нам нужны
+   * 2. Приложение запрашивает поле из конфигурации
+   * 3. Ищем метаданные
+   * 4. По метаданным вытягиваем значение
+   * 5. Отдаём значение
+
+   *
+   * Это важно так как позволяет прозрачным образом контролировать этот процесс и инициализировать поля в тот момент когда они потребуются
+   * А не в тот момент когда их объявили
+   * Основной кейс, где это применяется - тесты
+   * @private
+   */
+  readonly standalonePropertyMetadata = new Map<string, PropertyMetadata>();
+
+  /**
+   * Проинициализированные секции конфигов
+   * @private
+   */
+  private readonly initializedConfigs = new Map<Constructor<Config>, Config>();
+  /**
+   * undefined является валидным значением по умолчанию (`defaultValue`)
+   * @private
+   */
+  private readonly properties = new Map<
+    PropertyToken,
+    ConfigValue | undefined
+  >();
+
+  /**
+   * We don't use class as context here because it is undefined if
+   * tsc target is ES2022
+   */
+  private readonly logger = LoggerFactory.create('PlatformConfigModule');
+
+  constructor(
+    rsdkMetadataProvider: RsdkMetadataProvider,
+    options?: ConfigModuleOptions,
+  ) {
+    /**
+     * Should be invoked BEFORE bootstrapping nest application.
+     *
+     * It takes 2 main actions:
+     * - load environment variables
+     *
+     * - initialize storage from options and rsdkMetadataProvider
+     *
+     * If any of these actions fails - application should exit.
+     *
+     * ATTENTION: not load values from additional source
+     */
+    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();
+
+    const properties = new ConfigMetadataProvider(
+      rsdkMetadataProvider,
+    ).getPropertiesMap();
+
+    /**
+     * 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.
+     */
+
+    this.extractStandaloneProperties(properties, 'expectedInEnv');
+
+    /**
+     * NOTE: That properties from .env already loaded.
+     * Now loading ones from other sources
+     */
+    this.extractStandaloneProperties(properties, 'others');
+  }
+
+  /**
+   * 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
+   */
+  resolve<T extends Config>(ctor: Constructor<T>): T {
+    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;
+  }
+
+  resolveProperty(
+    token: `STANDALONE_CONFIG_PROPERTY_${string}`,
+  ): ConfigValue | undefined {
+    if (this.properties.has(token)) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      return this.properties.get(token)!;
+    }
+    const propMeta = this.standalonePropertyMetadata.get(token);
+    if (!propMeta) {
+      throw new ConfigPropertyMetadataNotFound(token);
+    }
+    const value = this.vars.extract(propMeta);
+
+    this.properties.set(token, value);
+    return value;
+  }
+
+  private 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 extractStandaloneProperties(
+    properties: Map<string, PropertyMetadata>,
+    subset: 'expectedInEnv' | 'others',
+  ): void {
+    for (const [alias, metadata] of properties.entries()) {
+      if (subset === 'expectedInEnv' && !metadata.expectedInEnv) {
+        continue;
+      }
+
+      this.standalonePropertyMetadata.set(getPropertyToken(alias), metadata);
+    }
+  }
+
+  /**
+   * Инициализирует инстанс секции конфига
+   * ATTENTION: не проверяет есть ли ещё проинициализированные, будьте внимательны во избежание неожиданного поведение
+   * @param ctor
+   * @private
+   */
+  private instantiateSection<T extends Config>(ctor: Constructor<T>): T {
+    const instance = new ctor(this.events);
+
+    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/context/module.ts

@@ -0,0 +1,25 @@
+import type { DynamicModule } from '@nestjs/common';
+
+import { ReloadEvents } from '../reload';
+
+import { ConfigContext } from './config.context';
+
+export class ConfigContextModule {
+  static forRoot(configContext: ConfigContext): DynamicModule {
+    return {
+      global: true,
+      module: ConfigContextModule,
+      providers: [
+        {
+          provide: ConfigContext,
+          useValue: configContext,
+        },
+        {
+          provide: ReloadEvents,
+          useValue: configContext.events,
+        },
+      ],
+      exports: [ConfigContext],
+    };
+  }
+}

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

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

package/src/config/index.ts

@@ -8,3 +8,4 @@ export * from './reload';
 export { AdditionalSourceModule } from './additional-source/additional-source.module';
 export { AdditionalSourceOptions } from './additional-source/additional-source.module';
 export { ConfigPropertyMetadataNotFound } from './exceptions';
+export { ConfigContext } from './context/config.context';

package/src/config/metadata/config-metadata.provider.ts

@@ -0,0 +1,79 @@
+import type { Constructor } from '@rsdk/common';
+import type { Resource, RsdkMetadataProvider } from '@rsdk/metadata';
+
+import type { Config } from '../config.abstract';
+import type { ConfigSource } from '../sources';
+import type {
+  PropertyMetadata,
+  SectionMetadata,
+  SourceMetadata,
+} from '../types';
+
+import {
+  CONFIG_PROPERTIES_RSDK_METADATA_SCOPE,
+  CONFIG_SECTION_RSDK_METADATA_SCOPE,
+  CONFIG_SOURCE_RSDK_METADATA_SCOPE,
+} from './constants';
+import type {
+  PropertyRsdkMetadata,
+  SectionRsdkMetadata,
+  SourcesRsdkMetadata,
+} from './types';
+
+export class ConfigMetadataProvider {
+  constructor(private rsdkMetadataProvider: RsdkMetadataProvider) {}
+
+  getPropertiesMetadata(): Resource<PropertyRsdkMetadata>[] {
+    return this.rsdkMetadataProvider.get<PropertyRsdkMetadata>(
+      CONFIG_PROPERTIES_RSDK_METADATA_SCOPE,
+    );
+  }
+
+  getMetadata(): Readonly<{
+    sources: Map<Constructor<ConfigSource>, SourceMetadata>;
+    sections: Map<Constructor<Config>, SectionMetadata>;
+    properties: Map<string, PropertyMetadata>;
+  }> {
+    return {
+      properties: this.getPropertiesMap(),
+      sections: this.getSectionsMap(),
+      sources: this.getSourcesMap(),
+    };
+  }
+
+  getPropertiesMap(): Map<string, PropertyMetadata> {
+    return new Map(
+      this.getPropertiesMetadata().map(
+        (resource) => [resource.value.alias, resource.value.metadata] as const,
+      ),
+    );
+  }
+
+  getSectionsMap(): Map<Constructor<Config>, SectionMetadata> {
+    return new Map(
+      this.getSectionsMetadata().map(
+        (resource) => [resource.value.target, resource.value.metadata] as const,
+      ),
+    );
+  }
+
+  getSourcesMap(): Map<Constructor<ConfigSource>, SourceMetadata> {
+    return new Map(
+      this.getSourcesMetadata().map(
+        (resource) => [resource.value.target, resource.value.metadata] as const,
+      ),
+    );
+  }
+
+  getSectionsMetadata(): Resource<SectionRsdkMetadata>[] {
+    return this.rsdkMetadataProvider.get<SectionRsdkMetadata>(
+      CONFIG_SECTION_RSDK_METADATA_SCOPE,
+    );
+  }
+
+  private getSourcesMetadata(): Resource<SourcesRsdkMetadata>[] {
+    return this.rsdkMetadataProvider.get<SourcesRsdkMetadata>(
+      CONFIG_SOURCE_RSDK_METADATA_SCOPE,
+    );
+  }
+}

package/src/config/metadata/config-metadata.registry.ts

@@ -1,6 +1,7 @@
 import type { Constructor } from '@rsdk/common';
+import { RsdkMetadata } from '@rsdk/metadata';
 
-import { IndicatorsRegistry } from '../../health/metadata';
+import { IndicatorsRegistry } from '../../health/metadata/indicators.registry';
 import type { Config } from '../config.abstract';
 import { ConfigReloadIndicator } from '../config-reload.indicator';
 import type { ConfigSource } from '../sources';
@@ -11,66 +12,60 @@ import type {
 } from '../types';
 
 import {
-  DuplicatePropertyException,
-  DuplicateSectionException,
-  DuplicateSourceException,
-} from './exceptions';
+  CONFIG_PROPERTIES_RSDK_METADATA_SCOPE,
+  CONFIG_SECTION_RSDK_METADATA_SCOPE,
+  CONFIG_SOURCE_RSDK_METADATA_SCOPE,
+} from './constants';
+import type {
+  PropertyRsdkMetadata,
+  SectionRsdkMetadata,
+  SourcesRsdkMetadata,
+} from './types';
 
 export class ConfigMetadataRegistry {
-  private static properties = new Map<string, PropertyMetadata>();
-  private static sources = new Map<Constructor<ConfigSource>, SourceMetadata>();
-  private static sections = new Map<Constructor<Config>, SectionMetadata>();
-
   static registerSource(
     target: Constructor<ConfigSource>,
     metadata: SourceMetadata,
   ): void {
-    if (this.sources.has(target)) {
-      throw new DuplicateSourceException(target);
-    }
+    RsdkMetadata.setWithScope<SourcesRsdkMetadata>(
+      target,
+      CONFIG_SOURCE_RSDK_METADATA_SCOPE,
+      target,
+      { target, metadata },
+    );
 
-    if (
-      metadata.type === 'reloadable' &&
-      !IndicatorsRegistry.isRegistered(ConfigReloadIndicator)
-    ) {
+    if (metadata.type === 'reloadable') {
       IndicatorsRegistry.register(ConfigReloadIndicator, {
         description: 'Will be "down" if there are problems with config reload',
         key: 'config-reload',
         scope: 'common',
       });
     }
-
-    this.sources.set(target, metadata);
   }
 
   static registerSection(
     target: Constructor<Config>,
     metadata: SectionMetadata,
   ): void {
-    if (this.sections.has(target)) {
-      throw new DuplicateSectionException(target);
-    }
-
-    this.sections.set(target, metadata);
+    RsdkMetadata.setWithScope<SectionRsdkMetadata>(
+      target,
+      CONFIG_SECTION_RSDK_METADATA_SCOPE,
+      target,
+      { target, metadata },
+    );
   }
 
-  static registerProperty(alias: string, metadata: PropertyMetadata): void {
-    if (this.properties.has(alias)) {
-      throw new DuplicatePropertyException(alias);
-    }
-
-    this.properties.set(alias, metadata);
-  }
-
-  static getMetadata(): Readonly<{
-    sources: Map<Constructor<ConfigSource>, SourceMetadata>;
-    sections: Map<Constructor<Config>, SectionMetadata>;
-    properties: Map<string, PropertyMetadata>;
-  }> {
-    return {
-      properties: this.properties,
-      sections: this.sections,
-      sources: this.sources,
-    };
+  static registerProperty(
+    target: object,
+    alias: string,
+    metadata: PropertyMetadata,
+  ): void {
+    RsdkMetadata.setWithScope(
+      target,
+      CONFIG_PROPERTIES_RSDK_METADATA_SCOPE,
+      alias,
+      <PropertyRsdkMetadata>{ metadata, alias },
+      true,
+    );
   }
 }

package/src/config/metadata/constants.ts

@@ -0,0 +1,6 @@
+export const CONFIG_SOURCE_RSDK_METADATA_SCOPE =
+  'CONFIG_SOURCE_RSDK_METADATA_SCOPE';
+export const CONFIG_SECTION_RSDK_METADATA_SCOPE =
+  'CONFIG_SECTION_RSDK_METADATA_SCOPE';
+export const CONFIG_PROPERTIES_RSDK_METADATA_SCOPE =
+  'CONFIG_PROPERTIES_RSDK_METADATA_SCOPE';

package/src/config/metadata/decorators/declare-property.decorator.ts

@@ -26,8 +26,8 @@ export const DeclareProperty = <T extends ConfigValue>(
   parser: PropertyParser<T>,
   options: PropertyOptions<T>,
 ): ClassDecorator => {
-  return function (): void {
-    ConfigMetadataRegistry.registerProperty(alias, {
+  return function (target): void {
+    ConfigMetadataRegistry.registerProperty(target, alias, {
       expectedInEnv: true,
       ...options,
       key: alias,

package/src/config/metadata/decorators/inject-property.decorator.ts

@@ -19,7 +19,7 @@ export const trimPrefix = (token: PropertyToken): string =>
  * 1. To inject properties into ConfigSource constructors. In this case
  * one should add @DeclareProperty() to ConfigSource constructor first.
  *
- * 2. To create and inject dynamic properties (ex: @rsdk/grpc-clients).
+ * 2. To create and inject dynamic properties (ex: @rsdk/grpc.clients).
  * In this case they should be registered manually using
  * ConfigMetadataRegistry.registerProperty() method.
  *

package/src/config/metadata/types.ts

@@ -0,0 +1,22 @@
+import type { Constructor } from '@rsdk/common';
+
+import type { Config } from '../config.abstract';
+import type { ConfigSource } from '../sources';
+import type {
+  PropertyMetadata,
+  SectionMetadata,
+  SourceMetadata,
+} from '../types';
+
+export type PropertyRsdkMetadata = {
+  metadata: PropertyMetadata;
+  alias: string;
+};
+export type SectionRsdkMetadata = {
+  target: Constructor<Config>;
+  metadata: SectionMetadata;
+};
+export type SourcesRsdkMetadata = {
+  target: Constructor<ConfigSource>;
+  metadata: SourceMetadata;
+};

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

@@ -1,4 +1,3 @@
-/* eslint-disable prettier/prettier */
 import EventEmitter from 'events';
 
 import type { Config } from '../config.abstract';
@@ -6,17 +5,7 @@ import type { PropertyException } from '../exceptions';
 import type { ConfigSource, ConfigSourceException } from '../sources';
 import type { Changes, RawValues } from '../types';
 
-export class ReloadEvents extends EventEmitter {
-  private static instance: ReloadEvents;
-
-  static getInstance(): ReloadEvents {
-    if (!this.instance) {
-      this.instance = new ReloadEvents();
-    }
-
-    return this.instance;
-  }
-}
+export class ReloadEvents extends EventEmitter {}
 
 export declare interface ReloadEvents {
   on(e: 'reload', fn: (source: ConfigSource, values: RawValues) => void): this;
@@ -30,7 +19,6 @@ export declare interface ReloadEvents {
     e: 'update_failure',
     fn: (section: Config, err: PropertyException) => void,
   ): this;
-
   emit(e: 'reload', source: ConfigSource, values: RawValues): boolean;
   emit(
     e: 'reload_failure',

package/src/config/sources/base/reloadable-config-source.abstract.ts

@@ -1,15 +1,14 @@
 import type { ILogger } from '@rsdk/logging';
 
-import { ReloadEvents } from '../../reload';
+import type { ReloadEvents } from '../../reload';
 import type { SourceType } from '../../types';
 
 import { ConfigSource } from './config-source.abstract';
 
 export abstract class ReloadableConfigSource extends ConfigSource {
   protected readonly logger: ILogger;
-  private readonly events = ReloadEvents.getInstance();
 
-  constructor(logger: ILogger) {
+  constructor(logger: ILogger, private readonly events: ReloadEvents) {
     super();
     this.logger = logger;
   }

package/src/config/sources/implementations/relodable-json-file.source.ts

@@ -5,6 +5,7 @@ import { LoggerFactory } from '@rsdk/logging';
 
 import { DeclareProperty, InjectProperty } from '../../metadata';
 import { FsPathParser } from '../../parsers';
+import { ReloadEvents } from '../../reload';
 import { ReloadableConfigSource } from '../base';
 import { Source } from '../config-source.decorator';
 
@@ -13,8 +14,11 @@ import { Source } from '../config-source.decorator';
   description: 'Path to some configuration file',
 })
 export class ReloadableFileSource extends ReloadableConfigSource {
-  constructor(@InjectProperty('CONFIG_PATH') private readonly path: string) {
-    super(LoggerFactory.create(ReloadableFileSource));
+  constructor(
+    @InjectProperty('CONFIG_PATH') private readonly path: string,
+    private reloadEvents: ReloadEvents,
+  ) {
+    super(LoggerFactory.create(ReloadableFileSource), reloadEvents);
   }
 
   override name(): string {

package/src/config/vars.class.ts

@@ -69,8 +69,10 @@ export class Vars {
     return { createdKeys, updatedKeys };
   }
 
-  extract<T extends ConfigValue>(propMeta: PropertyMetadata<T>): T | undefined {
-    const { key, parser } = propMeta;
+  extract<T extends ConfigValue>(
+    propertyMetadata: PropertyMetadata<T>,
+  ): T | undefined {
+    const { key, parser } = propertyMetadata;
     const preparedKey = this.toUpperSnakeCase(key);
 
     const withPrefix = this.prefix
@@ -80,20 +82,20 @@ export class Vars {
     const raw = this.values.get(withPrefix) ?? this.values.get(preparedKey);
 
     if (raw === undefined) {
-      if ('defaultValue' in propMeta) {
-        return propMeta.defaultValue;
+      if ('defaultValue' in propertyMetadata) {
+        return propertyMetadata.defaultValue;
       }
 
       throw new PropertyException(
-        preparedKey,
-        'No value by key ' + propMeta.key + ' was provided!',
+        `No value by key ${propertyMetadata.key} was provided!`,
+        { propertyMetadata, preparedKey },
       );
     }
 
     try {
       return parser.parse(raw);
     } catch (err) {
-      throw PropertyException.fromError(err, preparedKey);
+      throw PropertyException.fromError(err, { preparedKey, propertyMetadata });
     }
   }