@rsdk/core 0.14.0

package/src/transport/transport.module.ts

@@ -0,0 +1,64 @@
+import type { DynamicModule } from '@nestjs/common';
+import { flatten } from 'lodash';
+
+import { GlobalExceptionsModule } from '../exceptions.handling';
+import { HealthModule } from '../health';
+import { MetricsModule } from '../metrics';
+import type { PlatformExtendedOptions } from '../types';
+import { isPrimaryTransport } from '../types';
+
+export class PlatformTransportModule {
+  static forOptions(options: PlatformExtendedOptions): DynamicModule {
+    return {
+      imports: [
+        PlatformTransportModule.initHealthchecks(options),
+        PlatformTransportModule.initMetrics(options),
+        PlatformTransportModule.initExceptionsHandling(options),
+      ],
+      module: PlatformTransportModule,
+    };
+  }
+
+  private static initMetrics(options: PlatformExtendedOptions): DynamicModule {
+    const transports = options.transports ?? ([] as any[]);
+
+    return MetricsModule.forRoot({
+      controllers: transports
+        .filter(isPrimaryTransport)
+        .map((x) => x.getMetricsController()),
+    });
+  }
+
+  private static initHealthchecks(
+    options: PlatformExtendedOptions,
+  ): DynamicModule {
+    const transports = options.transports ?? ([] as any[]);
+
+    return HealthModule.forRoot({
+      controllers: transports
+        .filter(isPrimaryTransport)
+        .map((x) => x.getHealthController()),
+    });
+  }
+
+  private static initExceptionsHandling(
+    options: PlatformExtendedOptions,
+  ): DynamicModule {
+    const transports = options.transports ?? [];
+
+    return GlobalExceptionsModule.forRoot({
+      formatters: [
+        ...transports.map((x) => x.getErrorsFormatter()),
+        ...(options.plugins?.map((x) => x.errorFormatter?.()) || []),
+      ].filter((x) => x),
+      senders: [
+        ...transports.map((x) => x.getErrorsSender?.()),
+        ...(options.plugins?.map((x) => x.errorSender?.()) || []),
+      ].filter((x) => x),
+      transformers: [
+        ...flatten(transports.map((x) => x.getErrorTransformers())),
+        ...flatten(options.plugins?.map((x) => x.errorTransformers?.() || [])),
+      ],
+    });
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export * from './metadata';
+export * from './options';
+export * from './transports';
+export * from './plugins';

package/src/types/metadata.ts

@@ -0,0 +1,88 @@
+import type { Primitive } from '@rsdk/common';
+import { hasKey, isPrimitive } from '@rsdk/common';
+
+import type {
+  ParserMetadata,
+  PropertyMetadata,
+  SectionMetadata,
+  SourceMetadata,
+} from '../config';
+
+export type SerializablePropertyMetadata = Omit<
+  PropertyMetadata,
+  'defaultValue' | 'parser'
+> & {
+  defaultValue: Primitive | Primitive[] | undefined;
+  parser: ParserMetadata;
+};
+
+export const serializePropertyMetadata = (
+  metadata: PropertyMetadata,
+): SerializablePropertyMetadata => {
+  const { parser, defaultValue, ...rest } = metadata;
+
+  return {
+    ...rest,
+    parser: {
+      type: parser.type(),
+
+      description: parser.description(),
+    },
+    ...(hasKey(metadata, 'defaultValue') && {
+      // Here we need to serialize Timespans and URLs
+      defaultValue: isPrimitive(defaultValue)
+        ? defaultValue
+        : Array.isArray(defaultValue)
+        ? defaultValue.map((x) => (isPrimitive(x) ? x : x.toString()))
+        : defaultValue?.toString(),
+    }),
+  } as SerializablePropertyMetadata;
+};
+
+export type SerializableSectionMetadata = Omit<
+  SectionMetadata,
+  'properties'
+> & {
+  properties: SerializablePropertyMetadata[];
+};
+
+export const transformSectionMetadata = ({
+  properties,
+  ...rest
+}: SectionMetadata): SerializableSectionMetadata => ({
+  ...rest,
+  // TODO: Если properties переделается в мапу, может быть проблема
+  properties: Object.values(properties).map(serializePropertyMetadata),
+});
+
+export type SerializableConfigMetadata = {
+  prefix: string;
+  sources: SourceMetadata[];
+  sections: SerializableSectionMetadata[];
+  properties: SerializablePropertyMetadata[];
+};
+
+/**
+ * Platfrom metadata is used to generate documentation
+ */
+export interface PlatformAppMetadata {
+  /**
+   * Application name
+   */
+  name: string;
+
+  /**
+   * Application description
+   */
+  description: string;
+
+  /**
+   * Supported protocols
+   */
+  protocols: string[];
+
+  /**
+   * Configuration scheme and options
+   */
+  config: SerializableConfigMetadata;
+}

package/src/types/options.ts

@@ -0,0 +1,83 @@
+import type { Constructor, RequiredFields } from '@rsdk/common';
+
+import type { ConfigModuleOptions } from '../config';
+
+import type { PlatformAppPlugin } from './plugins';
+import type { IPrimaryTransport, ITransport } from './transports';
+
+/**
+ * Not empty collection of modules
+ */
+type Modules = [Constructor, ...Constructor[]];
+
+export interface ManifestData {
+  /**
+   * Application name
+   */
+  name: string;
+
+  /**
+   * Application description
+   */
+  description: string;
+
+  /**
+   * Application version
+   */
+  version: string;
+}
+
+export interface PlatformManifestPathOptions {
+  /**
+   * Path to package.json file. By default will be $(cwd())/package.json
+   */
+  manifestPath?: string;
+}
+
+/**
+ * All application options
+ */
+export interface PlatformOptions extends PlatformManifestPathOptions {
+  /**
+   * Application modules
+   *
+   * Platform creates root module behind the scenes. It
+   * will automatically import all infrastructure modules
+   * such as logging, tracing, error handling etc.
+   *
+   * And finally it will import modules provided here which
+   * should deliver business value.
+   *
+   * NOTE: If you declare global guard or let's say interceptor
+   * via APP_GUARD or APP_INTERCEPTOR in one of your modules, they
+   * will be applied **inside** of internal global middleware.
+   */
+  modules?: Modules;
+
+  /**
+   * Configuration options
+   */
+  config?: Omit<ConfigModuleOptions, 'appName'>;
+
+  /**
+   * Transports are implemented outside @rsdk/core package
+   * Ex: @rsdk/fastify, @platfrom/grpc-server, etc.
+   *
+   * Array of transport must not be empty.
+   * First transport should be primary one (implement health and metrics
+   * endpoints)
+   */
+  transports?: [IPrimaryTransport, ...ITransport[]];
+
+  /**
+   * Plugins extend application functionality.
+   */
+  plugins?: PlatformAppPlugin[];
+}
+
+export type PlatformAppOptions = RequiredFields<
+  PlatformOptions,
+  'transports' | 'modules'
+>;
+
+export type PlatformExtendedOptions = PlatformOptions & ManifestData;

package/src/types/plugins.ts

@@ -0,0 +1,68 @@
+import type { DynamicModule, MiddlewareConsumer } from '@nestjs/common';
+import type { Constructor } from '@rsdk/common';
+
+import type {
+  IErrorsFormatter,
+  IErrorsSender,
+  IErrorsTransformer,
+} from '../exceptions.handling';
+
+export type SpecifiedTransports = Readonly<string[]>;
+export type AppropriateTransports = SpecifiedTransports | 'any';
+
+export const hasSpecifiedTransports = (
+  x: PlatformAppPlugin,
+): x is PlatformAppPlugin<SpecifiedTransports> => x.forTransports() !== 'any';
+
+/**
+ * PlatformApp philosophy assumes that initialization
+ * should not be exposed outside the library. But there
+ * are cases when initialization should be extended from
+ * outside. This is where plugins come in.
+ */
+export interface PlatformAppPlugin<
+  T extends AppropriateTransports = AppropriateTransports,
+> {
+  /**
+   * Returns list of appropriate transports.
+   *
+   * When a plugin is applied, system will check if at
+   * least one of appropriate transports exists in application.
+   * If none - BootstrapException will be thrown
+   *
+   * If plugin is not transport specific - literal "any" should
+   * be returned.
+   */
+  forTransports(): T;
+
+  /**
+   * Modules that will be imported to root. Will be
+   * applied after all core modules but before any application
+   * level modules.
+   */
+  modules?(): (Constructor | DynamicModule)[];
+
+  /**
+   * Additional error transformers
+   */
+  errorTransformers?(): IErrorsTransformer[];
+
+  /**
+   * Additional error formatter
+   */
+  errorFormatter?(): IErrorsFormatter;
+
+  /**
+   * Additional errors sender
+   */
+  errorSender?(): IErrorsSender;
+
+  /**
+   * Apply additional middleware (using MiddlewareConsumer).
+   * Will work only if application has HttpAdapter
+   *
+   * When adding a plugin
+   * @param consumer MiddlewareConsumer
+   */
+  configureMiddleware?(consumer: MiddlewareConsumer): void;
+}

package/src/types/transports.ts

@@ -0,0 +1,110 @@
+import type { Controller, INestApplication } from '@nestjs/common/interfaces';
+import type { AbstractHttpAdapter } from '@nestjs/core';
+import type { MicroserviceOptions } from '@nestjs/microservices';
+import type { Constructor } from '@rsdk/common';
+
+import type {
+  IErrorsFormatter,
+  IErrorsSender,
+  IErrorsTransformer,
+} from '../exceptions.handling';
+
+/**
+ * Base functionality of HTTP or microservice transport
+ */
+export interface ITransport {
+  /**
+   * @returns protocol in text format
+   */
+  getProtocol(): string;
+
+  /**
+   * @returns error formatting algorithm
+   */
+  getErrorsFormatter(): IErrorsFormatter;
+
+  /**
+   * @returns error transformers or empty array
+   */
+  getErrorTransformers(): IErrorsTransformer[];
+
+  /**
+   * @returns sending error algorithm
+   */
+  getErrorsSender?(): IErrorsSender;
+}
+
+/**
+ * Primary transport is transport that implements maintenance
+ * functionality: healthchecks and metrics.
+ *
+ * NOTE: Application should have at least one primary transport.
+ */
+export interface IPrimaryTransport extends ITransport {
+  getHealthController(): Constructor<Controller>;
+  getMetricsController(): Constructor<Controller>;
+}
+
+/**
+ * Transport based on Nest.js microservice.
+ */
+export interface IMicroserviceTransport extends ITransport {
+  /**
+   * @retures options ready to be passed to
+   * NestFactory.createMicroservice() or
+   * app.connectMicroservice()
+   */
+  createMicroserviceOptions(): MicroserviceOptions;
+
+  /**
+   * Should be called before passing options
+   * to app.connectMicroservice()
+   */
+  init(): void;
+
+  /**
+   * Additional logic that will be ran after
+   * microservice is started. Most common use
+   * is logging
+   */
+  onStart(): void;
+}
+
+export interface HttpOptions {
+  host: string;
+  port: number;
+}
+
+/**
+ * HTTP-based transport build on top of some HTTP
+ * adapter.
+ */
+export interface IHttpTransport extends IPrimaryTransport {
+  /**
+   * @returns AbstractHttpAdapter (from @nestjs/core)
+   *
+   * Most common are ExpressAdapter and FastifyAdater,
+   * but custom adapter can be implemented if needed
+   */
+  getAdapter(): AbstractHttpAdapter;
+
+  /**
+   * Applies any configuration to Nest application instance:
+   * middleware, body parsers and other.
+   * @param app INestApplication
+   */
+  configure(app: INestApplication): Promise<void> | void;
+  createHttpOptions(): HttpOptions;
+}
+
+export const isPrimaryTransport = (t: ITransport): t is IPrimaryTransport =>
+  typeof (t as IPrimaryTransport).getHealthController === 'function' &&
+  typeof (t as IPrimaryTransport).getMetricsController === 'function';
+
+export const isHttpTransport = (t: ITransport): t is IHttpTransport =>
+  t.getProtocol() === 'http';
+
+export const isMicroserviceTransport = (
+  t: ITransport,
+): t is IMicroserviceTransport =>
+  typeof (t as IMicroserviceTransport).createMicroserviceOptions === 'function';

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+
+  "extends": "@rsdk/tsconfig/base.json",
+  "compilerOptions": {
+    "declaration": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test", "**/*spec.ts"]
+}