@rsdk/core 0.14.0

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

@@ -0,0 +1,43 @@
+/* eslint-disable prettier/prettier */
+import EventEmitter from 'events';
+
+import type { Config } from '../config.abstract';
+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 declare interface ReloadEvents {
+  on(e: 'reload', fn: (source: ConfigSource, values: RawValues) => void): this;
+  on(
+    e: 'reload_failure',
+    fn: (source: ConfigSource, err: ConfigSourceException) => void,
+  ): this;
+  on(e: 'merge', fn: (source: ConfigSource, changes: Changes) => void): this;
+  on(e: 'update', fn: (section: Config, keys: string[]) => void): this;
+  on(
+    e: 'update_failure',
+    fn: (section: Config, err: PropertyException) => void,
+  ): this;
+
+  emit(e: 'reload', source: ConfigSource, values: RawValues): boolean;
+  emit(
+    e: 'reload_failure',
+    source: ConfigSource,
+    err: ConfigSourceException,
+  ): boolean;
+  emit(e: 'merge', source: ConfigSource, changes: Changes): boolean;
+  emit(e: 'update', section: Config, keys: string[]): boolean;
+  emit(e: 'update_failure', section: Config, err: PropertyException): boolean;
+}

package/src/config/reload/index.ts

@@ -0,0 +1 @@
+export * from './config-reload.events';

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

@@ -0,0 +1,90 @@
+import { isPrimitive, isRecord } from '@rsdk/common';
+
+import type { RawConfigValue, RawValues, SourceType } from '../../types';
+import { ConfigSourceException } from '../exceptions';
+
+export abstract class ConfigSource {
+  /**
+   * Wrapped .loadRaw() method which should be implemented in
+   * derived class and enforces basic validation and error transforming.
+   *
+   * NOTE: Guarantees that only ConfigSourceException can't be thrown
+   * @returns Promise<Vars>
+   */
+  async load(): Promise<RawValues> {
+    try {
+      /**
+       * Need to handle error on reload because
+       * otherwise application will go down (just as
+       * on reading step)
+       *
+       * TODO: Add negative health check when last
+       * 3 configuration updates fail
+       */
+      const raw = await this.loadRaw();
+
+      return this.flattenEndValidate(raw);
+    } catch (err) {
+      if (err instanceof ConfigSourceException) {
+        throw err;
+      }
+
+      throw new ConfigSourceException(
+        'Failed to load configuration from file',
+        err as Error,
+      );
+    }
+  }
+
+  /**
+   * Flattens raw configuration and validates that each property is
+   * either primitive or array of primitives.
+   *
+   * @param obj Raw configuration object obtained from source
+   * @param prefix recursive calls chain path in for of string
+   * @returns Vars
+   */
+  private flattenEndValidate(obj: unknown, prefix = ''): RawValues {
+    if (!isRecord(obj)) {
+      throw new ConfigSourceException(
+        prefix
+          ? `Value at key: ${prefix} should be an object, primitive or array of primitives`
+          : `Value at root sould be an object`,
+      );
+    }
+
+    return Object.entries(obj).reduce((acc: RawValues, [key, value]) => {
+      if (isPrimitive(value)) {
+        acc.set(key, value);
+
+        return acc;
+      }
+
+      const pre = (prefix.length > 0 ? `${prefix}.` : '') + key;
+
+      if (Array.isArray(value)) {
+        if (!value.every(isPrimitive)) {
+          throw new ConfigSourceException(`Non primitive array at key: ${pre}`);
+        }
+
+        acc.set(key, value);
+
+        return acc;
+      }
+
+      /**
+       * Value is not primitive and is not array which means
+       * it is object. So: do recursion
+       */
+      for (const [key, v] of this.flattenEndValidate(value, pre).entries()) {
+        acc.set(key, v);
+      }
+
+      return acc;
+    }, new Map<string, RawConfigValue>());
+  }
+
+  abstract name(): string;
+  abstract type(): SourceType;
+  abstract loadRaw(): Promise<unknown>;
+}

package/src/config/sources/base/index.ts

@@ -0,0 +1,2 @@
+export * from './reloadable-config-source.abstract';
+export * from './config-source.abstract';

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

@@ -0,0 +1,39 @@
+import type { ILogger } from '@rsdk/logging';
+
+import { 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) {
+    super();
+    this.logger = logger;
+  }
+
+  type(): SourceType {
+    return 'reloadable';
+  }
+
+  async reload(): Promise<void> {
+    try {
+      const vars = await this.load();
+
+      this.events.emit('reload', this, vars);
+    } catch (err: any) {
+      this.logger.error(
+        `Failed to reload configuration (${this.constructor.name})`,
+        err,
+      );
+      this.events.emit('reload_failure', this, err);
+    }
+  }
+
+  abstract init(): void;
+}
+
+export const isReloadable = (s: ConfigSource): s is ReloadableConfigSource =>
+  s.type() === 'reloadable';

package/src/config/sources/config-source.decorator.ts

@@ -0,0 +1,37 @@
+/* eslint-disable @typescript-eslint/ban-types */
+import type { Constructor } from '@rsdk/common';
+
+import { ConfigMetadataRegistry } from '../metadata';
+import type { SourceType } from '../types';
+
+const SOURCE_METADATA_KEY = 'CONFIG_SOURCE_METADATA_KEY';
+
+export interface SourceOptions {
+  description?: string;
+  name?: string;
+}
+
+const DEFAULT_OPTIONS = {};
+
+/**
+ * This decorator is used to register additional configuration
+ * sourcePropertyParser
+ * @param options Metadata used mostly for docs generation
+ * @returns
+ */
+export const Source = (
+  type: SourceType,
+  options: SourceOptions = {},
+): ClassDecorator => {
+  return function (target: Function): void {
+    const name = options.name || target.name;
+    const effectiveOptions = { ...DEFAULT_OPTIONS, ...options, name, type };
+
+    Reflect.defineMetadata(SOURCE_METADATA_KEY, effectiveOptions, target);
+
+    ConfigMetadataRegistry.registerSource(
+      target as Constructor,
+      effectiveOptions,
+    );
+  };
+};

package/src/config/sources/exceptions/config-source-di.exception.ts

@@ -0,0 +1,20 @@
+import { Constructor, text } from '@rsdk/common';
+
+import { BootstrapException, Exception } from '../../../exceptions';
+import type { ConfigSource } from '../base';
+
+@Exception({
+  description: text`
+    Wrong usage of DI in custom configuration source.
+    See @rsdk/core docs.
+  `,
+})
+export class ConfigSourceDIException extends BootstrapException {
+  constructor(source: Constructor<ConfigSource>, param: unknown) {
+    super(text`
+      Only standalone properties (from env) and some special values (ex. application name)
+      can be injected into ConfigSource constructor. You are trying to inject
+      <${param}> to ${source.constructor.name}.
+    `);
+  }
+}

package/src/config/sources/exceptions/config-source.exception.ts

@@ -0,0 +1,7 @@
+import { PlatformException } from '../../../exceptions';
+
+export class ConfigSourceException extends PlatformException {
+  constructor(message: string, cause?: Error) {
+    super('CONFIG:LOAD', message, { cause });
+  }
+}

package/src/config/sources/exceptions/index.ts

@@ -0,0 +1,2 @@
+export * from './config-source.exception';
+export * from './config-source-di.exception';

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

@@ -0,0 +1,29 @@
+import { readObj } from '@rsdk/common';
+
+import { DeclareProperty, InjectProperty } from '../../metadata';
+import { FsPathParser } from '../../parsers';
+import type { SourceType } from '../../types';
+import { ConfigSource } from '../base';
+import { Source } from '../config-source.decorator';
+
+@Source('static')
+@DeclareProperty(`CONFIG_PATH`, new FsPathParser('file'), {
+  description: 'Path to some configuration file',
+})
+export class StaticFileSource extends ConfigSource {
+  constructor(@InjectProperty('CONFIG_PATH') private readonly path: string) {
+    super();
+  }
+
+  override type(): SourceType {
+    return 'static';
+  }
+
+  override name(): string {
+    return `Static conf file: ${this.path}`;
+  }
+
+  override loadRaw(): Promise<unknown> {
+    return readObj(this.path);
+  }
+}

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

@@ -0,0 +1,39 @@
+import { watch } from 'fs';
+
+import { readObj } from '@rsdk/common';
+import { LoggerFactory } from '@rsdk/logging';
+
+import { DeclareProperty, InjectProperty } from '../../metadata';
+import { FsPathParser } from '../../parsers';
+import { ReloadableConfigSource } from '../base';
+import { Source } from '../config-source.decorator';
+
+@Source('reloadable')
+@DeclareProperty('CONFIG_PATH', new FsPathParser('file'), {
+  description: 'Path to some configuration file',
+})
+export class ReloadableFileSource extends ReloadableConfigSource {
+  constructor(@InjectProperty('CONFIG_PATH') private readonly path: string) {
+    super(LoggerFactory.create(ReloadableFileSource));
+  }
+
+  override name(): string {
+    return `Configuration file: ${this.path}`;
+  }
+
+  override loadRaw(): Promise<unknown> {
+    return readObj(this.path);
+  }
+
+  override init(): void {
+    watch(this.path, (event) => {
+      if (event !== 'change') {
+        return;
+      }
+
+      this.logger.info('Changes detected', { source: this.name });
+
+      this.reload();
+    });
+  }
+}

package/src/config/sources/index.ts

@@ -0,0 +1,3 @@
+export * from './config-source.decorator';
+export * from './exceptions';
+export * from './base';

package/src/config/types.ts

@@ -0,0 +1,87 @@
+import type { EnumValue, Primitive, Size, Timespan } from '@rsdk/common';
+
+export type SourceType = 'static' | 'reloadable';
+export type RawConfigValue = Primitive | Primitive[];
+
+export type SingleConfigValue =
+  | string
+  | number
+  | boolean
+  | Timespan
+  | Size
+  | EnumValue
+  | URL;
+
+export type ConfigValue = SingleConfigValue | SingleConfigValue[];
+
+export interface Changes {
+  createdKeys: string[];
+  updatedKeys: string[];
+}
+
+export interface PropertyOptions<T extends ConfigValue> {
+  /**
+   * Description of configuration property. Will automatically
+   * appear in documentation.
+   */
+  description: string;
+
+  /**
+   * Providing default value for property effectively makes it optional
+   */
+  defaultValue?: T | undefined;
+}
+
+export interface PropertyMetadata<T extends ConfigValue = ConfigValue> {
+  key: string;
+  parser: PropertyParser<T>;
+  description: string;
+
+  /**
+   * Expect that this property will be in env, not in extra source.
+   */
+  expectedInEnv: boolean;
+  defaultValue?: T | undefined;
+}
+
+export interface SectionMetadata {
+  name: string;
+  // TODO: Why use Record instead of map here
+  // TODO: Why symbol here
+  properties: Record<string | symbol, PropertyMetadata>;
+  description?: string;
+}
+
+export interface SourceMetadata {
+  type: SourceType;
+  name: string;
+  description?: string;
+}
+
+export interface ParserMetadata {
+  type: string;
+  description: string;
+}
+
+/**
+ * Implement this interface to create more parsers.
+ * For example: email, BigInt, guid etc.
+ *
+ * NOTE: In other modules it is more common to define metadata
+ * via decorators. But this case is a bit different.
+ *
+ * 1. Parser implementations can have constructors with parameters
+ * which will affect it's behaviour. It's will be nice to have it
+ * in metadata, and decorators won't provide this.
+ *
+ * 2. Metadata will be extracted via type() and description() methods
+ * mostly during decorator factories (such as @Property()) code is
+ * executed. Thus output **can** be used in autodoc
+ */
+export interface PropertyParser<T extends ConfigValue = ConfigValue> {
+  type(): string;
+  description(): string;
+  parse(value: RawConfigValue): T;
+}
+
+export type RawValues = Map<string, RawConfigValue>;

package/src/config/vars.class.ts

@@ -0,0 +1,103 @@
+import { cloneDeep, isEqual } from 'lodash';
+
+import { PropertyException } from './exceptions';
+import type {
+  Changes,
+  ConfigValue,
+  PropertyMetadata,
+  RawConfigValue,
+  RawValues,
+} from './types';
+
+export enum SetResult {
+  CREATED,
+  UPDATED,
+  UNCHANGED,
+}
+
+export class Vars {
+  private readonly values = new Map<string, RawConfigValue>();
+
+  /**
+   * Expecting prefix is already converted to upper snake case
+   * @param prefix
+   */
+  constructor(private readonly prefix: string) {}
+
+  set(key: string, value: RawConfigValue): [SetResult, string] {
+    const preparedKey = this.toUpperSnakeCase(key);
+    const preparedValue = Array.isArray(value)
+      ? cloneDeep(value).sort()
+      : value;
+
+    const existing = this.values.get(preparedKey);
+
+    if (existing === undefined) {
+      this.values.set(preparedKey, preparedValue);
+
+      return [SetResult.CREATED, preparedKey];
+    }
+
+    if (isEqual(preparedValue, existing)) {
+      return [SetResult.UNCHANGED, preparedKey];
+    }
+
+    this.values.set(preparedKey, preparedValue);
+
+    return [SetResult.UPDATED, preparedKey];
+  }
+
+  merge(values: RawValues): Changes {
+    const createdKeys: string[] = [];
+    const updatedKeys: string[] = [];
+
+    for (const [key, value] of values.entries()) {
+      const [result, preparedKey] = this.set(key, value);
+
+      switch (result) {
+        case SetResult.CREATED:
+          createdKeys.push(preparedKey);
+
+          break;
+        case SetResult.UPDATED:
+          updatedKeys.push(preparedKey);
+
+          break;
+      }
+    }
+
+    return { createdKeys, updatedKeys };
+  }
+
+  extract<T extends ConfigValue>(propMeta: PropertyMetadata<T>): T | undefined {
+    const { key, parser } = propMeta;
+    const preparedKey = this.toUpperSnakeCase(key);
+
+    const withPrefix = this.prefix
+      ? `${this.toUpperSnakeCase(this.prefix)}_${preparedKey}`
+      : preparedKey;
+
+    const raw = this.values.get(withPrefix) ?? this.values.get(preparedKey);
+
+    if (raw === undefined) {
+      if ('defaultValue' in propMeta) {
+        return propMeta.defaultValue;
+      }
+
+      throw new PropertyException(
+        preparedKey,
+        'No value by key ' + propMeta.key + ' was provided!',
+      );
+    }
+
+    try {
+      return parser.parse(raw);
+    } catch (err) {
+      throw PropertyException.fromError(err, preparedKey);
+    }
+  }
+
+  private toUpperSnakeCase(key: string): string {
+    return key.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase();
+  }
+}

package/src/exceptions/base/bootstrap-exception.abstract.ts

@@ -0,0 +1,20 @@
+import type { ExceptionsProps } from './platform-exception.absract';
+import { PlatformException } from './platform-exception.absract';
+
+/**
+ * Bootstrap exception is one that happens on application
+ * startup (bootstrap). Exceptions of this kind should kill the
+ * application completely.
+ */
+export abstract class BootstrapException extends PlatformException {
+  /**
+   * @param kind kind of pipeline error
+   * @param message error message
+   * @param props additional properties
+   */
+  constructor(message: string, props?: ExceptionsProps) {
+    const { code, ...other } = props || {};
+
+    super(code ?? `BOOTSTRAP`, message, other);
+  }
+}

package/src/exceptions/base/index.ts

@@ -0,0 +1,3 @@
+export * from './pipeline-exception.abstract';
+export * from './platform-exception.absract';
+export * from './bootstrap-exception.abstract';

package/src/exceptions/base/pipeline-exception.abstract.ts

@@ -0,0 +1,29 @@
+import { ExceptionKind } from '../types';
+
+import type { ExceptionsProps } from './platform-exception.absract';
+import { PlatformException } from './platform-exception.absract';
+
+/**
+ * PipelineException is exception that occurs during request
+ * or event handling. In both cases it raises inside Nest.js
+ * pipeline and is meant to be caught by GlobalExceptionsFilter
+ */
+export abstract class PipelineException extends PlatformException {
+  /**
+   * All pipeline exceptions have "kind" field which allows to
+   * map them to any specific transport exception.
+   */
+  readonly kind: ExceptionKind;
+
+  /**
+   * @param kind kind of pipeline error
+   * @param message error message
+   * @param props additional properties
+   */
+  constructor(kind: ExceptionKind, message: string, props?: ExceptionsProps) {
+    const { code, ...other } = props || {};
+
+    super(code ?? `KIND:${ExceptionKind[kind]}`, message, other);
+    this.kind = kind;
+  }
+}

package/src/exceptions/base/platform-exception.absract.ts

@@ -0,0 +1,72 @@
+export type ExceptionCode = string | number;
+
+export interface ExceptionsProps<T = any> {
+  /**
+   * Custom exception code
+   */
+  code?: ExceptionCode | undefined;
+  /**
+   * Wrapped original error
+   */
+  cause?: Error | undefined;
+
+  /**
+   * Additional structured details
+   */
+  details?: T | undefined;
+}
+
+/**
+ * Every error thrown in platform based application
+ * should be derivitives of PlatformException. This doesn't
+ * mean that thowing just new Error() will ruin production.
+ * But there will be no automatic nice handling in this case.
+ */
+export abstract class PlatformException<T = any> extends Error {
+  /**
+   * Class name of exception
+   */
+  readonly metatype: string;
+
+  /**
+   * Required!
+   */
+  readonly code: ExceptionCode;
+
+  /**
+   * PlatformException has ability to wrap original errors. Such an option exists
+   * in many other languages and frameworks: .NET, Java, Go etc.
+   */
+  readonly cause: Error | undefined;
+
+  /**
+   * Any custom attributes developer is willing to
+   * attach. Very useful for creating structured validation
+   * errors
+   */
+  readonly details: T | undefined;
+
+  /**
+   * @param message error message
+   * @param props additional properties
+   */
+  constructor(
+    code: ExceptionCode,
+    message: string,
+    props?: Omit<ExceptionsProps<T>, 'code'>,
+  ) {
+    super(message);
+    this.metatype = this.constructor.name;
+    this.code = code;
+    this.cause = props?.cause;
+    this.details = props?.details;
+  }
+
+  static innerMessages(ex: Error): string[] {
+    if (!ex || !(ex instanceof PlatformException) || !ex.cause) {
+      return [];
+    }
+
+    return [ex.cause.message, ...PlatformException.innerMessages(ex.cause)];
+  }
+}

package/src/exceptions/implementations/bootstrap/double-init.exception.ts

@@ -0,0 +1,21 @@
+import { text } from '@rsdk/common';
+
+import { BootstrapException } from '../../base';
+import { Exception } from '../../metadata';
+
+@Exception({
+  description: text`
+    Means that some provider or other object that registered or
+    initialized twice.
+  `,
+})
+export class DoubleInitException extends BootstrapException {
+  constructor(type: string, name: string, hint?: string) {
+    const parts = [`${type} <${name}> is already registered or initialized!`];
+    if (hint) {
+      parts.push(`Hint: ${hint}`);
+    }
+
+    super(parts.join(' '));
+  }
+}

package/src/exceptions/implementations/bootstrap/duplicate-protocol.exception.ts

@@ -0,0 +1,19 @@
+import { text } from '@rsdk/common';
+
+import { BootstrapException } from '../../base';
+import { Exception } from '../../metadata';
+
+@Exception({
+  description: text`
+    Means that you added more than one transport implementations
+    for one protocol.
+  `,
+})
+export class DuplicateProtocolException extends BootstrapException {
+  constructor(protocol: string, duplicates: number) {
+    super(text`
+      You should provide only one transport for each protocol.
+      Protocol ${protocol} has ${duplicates} implementations!
+    `);
+  }
+}