@rsdk/core 0.14.0

package/src/exceptions/implementations/bootstrap/index.ts

@@ -0,0 +1,8 @@
+export * from './unknown-bootstrap.exception';
+export * from './no-http.exception';
+export * from './duplicate-protocol.exception';
+export * from './no-matching-transport.exception';
+export * from './sequence.exception';
+export * from './double-init.exception';
+export * from './no-init.exception';
+export * from './symbol-key-decoration.exception';

package/src/exceptions/implementations/bootstrap/no-http.exception.ts

@@ -0,0 +1,21 @@
+import { text } from '@rsdk/common';
+
+import { BootstrapException } from '../../base';
+import { Exception } from '../../metadata';
+
+@Exception({
+  description: text`
+    Means that you use some HTTP routing decorators (ex: Get, Post etc.)
+    but there is no HTTP-tranport in you application.
+  `,
+})
+export class NoHttpException extends BootstrapException {
+  constructor() {
+    super(text`
+      It is impossible to register HTTP route because there is
+      no HTTP-transport in your application. Please add
+      HTTP-transport or remove HTTP routing decorators:
+      @Get(), @Post(), @Put(), etc.
+    `);
+  }
+}

package/src/exceptions/implementations/bootstrap/no-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 were called
+    was not registered properly.
+  `,
+})
+export class NoInitException extends BootstrapException {
+  constructor(type: string, name: string, hint?: string) {
+    const parts = [`${type} <${name}> is not registered/initialized!`];
+    if (hint) {
+      parts.push(`Hint: ${hint}`);
+    }
+
+    super(parts.join(' '));
+  }
+}

package/src/exceptions/implementations/bootstrap/no-matching-transport.exception.ts

@@ -0,0 +1,24 @@
+import { text } from '@rsdk/common';
+
+import { PlatformAppPlugin } from '../../../types';
+import { BootstrapException } from '../../base';
+import { Exception } from '../../metadata';
+
+@Exception({
+  description: text`
+    Plugins are attached to transports. This exception means that
+    there is no appropriate tranport for the plugin you are trying
+    to attach.
+  `,
+})
+export class NoMatchingTransportException extends BootstrapException {
+  constructor(plugin: PlatformAppPlugin<Readonly<string[]>>) {
+    const name = plugin.constructor.name;
+    const transports = plugin.forTransports().join(', ');
+
+    super(text`
+      Plugin ${name} requires one of the following transports:
+      ${transports} (no one is supported by the app).
+    `);
+  }
+}

package/src/exceptions/implementations/bootstrap/sequence.exception.ts

@@ -0,0 +1,16 @@
+import { text } from '@rsdk/common';
+
+import { BootstrapException } from '../../base';
+import { Exception } from '../../metadata';
+
+@Exception({
+  description: text`
+    Means that some bootstrap operations were mixed in wrong
+    order or were repeated incorrectly.
+  `,
+})
+export class SequenceException extends BootstrapException {
+  constructor(message: string) {
+    super(message, { code: 'SEQUENCE' });
+  }
+}

package/src/exceptions/implementations/bootstrap/symbol-key-decoration.exception.ts

@@ -0,0 +1,15 @@
+import { text } from '@rsdk/common';
+
+import { BootstrapException } from '../../base';
+import { Exception } from '../../metadata';
+
+@Exception({
+  description: text`
+    Occurs when decorator is applied to non string (symbol) property/method.
+  `,
+})
+export class SymbolKeyDecorationException extends BootstrapException {
+  constructor() {
+    super("Can't apply decorator to property or method with symbol key");
+  }
+}

package/src/exceptions/implementations/bootstrap/unknown-bootstrap.exception.ts

@@ -0,0 +1,11 @@
+import { BootstrapException } from '../../base';
+import { Exception } from '../../metadata';
+
+@Exception({
+  description: 'Something fatal happened on rsdk app intialization phase',
+})
+export class UnknownBootstrapException extends BootstrapException {
+  constructor(message: string, cause?: Error) {
+    super(`Failed to init rsdk app: ${message}`, { cause });
+  }
+}

package/src/exceptions/implementations/index.ts

@@ -0,0 +1,2 @@
+export * from './bootstrap';
+export * from './pipeline';

package/src/exceptions/implementations/pipeline/authentication.exception.ts

@@ -0,0 +1,20 @@
+import { text } from '@rsdk/common';
+
+import { ExceptionsProps, PipelineException } from '../../base';
+import { Exception } from '../../metadata';
+import { ExceptionKind } from '../../types';
+
+@Exception({
+  description: text`
+    General AuthenticationException. Means that system was unable to
+    recognize user or credentials are invalid.
+    
+    Will be translated into 401 (Unauthorized) in HTTP
+    or into 16 (UNAUTHENTICATED) in gRPC context.
+  `,
+})
+export class AuthException extends PipelineException {
+  constructor(message: string, props: ExceptionsProps = {}) {
+    super(ExceptionKind.AUTHENTICATION, message, props);
+  }
+}

package/src/exceptions/implementations/pipeline/conflict.exception.ts

@@ -0,0 +1,21 @@
+import { text } from '@rsdk/common';
+
+import { ExceptionsProps, PipelineException } from '../../base';
+import { Exception } from '../../metadata';
+import { ExceptionKind } from '../../types';
+
+@Exception({
+  description: text`
+    General ConflictException. Means that request was correct by itself, but
+    business rules doesn't allow to peform operation. When it's appropriate
+    use DuplicateEntityException instead (more specific)
+    
+    Will be translated into 409 (Conflict) in HTTP (just as DuplicateEntityException)
+    or into 9 (FAILED_PRECONDITION) in gRPC context.
+  `,
+})
+export class ConflictException extends PipelineException {
+  constructor(message: string, props: ExceptionsProps = {}) {
+    super(ExceptionKind.CONFLICT, message, props);
+  }
+}

package/src/exceptions/implementations/pipeline/duplicate-entity.exception.ts

@@ -0,0 +1,20 @@
+import { text } from '@rsdk/common';
+
+import { ExceptionsProps, PipelineException } from '../../base';
+import { Exception } from '../../metadata';
+import { ExceptionKind } from '../../types';
+
+@Exception({
+  description: text`
+    General DuplicateEntityException. Means that requested operation
+    will lead to duplication, which is forbidden by business rules.
+    
+    Will be translated into 409 (Conflict) in HTTP (just as ConflictException)
+    or into  (ALREADY_EXISTS) in gRPC context.
+  `,
+})
+export class DuplicateEntityException extends PipelineException {
+  constructor(message: string, props: ExceptionsProps = {}) {
+    super(ExceptionKind.DUPLICATION, message, props);
+  }
+}

package/src/exceptions/implementations/pipeline/index.ts

@@ -0,0 +1,9 @@
+export * from './authentication.exception';
+export * from './conflict.exception';
+export * from './duplicate-entity.exception';
+export * from './input.exception';
+export * from './internal.exception';
+export * from './not-allowed.exception';
+export * from './not-found.exception';
+export * from './timeout.exception';
+export * from './validation.exception';

package/src/exceptions/implementations/pipeline/input.exception.ts

@@ -0,0 +1,20 @@
+import { text } from '@rsdk/common';
+
+import { ExceptionsProps, PipelineException } from '../../base';
+import { Exception } from '../../metadata';
+import { ExceptionKind } from '../../types';
+
+@Exception({
+  description: text`
+    General InputException. Means that user input was incorrect.
+    It could be called ValidationException as well.
+    
+    Will be translated into 400 (BadRequest) in HTTP
+    or into 3 (INVALID_ARGUMENT) in gRPC context.
+  `,
+})
+export class InputException extends PipelineException {
+  constructor(message: string, props: ExceptionsProps = {}) {
+    super(ExceptionKind.INPUT, message, props);
+  }
+}

package/src/exceptions/implementations/pipeline/internal.exception.ts

@@ -0,0 +1,20 @@
+import { text } from '@rsdk/common';
+
+import { ExceptionsProps, PipelineException } from '../../base';
+import { Exception } from '../../metadata';
+import { ExceptionKind } from '../../types';
+
+@Exception({
+  description: text`
+    General InternalException. Something happened which was caused by internal
+    problems (user did everything right).
+    
+    Will be translated into 500 (Internal) in HTTP
+    or into 13 (INTERNAL) in gRPC context.
+  `,
+})
+export class InternalException extends PipelineException {
+  constructor(message: string, props: ExceptionsProps = {}) {
+    super(ExceptionKind.INTERNAL, message, props);
+  }
+}

package/src/exceptions/implementations/pipeline/not-allowed.exception.ts

@@ -0,0 +1,20 @@
+import { text } from '@rsdk/common';
+
+import { ExceptionsProps, PipelineException } from '../../base';
+import { Exception } from '../../metadata';
+import { ExceptionKind } from '../../types';
+
+@Exception({
+  description: text`
+    General NotAllowedException. Means that this user can't access specific
+    resource or functionality.
+    
+    Will be translated into 403 (Forbidden) in HTTP
+    or into 7 (PERMISSION_DENIED) in gRPC context.
+  `,
+})
+export class NotAllowedException extends PipelineException {
+  constructor(message: string, props: ExceptionsProps = {}) {
+    super(ExceptionKind.NOT_ALLOWED, message, props);
+  }
+}

package/src/exceptions/implementations/pipeline/not-found.exception.ts

@@ -0,0 +1,20 @@
+import { text } from '@rsdk/common';
+
+import { ExceptionsProps, PipelineException } from '../../base';
+import { Exception } from '../../metadata';
+import { ExceptionKind } from '../../types';
+
+@Exception({
+  description: text`
+    General NotFoundException. It's recommended to create more specific
+    exceptions by deriving BaseException class.
+
+    Will be translated into 404 (NotFound) in HTTP
+    or into 5 (NOT_FOUND) in gRPC context.
+  `,
+})
+export class NotFoundException extends PipelineException {
+  constructor(message: string, props: ExceptionsProps = {}) {
+    super(ExceptionKind.NOT_FOUND, message, props);
+  }
+}

package/src/exceptions/implementations/pipeline/timeout.exception.ts

@@ -0,0 +1,19 @@
+import { text } from '@rsdk/common';
+
+import { ExceptionsProps, PipelineException } from '../../base';
+import { Exception } from '../../metadata';
+import { ExceptionKind } from '../../types';
+
+@Exception({
+  description: text`
+    General TimeoutException.
+    
+    Will be translated into 408 (Request Timeout) in HTTP
+    or into 4 (DEADLINE_EXCEEDED) in gRPC context.
+  `,
+})
+export class TimeoutException extends PipelineException {
+  constructor(message: string, props: ExceptionsProps = {}) {
+    super(ExceptionKind.TIMEOUT, message, props);
+  }
+}

package/src/exceptions/implementations/pipeline/validation.exception.ts

@@ -0,0 +1,9 @@
+import { InputException } from './input.exception';
+
+export class ValidateException extends InputException {
+  constructor(details: unknown) {
+    super('Validation failed', {
+      details,
+    });
+  }
+}

package/src/exceptions/index.ts

@@ -0,0 +1,5 @@
+export * from './base';
+export * from './metadata';
+export * from './types';
+export * from './implementations';
+export { ValidateException } from './validation/exception';

package/src/exceptions/metadata/decorators/exception.decorator.ts

@@ -0,0 +1,10 @@
+import type { ExceptionMetadata } from '../exceptions.registry';
+import { ExceptionsRegistry } from '../exceptions.registry';
+
+export const Exception = (metadata: ExceptionMetadata): ClassDecorator => {
+  // TODO: таргет нужно использовать при регистрации!
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  return function (target: object): void {
+    ExceptionsRegistry.getInstance().register(metadata);
+  };
+};

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

@@ -0,0 +1,2 @@
+export * from './exception.decorator';
+export * from './throws.decorator';

package/src/exceptions/metadata/decorators/throws.decorator.ts

@@ -0,0 +1,25 @@
+import type { Constructor } from '@rsdk/common';
+import { LoggerFactory } from '@rsdk/logging';
+
+import type { PipelineException } from '../../base';
+import { ExceptionsRegistry } from '../exceptions.registry';
+
+const logger = LoggerFactory.create('ExceptionsRegistry');
+
+export const Throws = (
+  ...ex: Constructor<PipelineException>[]
+): MethodDecorator => {
+  return function (ctor: object, methodName: string | symbol) {
+    logger.debug(
+      `Method ${ctor.constructor.name}.${methodName.toString()} throws: ${ex
+        .map((x) => x.name)
+        .join(', ')}`,
+    );
+
+    ExceptionsRegistry.getInstance().register({
+      class: ctor.constructor,
+      exceptions: ex,
+      method: methodName.toString(),
+    });
+  };
+};

package/src/exceptions/metadata/exceptions.registry.ts

@@ -0,0 +1,50 @@
+import type { Constructor } from '@rsdk/common';
+
+import type { PipelineException } from '../base';
+
+export interface ExceptionMetadata {
+  description: string;
+}
+
+export interface ThrowsMetadata {
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  class: Function;
+  method: string;
+  exceptions: Constructor<PipelineException>[];
+}
+
+const isExceptionMeta = (
+  arg: ExceptionMetadata | ThrowsMetadata,
+): arg is ExceptionMetadata => !!(arg as any).description;
+
+export class ExceptionsRegistry {
+  private static _instance: ExceptionsRegistry;
+
+  private exceptions: ExceptionMetadata[] = [];
+  private throws: ThrowsMetadata[] = [];
+
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  private constructor() {}
+
+  static getInstance(): ExceptionsRegistry {
+    if (!this._instance) {
+      this._instance = new ExceptionsRegistry();
+    }
+
+    return this._instance;
+  }
+
+  register(meta: ThrowsMetadata): void;
+  register(meta: ExceptionMetadata): void;
+  register(meta: ThrowsMetadata | ExceptionMetadata): void {
+    if (isExceptionMeta(meta)) {
+      this.exceptions.push(meta);
+    } else {
+      this.throws.push(meta);
+    }
+  }
+
+  getAll(): { exceptions: ExceptionMetadata[]; throws: ThrowsMetadata[] } {
+    return { exceptions: this.exceptions, throws: this.throws };
+  }
+}

package/src/exceptions/metadata/index.ts

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

package/src/exceptions/types.ts

@@ -0,0 +1,18 @@
+/**
+ * Kind helps exception handlers to map exception
+ * to transport-specific one. For example InputException
+ * probably will result 400 HTTP status, while InternalException
+ * - 500
+ */
+export enum ExceptionKind {
+  INPUT = 0,
+  CONFLICT = 1,
+  DUPLICATION = 2,
+  AUTHENTICATION = 3,
+  NOT_ALLOWED = 4,
+  NOT_FOUND = 5,
+  INTERNAL = 6,
+  TIMEOUT = 7,
+  UNAVAILABLE = 8,
+  UNKNOWN = 9,
+}

package/src/exceptions/validation/exception.ts

@@ -0,0 +1,9 @@
+import { InputException } from '../implementations';
+
+export class ValidateException extends InputException {
+  constructor(details: unknown) {
+    super('Validation failed', {
+      details,
+    });
+  }
+}

package/src/exceptions.handling/constants.ts

@@ -0,0 +1,3 @@
+export const FORMATTERS = Symbol('FORMATTERS_TOKEN');
+export const TRANSFORMERS = Symbol('TRANSFORMERS_TOKEN');
+export const SENDERS = Symbol('SENDERS_TOKEN');

package/src/exceptions.handling/global-exceptions.config.ts

@@ -0,0 +1,15 @@
+import { text } from '@rsdk/common';
+
+import { BoolParser, Config, ConfigSection, Property } from '../config';
+
+@ConfigSection()
+export class GlobalExceptionsConfig extends Config {
+  @Property('VERBOSE_ERRORS', new BoolParser(), {
+    defaultValue: true,
+    description: text`
+      If set "true" all exception messages will be returned to client.
+      If false, only 4XX will contain messages, others - just status codes.
+    `,
+  })
+  readonly verbose!: boolean;
+}

package/src/exceptions.handling/global-exceptions.filter.ts

@@ -0,0 +1,81 @@
+import type { ArgumentsHost, ExceptionFilter } from '@nestjs/common';
+import { Catch, Inject } from '@nestjs/common';
+import { normalizer, sortErrorKeys } from '@rsdk/common';
+import { ILogger } from '@rsdk/logging';
+import type { Observable } from 'rxjs';
+import { throwError } from 'rxjs';
+
+import { InternalException, PipelineException } from '../exceptions';
+import { InjectLogger } from '../logging';
+
+import { FORMATTERS, SENDERS, TRANSFORMERS } from './constants';
+import { GlobalExceptionsConfig } from './global-exceptions.config';
+import type {
+  IErrorsFormatter,
+  IErrorsSender,
+  IErrorsTransformer,
+} from './types';
+
+@Catch()
+export class GlobalExceptionsFilter implements ExceptionFilter {
+  constructor(
+    @Inject(FORMATTERS) private readonly formatters: IErrorsFormatter[],
+    @Inject(TRANSFORMERS) private readonly transformers: IErrorsTransformer[],
+    @Inject(SENDERS) private readonly senders: IErrorsSender[],
+    @InjectLogger(GlobalExceptionsFilter)
+    private readonly logger: ILogger,
+    private readonly config: GlobalExceptionsConfig,
+  ) {}
+
+  catch(ex: any, host: ArgumentsHost): Observable<any> {
+    const transformed =
+      ex instanceof PipelineException ? ex : this.transform(ex);
+
+    // Error is transformed to standard PipelineException
+    this.logger.error(transformed);
+
+    const formatted = this.format(host, transformed);
+
+    return this.send(host, formatted);
+  }
+
+  private transform(ex: any): PipelineException {
+    const transformer = this.transformers.find((x) => x.match(ex));
+    if (transformer) {
+      return transformer.transform(ex);
+    }
+
+    const err = new InternalException(ex.message ?? 'UNKNOWN ERROR', ex);
+
+    err.stack = ex.stack;
+
+    return err;
+  }
+
+  private format(host: ArgumentsHost, ex: unknown): unknown {
+    const formatter = this.formatters.find((x) => x.match(host, ex));
+    if (formatter) {
+      this.logger.trace(`Found formatter: ${formatter.constructor.name}`);
+
+      return formatter.format(ex, this.config.verbose);
+    }
+
+    this.logger.trace('No formatter for error!');
+
+    if (this.config.verbose) {
+      return normalizer()(ex, {
+        // This means stacktrace will never be sent to user
+        filterKeys: ['stack'],
+        sortKeys: sortErrorKeys,
+      }) as object;
+    }
+
+    return { message: 'NO FORMATTER' };
+  }
+
+  private send(host: ArgumentsHost, ex: any): Observable<unknown> {
+    const sender = this.senders.find((x) => x.match(host));
+
+    return sender?.send(host, ex) ?? throwError(() => ex);
+  }
+}

package/src/exceptions.handling/global-exceptions.module.ts

@@ -0,0 +1,67 @@
+import type { DynamicModule } from '@nestjs/common';
+import { Module } from '@nestjs/common';
+import { APP_FILTER } from '@nestjs/core';
+
+import { PlatformConfigModule } from '../config';
+
+import { FORMATTERS, SENDERS, TRANSFORMERS } from './constants';
+import { GlobalExceptionsConfig } from './global-exceptions.config';
+import { GlobalExceptionsFilter } from './global-exceptions.filter';
+import type {
+  IErrorsFormatter,
+  IErrorsSender,
+  IErrorsTransformer,
+} from './types';
+
+export interface GlobalExceptionModuleOptions {
+  /**
+   * Formatters are used to transform exceptions to transport specific
+   * final implementations. Usually formatter expects transport agnostic
+   * subclasses of BaseException.
+   */
+  formatters: IErrorsFormatter[];
+
+  /**
+   * Senders are used to actually respond to client (algorithm
+   * is transport specific)
+   */
+  senders: IErrorsSender[];
+
+  /**
+   * Sometimes application throws a lot of unconventional
+   * (not inheriting BaseExceptions). Usually they are throw by
+   * libraries: typeorm, axios, etc. Transformers are used to
+   * catch them and convert to any subtype of BaseException which
+   * will be processed further by transport specific formatters.
+   */
+  transformers?: IErrorsTransformer[];
+}
+
+@Module({})
+export class GlobalExceptionsModule {
+  static forRoot(options: GlobalExceptionModuleOptions): DynamicModule {
+    return {
+      module: GlobalExceptionsModule,
+
+      imports: [PlatformConfigModule.forFeature(GlobalExceptionsConfig)],
+      providers: [
+        {
+          provide: APP_FILTER,
+          useClass: GlobalExceptionsFilter,
+        },
+        {
+          provide: FORMATTERS,
+          useValue: options.formatters,
+        },
+        {
+          provide: SENDERS,
+          useValue: options.senders,
+        },
+        {
+          provide: TRANSFORMERS,
+          useValue: options.transformers || [],
+        },
+      ],
+    };
+  }
+}

package/src/exceptions.handling/index.ts

@@ -0,0 +1,2 @@
+export * from './global-exceptions.module';
+export * from './types';