@rsdk/core 0.14.0

package/src/exceptions.handling/types.ts

@@ -0,0 +1,88 @@
+import type { ArgumentsHost } from '@nestjs/common';
+import type { EMPTY, Observable } from 'rxjs';
+
+import type { PipelineException } from '../exceptions/base';
+
+/**
+ * Errors formatter is used to map transport-agnostic
+ * buisiness exception to transport-specific on (with appropriate
+ * status code and other attributes)
+ *
+ * @implementme Implement this interface if you need to create a
+ * custom transport.
+ */
+export interface IErrorsFormatter {
+  /**
+   * Matcher returns true if exception should be processed with
+   * this formatter. Most common use is match by context type.
+   *
+   * @param host ArgumentsHost - nest.js wrapper over request context
+   * @param exception Exception itself
+   */
+  match(host: ArgumentsHost, exception?: unknown): boolean;
+
+  /**
+   * Formatting algorithm that should match received exception with
+   * transport-specific one and map one into another.
+   *
+   * @param exception Exception itself
+   * @param verbose True - means that all exception data can be exposed
+   * in response. False - indicates that service is probably working in
+   * production and all extra data shouldn't be sent back to client.
+   */
+  format(exception: unknown, verbose: boolean): unknown;
+}
+
+/**
+ * Different transports need to return errors in different ways.
+ *
+ * @implementme
+ */
+export interface IErrorsSender {
+  /**
+   * Matcher returns true if exception should be processed with
+   * this formatter. Most common use is match by context type.
+   *
+   * @param host ArgumentsHost - nest.js wrapper over request context
+   */
+  match(host: ArgumentsHost): boolean;
+
+  /**
+   * Implementation of sending error back to the client
+   *
+   * @param host ArgumentsHost - nest.js wrapper over request context
+   * @param exception Exception itself
+   */
+  send(host: ArgumentsHost, ex: unknown): Observable<any> | typeof EMPTY;
+}
+
+/**
+ * Not all exceptions that can be thrown when handling request
+ * are created in application code. And library authors have no
+ * idea about PipelineExceptions and our conventions. Hence they
+ * throw their own errors of any possible type.
+ *
+ * Aim of transformers is to catch those "unconventional" errors and
+ * map them into instances of PipelineException which then will be
+ * mapped correctly to responses.
+ *
+ * @implementme Implement this interface if you use some library that
+ * can throw (let's say axios) and don't want to wrap each call of this
+ * library into try/catch block
+ */
+export interface IErrorsTransformer {
+  /**
+   * Matcher returns true if exception should be processed with
+   * this transformer
+   *
+   * @param ex Exception to transform
+   */
+  match(ex: any): boolean;
+
+  /**
+   * Transformating algorithm
+   *
+   * @param ex Exception itself
+   */
+  transform(ex: any): PipelineException;
+}

package/src/health/exceptions/health-check.exception.ts

@@ -0,0 +1,9 @@
+import { Exception, ExceptionKind, PipelineException } from '../../exceptions';
+import type { CheckResult } from '../helpers';
+
+@Exception({ description: 'Service is unavailable' })
+export class HealthCheckException extends PipelineException {
+  constructor(details: Record<string, CheckResult>) {
+    super(ExceptionKind.UNAVAILABLE, 'Health check failed!', { details });
+  }
+}

package/src/health/exceptions/index.ts

@@ -0,0 +1 @@
+export * from './health-check.exception';

package/src/health/health.const.ts

@@ -0,0 +1,2 @@
+export const MODULE_OPTIONS = 'HEALTH_MODULE_OPTIONS';
+export const HEALTH_SERVICE = 'HEALTH_SERVICE_TOKEN';

package/src/health/health.module.ts

@@ -0,0 +1,23 @@
+import type { DynamicModule } from '@nestjs/common';
+import { Module } from '@nestjs/common';
+
+import { MODULE_OPTIONS } from './health.const';
+import { HealthChecksService } from './health.service';
+import type { HealthModuleOptions } from './types';
+
+@Module({})
+export class HealthModule {
+  static forRoot(options: HealthModuleOptions): DynamicModule {
+    return {
+      controllers: [...options.controllers],
+      module: HealthModule,
+      providers: [
+        HealthChecksService,
+        {
+          provide: MODULE_OPTIONS,
+          useValue: options,
+        },
+      ],
+    };
+  }
+}

package/src/health/health.service.ts

@@ -0,0 +1,125 @@
+import { Injectable } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import type { Constructor } from '@rsdk/common';
+import { LogTime } from '@rsdk/decorators';
+import { ILogger } from '@rsdk/logging';
+
+import { InjectLogger } from '../logging';
+
+import { HealthCheckException } from './exceptions';
+import { IndicatorsRegistry } from './metadata';
+import type {
+  CheckSummary,
+  HealthIndicator,
+  ResolvedIndicators,
+} from './types';
+
+@Injectable()
+export class HealthChecksService {
+  private readonly indicators: ResolvedIndicators = { common: [] };
+  private readonly indicatorNames = new Map<HealthIndicator, string>();
+
+  constructor(
+    @InjectLogger(HealthChecksService) private readonly logger: ILogger,
+    private readonly moduleRef: ModuleRef,
+  ) {}
+
+  @LogTime()
+  async check(filter?: '*' | string): Promise<CheckSummary> {
+    this.logger.info('Checking health', { filter });
+
+    const indicators = this.filterIndicators(filter);
+
+    let success = true;
+    const summary: CheckSummary = { details: {}, status: 'up' };
+
+    await Promise.all(
+      indicators.map(async (indicator) => {
+        const name = this.indicatorNames.get(indicator);
+        if (!name) {
+          throw new Error(
+            `Indicator [${indicator.constructor.name}] - name not found`,
+          );
+        }
+
+        try {
+          const result = await indicator.check();
+          if (result.isError) {
+            success = false;
+          }
+
+          summary.details[name] = result;
+        } catch (err) {
+          success = false;
+          summary.details[name] = err as any;
+        }
+      }),
+    );
+
+    if (!success) {
+      throw new HealthCheckException(summary.details);
+    }
+
+    return summary;
+  }
+
+  async onModuleInit(): Promise<void> {
+    this.logger.debug('Initializing indicators...');
+
+    for (const [ctor, { key, scope }] of IndicatorsRegistry.entries()) {
+      if (!this.indicators[scope]) {
+        this.indicators[scope] = [];
+      }
+
+      const [instance] = this.resolve([ctor]);
+
+      this.indicatorNames.set(instance, key);
+      this.indicators[scope].push(instance);
+    }
+
+    this.logger.info(`Indicators initialized!`);
+  }
+
+  private filterIndicators(filter: '*' | string = ''): HealthIndicator[] {
+    switch (filter) {
+      /**
+       * This means readiness healthcheck which means that server itself is up,
+       * but doesn't guarantee that it is ready to serve.
+       */
+      case '':
+        return [];
+
+      /**
+       * This means - "perform all checks you have"
+       */
+      case '*':
+        return [...this.indicators.common];
+
+      /**
+       * Matching exact filter. If no specific checks
+       * found - common checks will be performed
+       */
+      default: {
+        const specific = this.indicators[filter];
+
+        if (!specific || specific.length === 0) {
+          this.logger.warn(`Unsupported healthcheck filter: ${filter}`);
+        }
+
+        return [...this.indicators.common, ...(specific || [])];
+      }
+    }
+  }
+
+  private resolve(
+    indicators: Readonly<Constructor<HealthIndicator>[]>,
+  ): HealthIndicator[] {
+    return indicators.map((x) => {
+      if (typeof x !== 'function') {
+        return x;
+      }
+
+      return this.moduleRef.get(x, { strict: false });
+    });
+  }
+}

package/src/health/helpers/check-result.class.ts

@@ -0,0 +1,52 @@
+export type CheckStatus = 'up' | 'down';
+export type CheckDetails = Record<string, unknown>;
+
+/**
+ * Check result is an outcome for a check. It is
+ * a little specialized version of classical Result
+ * abstraction with error and data
+ */
+export class CheckResult {
+  /**
+   * Check status
+   */
+  readonly status: CheckStatus;
+
+  /**
+   * @optional Custom attributes (key value) Will
+   * be returned to check caller or/and logged
+   */
+  readonly details?: CheckDetails;
+
+  private constructor(status: CheckStatus, details: CheckDetails) {
+    this.status = status;
+    this.details = details;
+  }
+
+  /**
+   * Indicated that check was not successful
+   */
+  get isError(): boolean {
+    return this.status === 'down';
+  }
+
+  /**
+   * Creates successful CheckResult
+   *
+   * @param details Any custom attributes
+   * @returns CheckResult
+   */
+  static up(details: CheckDetails): CheckResult {
+    return new CheckResult('up', details);
+  }
+
+  /**
+   * Creates failed CheckResult
+   *
+   * @param details Any custom attributes
+   * @returns CheckResult
+   */
+  static down(details: CheckDetails): CheckResult {
+    return new CheckResult('down', details);
+  }
+}

package/src/health/helpers/index.ts

@@ -0,0 +1 @@
+export * from './check-result.class';

package/src/health/index.ts

@@ -0,0 +1,6 @@
+export * from './health.module';
+export * from './health.service';
+export * from './indicators.abstract';
+export * from './metadata/indicator.decorator';
+export * from './types';
+export * from './helpers';

package/src/health/indicators.abstract/fs-access.indicator.ts

@@ -0,0 +1,47 @@
+import { access } from 'fs';
+
+import { CheckResult } from '../helpers';
+import type { HealthIndicator } from '../types';
+
+export interface FileSystemCheckOptions {
+  /**
+   * Absolute path to file or directory
+   */
+  path: string;
+
+  /**
+   * Access mode (see fs.access docs on nodejs website)
+   */
+  mode?: number;
+}
+
+/**
+ * FileSystemIndicator checks if specified file or directory
+ * exists and is accessible to the application
+ *
+ * TODO: Need to be tested! Especially modes.
+ */
+export abstract class FileSystemIndicator implements HealthIndicator {
+  private path: string;
+  private mode: number | undefined;
+
+  constructor(options: FileSystemCheckOptions) {
+    this.path = options.path;
+    this.mode = options.mode;
+  }
+
+  /**
+   * Проверяет, существует ли файл и есть ли к нему доступ
+   */
+  check(): Promise<CheckResult> {
+    return new Promise((resolve, reject) => {
+      access(this.path, this.mode, (error) => {
+        if (!error) {
+          resolve(CheckResult.up({ path: this.path }));
+        } else {
+          reject({ error });
+        }
+      });
+    });
+  }
+}

package/src/health/indicators.abstract/index.ts

@@ -0,0 +1,2 @@
+export * from './fs-access.indicator';
+export * from './ping.indicator';

package/src/health/indicators.abstract/ping.indicator.ts

@@ -0,0 +1,36 @@
+import type { ILogger } from '@rsdk/logging';
+
+import { InternalException } from '../../exceptions';
+import type { CheckResult } from '../helpers';
+import type { HealthIndicator } from '../types';
+
+export interface PingCheckOptions {
+  /**
+   * URI of external resource
+   */
+  url: URL;
+}
+
+/**
+ * PingIndicator is meant to check access to some network
+ * resource.
+ *
+ * @attention NOT IMPLEMENTED
+ */
+export abstract class PingIndicator implements HealthIndicator {
+  private readonly url: URL;
+
+  constructor(protected logger: ILogger, options: PingCheckOptions) {
+    this.url = options.url;
+  }
+
+  async check(): Promise<CheckResult> {
+    this.logger.info('Url to be checked', { url: this.url });
+
+    /**
+     * TODO: Implement this. How? Probably caller should
+     * specify strategy protocol to use
+     */
+    throw new InternalException('Ping check is yet to be implemented!');
+  }
+}

package/src/health/metadata/index.ts

@@ -0,0 +1,2 @@
+export * from './indicator.decorator';
+export * from './indicators.registry';

package/src/health/metadata/indicator.decorator.ts

@@ -0,0 +1,25 @@
+/* eslint-disable @typescript-eslint/ban-types */
+
+import type { Constructor } from '@rsdk/common';
+
+import type { HealthIndicator } from '../types';
+
+import { IndicatorsRegistry } from './indicators.registry';
+
+export interface IndicatorOptions {
+  description?: string;
+  scope?: string;
+}
+
+export const Indicator = (
+  key: string,
+  options: IndicatorOptions = {},
+): ClassDecorator => {
+  return function (target: Function): void {
+    IndicatorsRegistry.register(target as Constructor<HealthIndicator>, {
+      key,
+      scope: 'common',
+      ...options,
+    });
+  };
+};

package/src/health/metadata/indicators.registry.ts

@@ -0,0 +1,38 @@
+import type { Constructor } from '@rsdk/common';
+import { LoggerFactory } from '@rsdk/logging';
+
+import { DoubleInitException } from '../../exceptions';
+import type { HealthIndicator, IndicatorMetadata } from '../types';
+
+export class IndicatorsRegistry {
+  private static logger = LoggerFactory.create('IndicatorsRegistry');
+  private static indicators = new Map<
+    Constructor<HealthIndicator>,
+    IndicatorMetadata
+  >();
+
+  static isRegistered(ctor: Constructor<HealthIndicator>): boolean {
+    return this.indicators.has(ctor);
+  }
+
+  static register(
+    target: Constructor<HealthIndicator>,
+    options: IndicatorMetadata,
+  ): void {
+    if (this.indicators.has(target)) {
+      throw new DoubleInitException('Health indicator', target.name);
+    }
+
+    this.logger.info(`Registering indicator: ${target.name}`, {
+      indicator: target.name,
+    });
+
+    this.indicators.set(target, options);
+  }
+
+  static entries(): Iterable<
+    [Constructor<HealthIndicator>, IndicatorMetadata]
+  > {
+    return this.indicators.entries();
+  }
+}

package/src/health/types.ts

@@ -0,0 +1,50 @@
+import type { Controller } from '@nestjs/common/interfaces';
+import type { Constructor } from '@rsdk/common';
+
+import type { CheckResult } from './helpers';
+
+/**
+ * Summary for a number of **successful** checks
+ */
+export interface CheckSummary {
+  /**
+   * Overral check status
+   *
+   * NOTE: If some checks fail an exception will be thrown.
+   * So 'down' will never be returned.
+   */
+  status: 'up';
+
+  /**
+   * @keys indicator keys
+   * @values check result for respective indicator
+   */
+  details: Record<string, CheckResult>;
+}
+
+/**
+ * To create indicator with any custom logic
+ * just implement this interface
+ */
+export interface HealthIndicator {
+  /**
+   * Actual check method.
+   *
+   * @returns CheckResult
+   */
+  check(): Promise<CheckResult>;
+}
+
+export type ResolvedIndicators = {
+  [key: string]: HealthIndicator[];
+} & { common: HealthIndicator[] };
+
+export interface HealthModuleOptions {
+  controllers: Constructor<Controller>[];
+}
+
+export interface IndicatorMetadata {
+  key: string;
+  scope: string;
+  description?: string;
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+export { PlatformContext } from './platform.context';
+
+export * from './config';
+export * from './exceptions';
+export * from './exceptions.handling';
+export {
+  // TODO: Продолжить документирование отсюда
+  HealthIndicator,
+  FileSystemIndicator,
+  FileSystemCheckOptions,
+  PingIndicator,
+  PingCheckOptions,
+  HealthChecksService,
+  CheckSummary,
+  Indicator,
+  CheckResult,
+} from './health';
+export { InjectLogger } from './logging';
+export {
+  AnyMetric,
+  Counter,
+  Gauge,
+  Histogram,
+  Summary,
+  Metric,
+  MetricsModule,
+  register,
+} from './metrics';
+export { PlatformApp } from './app/platform.app';
+export * from './types';
+export * from './app-metadata/decorators';
+export * from './app-metadata/app-metadata.const';

package/src/logging/adapters/index.ts

@@ -0,0 +1 @@
+export * from './nest-logger.adapter';

package/src/logging/adapters/nest-logger.adapter.ts

@@ -0,0 +1,32 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+import type { LoggerService } from '@nestjs/common';
+import type { ILogger } from '@rsdk/logging';
+
+export class NestLoggerAdapter implements LoggerService {
+  constructor(private readonly logger: ILogger) {}
+
+  error(message: unknown, trace?: string, _context?: string): void {
+    this.logger.error(Object.assign(new Error(message as string), { trace }));
+  }
+
+  log(message: unknown, _context?: string): void {
+    this.logger.info(message as string);
+  }
+
+  warn(message: unknown, _context?: string): void {
+    this.logger.warn(message as string);
+  }
+
+  debug(message: unknown, _context?: string): void {
+    this.logger.debug(message as string);
+  }
+
+  verbose(message: unknown, _context?: string): void {
+    this.logger.trace(message as string);
+  }
+
+  // private parseMessage (message: unknown): string {
+  //   return typeof message === 'string' ? message : stringifyObject(message);
+  // }
+}

package/src/logging/decorators/index.ts

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

package/src/logging/decorators/inject-logger.decorator.ts

@@ -0,0 +1,15 @@
+import { Inject } from '@nestjs/common';
+import type { Constructor } from '@rsdk/common';
+
+import { getLoggerToken } from '../helpers';
+import { LoggingModule } from '../logging.module';
+
+export const InjectLogger = (
+  context: string | Constructor,
+): ParameterDecorator => {
+  const token = getLoggerToken(context);
+
+  LoggingModule.register(context, token);
+
+  return Inject(token);
+};

package/src/logging/helpers.ts

@@ -0,0 +1,5 @@
+import type { Constructor } from '@rsdk/common';
+import { stringifyContext } from '@rsdk/logging';
+
+export const getLoggerToken = (context: string | Constructor): string =>
+  `LOGGER_${stringifyContext(context)}`;

package/src/logging/index.ts

@@ -0,0 +1,4 @@
+export * from '@rsdk/logging';
+export * from './logging.module';
+export * from './adapters';
+export * from './decorators';

package/src/logging/logging.config.ts

@@ -0,0 +1,26 @@
+import { LogLevel } from '@rsdk/logging';
+
+import {
+  ArrayParser,
+  Config,
+  ConfigSection,
+  EnumParser,
+  Property,
+  StringParser,
+} from '../config';
+
+@ConfigSection()
+export class LoggingConfig extends Config {
+  @Property('LOG_LEVEL', new EnumParser(LogLevel), {
+    // TODO: Can pass anything instead of enum value. Need to handle this!
+    defaultValue: LogLevel.debug,
+    description: 'Log level',
+  })
+  readonly level!: LogLevel;
+
+  @Property('LOG_REDACT', new ArrayParser(new StringParser()), {
+    defaultValue: [],
+    description: 'Log level',
+  })
+  readonly redact!: string[];
+}