@rsdk/nats.transport 5.4.0-next.2

package/src/server.ts

@@ -0,0 +1,491 @@
+import type {
+  CustomTransportStrategy,
+  MessageHandler,
+} from '@nestjs/microservices';
+import { Server } from '@nestjs/microservices';
+import type { NatsJetStreamServerOptions } from '@nestjs-plugins/nestjs-nats-jetstream-transport';
+import {
+  NATS_JETSTREAM_TRANSPORT,
+  NatsContext,
+  NatsJetStreamContext,
+} from '@nestjs-plugins/nestjs-nats-jetstream-transport';
+import { InternalException, NotFoundException } from '@rsdk/core';
+import type { EventType } from '@rsdk/events.common';
+import { isEventType, X_TYPE_HEADER } from '@rsdk/events.common';
+import { LoggerFactory } from '@rsdk/logging';
+import { getStreamName } from '@rsdk/nats.common';
+import { isEqual } from 'lodash';
+import type {
+  Consumer,
+  ConsumerConfig,
+  JetStreamClient,
+  JetStreamManager,
+  NatsConnection,
+  SubscriptionOptions,
+} from 'nats';
+import { connect } from 'nats';
+import { connectable, isObservable, Subject } from 'rxjs';
+
+import type { ConsumerInfo } from './types/consumer-info.type';
+import type { ConsumersMap } from './types/consumers-map.type';
+import type { EventTypeWithOptions } from './types/event-type-with-options.type';
+import type { Mapping } from './types/mapping.type';
+import { EventsDeserializer } from './events.deserializer';
+
+/**
+ * Класс, реализующий сервер NATS JetStream.
+ */
+export class NatsJetStreamServer
+  extends Server
+  implements CustomTransportStrategy
+{
+  readonly transportId = NATS_JETSTREAM_TRANSPORT;
+  override logger = LoggerFactory.create('NatsJetStreamServer');
+  override readonly deserializer = new EventsDeserializer();
+  private nc?: NatsConnection;
+  private jsm?: JetStreamManager;
+  private readonly streams = new Set<string>();
+
+  private readonly normalizedApplicationName: string;
+  private readonly autoUpdateConsumers: boolean;
+
+  /**
+   * Конструктор класса NatsJetStreamServer.
+   * @param options - Опции для подключения к NATS JetStream.
+   * @param config - Конфигурация приложения.
+   */
+  constructor(
+    private readonly options: NatsJetStreamServerOptions,
+    private readonly config: {
+      appName: string;
+      autoUpdateConsumers?: boolean;
+    },
+  ) {
+    super();
+    this.normalizedApplicationName = config.appName.replaceAll('.', '-');
+    this.autoUpdateConsumers = Boolean(config.autoUpdateConsumers);
+  }
+
+  static isNatsContext(
+    maybeNatsContext: unknown,
+  ): maybeNatsContext is NatsJetStreamContext {
+    return maybeNatsContext instanceof NatsJetStreamContext;
+  }
+
+  /**
+   * Запускает сервер и устанавливает соединение.
+   * @param callback - Функция обратного вызова для выполнения после подключения.
+   */
+  async listen(callback: () => void): Promise<void> {
+    if (!this.nc) {
+      this.nc = await connect(this.options.connectionOptions);
+      this.options.connectionOptions!.connectedHook?.(this.nc);
+    }
+    this.jsm = await this.nc.jetstreamManager(this.options.jetStreamOptions);
+
+    await this.bindEventHandlers();
+    this.bindMessageHandlers();
+    callback();
+  }
+
+  /**
+   * Закрывает соединение с сервером.
+   */
+  async close(): Promise<void> {
+    await this.nc?.drain();
+    delete this.nc;
+  }
+
+  /**
+   * Добавляет обработчик сообщения.
+   * @param pattern Шаблон для сообщения.
+   * @param callback Функция-обработчик сообщения.
+   * @param isEventHandler Указывает, является ли обработчик обработчиком событий.
+   * @param extras Дополнительные параметры.
+   */
+  public override addHandler(
+    pattern: any,
+    callback: MessageHandler,
+    isEventHandler = false,
+    extras: Record<string, any> = {},
+  ): void {
+    const eventType = this.getEventType(pattern);
+    let formattedPattern: string;
+
+    if (isEventType(eventType)) {
+      this.streams.add(this.getStreamName(pattern));
+      formattedPattern = eventType.$type;
+      this.deserializer.events.set(formattedPattern, pattern);
+    } else if (typeof eventType === 'string') {
+      formattedPattern = eventType;
+      this.streams.add(eventType);
+    }
+
+    super.addHandler(formattedPattern!, callback, isEventHandler, extras);
+  }
+
+  /**
+   * Получает тип события из шаблона.
+   * @param pattern - Шаблон для получения типа события.
+   * @returns Тип события.
+   */
+  private getEventType(pattern: any): any {
+    return typeof pattern === 'object' && 'eventType' in pattern
+      ? pattern.eventType
+      : pattern;
+  }
+
+  /**
+   * Связывает обработчики событий.
+   */
+  private async bindEventHandlers(): Promise<void> {
+    const eventHandlers = [...this.messageHandlers.entries()].filter(
+      ([, handler]) => handler.isEventHandler,
+    );
+
+    if (!this.nc) {
+      throw new InternalException('Connection must be established');
+    }
+    const js = this.nc.jetstream(this.options.jetStreamOptions);
+
+    const { orderedConsumers, unorderedConsumers } =
+      this.groupHandlersByOrderType(eventHandlers);
+
+    for (const [consumerName, consumer] of orderedConsumers) {
+      await this.createConsumer(js, consumerName, consumer, {
+        max_ack_pending: 1,
+      });
+    }
+
+    for (const [consumerName, consumer] of unorderedConsumers) {
+      await this.createConsumer(js, consumerName, consumer, {});
+    }
+  }
+
+  /**
+   * Группирует обработчики по типу порядка (зависимые и независимые от порядка).
+   *
+   * @param {Array<[string, MessageHandler<any, any, any>]>} eventHandlers - Список обработчиков событий,
+   * где каждый элемент представляет собой кортеж из метаданных и обработчика.
+   *
+   * @returns {{
+   *   orderedConsumers: ConsumersMap,
+   *   unorderedConsumers: ConsumersMap
+   * }}
+   * Объект, содержащий две карты:
+   * - orderedConsumers: карта с зависимыми от порядка consumer'ами.
+   * - unorderedConsumers: карта с независимыми от порядка consumer'ами.
+   */
+  private groupHandlersByOrderType(
+    eventHandlers: [string, MessageHandler<any, any, any>][],
+  ): { orderedConsumers: ConsumersMap; unorderedConsumers: ConsumersMap } {
+    const orderedConsumers: ConsumersMap = new Map();
+    const unorderedConsumers: ConsumersMap = new Map();
+
+    for (const [meta, handler] of eventHandlers) {
+      const deserializer = this.deserializer.events.get(meta)!;
+      const consumerName = this.getConsumerName(deserializer);
+      const streamName = this.getStreamName(deserializer);
+
+      const targetMap = deserializer.options?.maxAckPending
+        ? orderedConsumers
+        : unorderedConsumers;
+
+      const aggregatedConsumer = targetMap.get(consumerName) ?? {
+        streamName,
+        mapping: new Map() as Mapping,
+      };
+
+      aggregatedConsumer.mapping.set(this.getTypePart(deserializer.eventType), {
+        deserializer,
+        handler,
+      });
+      targetMap.set(consumerName, aggregatedConsumer);
+    }
+
+    return { orderedConsumers, unorderedConsumers };
+  }
+
+  /**
+   * Получает информацию о консьюмере.
+   * @param js - Клиент JetStream.
+   * @param streamName - Имя потока.
+   * @param consumerName - Имя консьюмера.
+   * @returns Информация о консьюмере.
+   */
+  private async getConsumer(
+    js: JetStreamClient,
+    streamName: string,
+    consumerName: string,
+  ): Promise<Consumer> {
+    return js.consumers.get(streamName, consumerName);
+  }
+
+  /**
+   * Создаёт консьюмера для заданного потока.
+   * @param js - Клиент JetStream.
+   * @param consumerName - Имя консьюмера.
+   * @param consumer - Информация о консьюмере.
+   * @param options - Дополнительные параметры конфигурации консьюмера.
+   */
+  private async createConsumer(
+    js: JetStreamClient,
+    consumerName: string,
+    { streamName, mapping }: ConsumerInfo,
+    options: Partial<ConsumerConfig>,
+  ): Promise<void> {
+    try {
+      await js.streams.get(streamName);
+      this.logger.trace('Stream %s found', { streamName });
+    } catch (error) {
+      this.logger.error('Stream %s not found', { streamName });
+      throw new InternalException(`Stream not found: ${streamName}`, {
+        cause: error,
+      });
+    }
+
+    const jsm = await js.jetstreamManager();
+    const expectedSubjects: string[] = [...mapping.values()].flatMap((e) =>
+      this.getEventSubjects(e.deserializer),
+    );
+
+    const consumer: Consumer =
+      (await this.getConsumer(js, streamName, consumerName).catch(
+        () => null,
+      )) ??
+      (await jsm.consumers
+        .add(streamName, {
+          ...options,
+          durable_name: consumerName,
+          filter_subjects: expectedSubjects,
+        })
+        .then(() => this.getConsumer(js, streamName, consumerName)));
+
+    const info = await consumer.info();
+    const receivedSubjects = info.config.filter_subjects;
+
+    await this.handleCorrectness(
+      jsm,
+      streamName,
+      consumerName,
+      expectedSubjects,
+      receivedSubjects,
+    );
+
+    this.handleMessages(consumer, mapping, consumerName);
+  }
+
+  /**
+   * Обрабатывает сообщения из консьюмера.
+   * @param consumer - Консьюмер для обработки сообщений.
+   * @param mapping - Соответствия между типами сообщений и обработчиками.
+   * @param consumerName - Имя консьюмера.
+   */
+  private async handleMessages(
+    consumer: Consumer,
+    mapping: Mapping,
+    consumerName: string,
+  ): Promise<void> {
+    const msgs = await consumer.consume();
+
+    /**
+     * Слушаем все сообщения консьюмера
+     * @type {Promise<void>}
+     */
+    const done = (async (): Promise<void> => {
+      for await (const msg of msgs) {
+        try {
+          const data = this.deserializer.deserialize(msg);
+          const context = new NatsJetStreamContext([msg]);
+          const contract = mapping.get(this.getTypePart(data.pattern));
+
+          if (!contract) {
+            throw new NotFoundException(`Unknown ${X_TYPE_HEADER} header`);
+          }
+
+          const resultOrStream = await contract.handler(data, context);
+          if (isObservable(resultOrStream)) {
+            const connectableSource = connectable(resultOrStream, {
+              connector: () => new Subject(),
+              resetOnDisconnect: false,
+            });
+
+            connectableSource.connect();
+          }
+        } catch (error: any) {
+          this.logger.error(error.message, error.stack);
+          // specifies that you failed to process the server and instructs
+          // the server to not send it again (to any consumer)
+          msg.term();
+          continue;
+        }
+
+        /**
+         * Потенциально мы можем сюда придти если в одном консюьмере несколько сервисов
+         * Это не совсем корректное поведение потому что неясно есть ли такой обработчик, а мы можем встрять и ни разу не двинуть оффсет
+         */
+        msg.nak();
+        this.logger.warn('Unhandled message: ', { msg });
+      }
+    })();
+
+    done.then(() => {
+      if (this.nc?.isDraining() || this.nc?.isClosed()) {
+        return;
+      }
+
+      this.logger.debug(`Unsubscribed ${consumerName}`);
+    });
+  }
+
+  /**
+   * Проверяет корректность подписки консьюмера.
+   * @param jsm - Менеджер JetStream.
+   * @param streamName - Имя потока.
+   * @param consumerName - Имя консьюмера.
+   * @param expectedSubjects - Ожидаемые темы.
+   * @param receivedSubjects - Полученные темы.
+   */
+  private async handleCorrectness(
+    jsm: JetStreamManager,
+    streamName: string,
+    consumerName: string,
+    expectedSubjects: string[],
+    receivedSubjects: string[] | undefined,
+  ): Promise<void> {
+    if (isEqual(receivedSubjects, expectedSubjects)) {
+      return;
+    }
+    if (!this.autoUpdateConsumers) {
+      throw new InternalException('Incorrect subjects', {
+        cause: {
+          expectedSubjects,
+          receivedSubjects,
+        },
+      });
+    }
+    await jsm.consumers.update(streamName, consumerName, {
+      filter_subjects: expectedSubjects,
+    });
+  }
+
+  /**
+   * Связывает обработчики сообщений.
+   */
+  private bindMessageHandlers(): void {
+    const messageHandlers = [...this.messageHandlers.entries()].filter(
+      ([, handler]) => !handler.isEventHandler,
+    );
+
+    for (const [subject, messageHandler] of messageHandlers) {
+      const subscriptionOptions: SubscriptionOptions = {
+        callback: async (err, msg) => {
+          if (err) {
+            this.logger.error(err.message, err);
+            return;
+          }
+          const payload = this.deserializer.deserialize(msg);
+          const context = new NatsContext([msg]);
+          const response$ = this.transformToObservable(
+            messageHandler(payload.data, context),
+          );
+
+          this.send(response$, (response) =>
+            msg.respond(response as Uint8Array),
+          );
+        },
+      };
+
+      this.nc?.subscribe(subject, subscriptionOptions);
+      this.logger.debug(`Subscribed to ${subject} messages`);
+    }
+  }
+
+  /**
+   * Настраивает поток для сервера.
+   */
+  private async setupStream(): Promise<void> {
+    const { streamConfig } = this.options;
+    const streams = await this.jsm?.streams.list().next();
+
+    const reqStreamConfigs = Array.isArray(streamConfig)
+      ? streamConfig
+      : [streamConfig];
+
+    for (const requiredStreamConfig of reqStreamConfigs) {
+      if (!requiredStreamConfig) {
+        continue;
+      }
+      const stream = streams?.find(
+        (stream) => stream.config.name === requiredStreamConfig?.name,
+      );
+
+      if (stream) {
+        const streamSubjects = new Set([
+          ...stream.config.subjects,
+          ...(requiredStreamConfig?.subjects ?? []),
+        ]);
+
+        const streamInfo = await this.jsm?.streams.update(stream.config.name, {
+          ...stream.config,
+          ...requiredStreamConfig,
+          subjects: [...streamSubjects.keys()],
+        });
+
+        this.logger.info(`Stream ${streamInfo?.config.name} updated`);
+      } else {
+        const streamInfo = await this.jsm?.streams.add(requiredStreamConfig);
+
+        this.logger.info(`Stream ${streamInfo?.config.name} created`);
+      }
+    }
+  }
+
+  /**
+   * Получает имя потока для десериализатора.
+   * @param contract - Десериализатор событий.
+   * @returns Имя потока.
+   */
+  private getStreamName(contract: EventTypeWithOptions): string {
+    return contract.options?.streamName ?? getStreamName(contract.eventType);
+  }
+
+  /**
+   * Получает имя консьюмера по десериализатору.
+   * @param contract - Десериализатор событий.
+   * @returns Имя консьюмера.
+   */
+  private getConsumerName(contract: EventTypeWithOptions): string {
+    const arr = [
+      this.normalizedApplicationName,
+      this.getStreamName(contract),
+      'consumer',
+    ];
+
+    if (contract.options?.consumerName) {
+      arr.unshift(contract.options.consumerName);
+    }
+
+    return arr.join('-');
+  }
+
+  /**
+   * Получает темы событий для десериализатора.
+   * @param contract - Десериализатор событий.
+   * @returns Темы событий.
+   */
+  private getEventSubjects(contract: EventTypeWithOptions): string[] {
+    return contract.options?.subjects ?? [];
+  }
+
+  /**
+   * Получает часть типа события.
+   * @param eventType - Тип события.
+   * @returns Часть типа.
+   */
+  private getTypePart(eventType: EventType | string): string {
+    return (
+      typeof eventType === 'string' ? eventType : eventType.$type
+    ).replaceAll('.', '-');
+  }
+}

package/src/types/consume.options.ts

@@ -0,0 +1,6 @@
+export type ConsumeOptions = {
+  streamName?: string;
+  subjects?: string[];
+  maxAckPending?: number;
+  consumerName?: string;
+};

package/src/types/consumer-info.type.ts

@@ -0,0 +1,6 @@
+import type { Mapping } from './mapping.type';
+
+export type ConsumerInfo = {
+  streamName: string;
+  mapping: Mapping;
+};

package/src/types/consumers-map.type.ts

@@ -0,0 +1,3 @@
+import type { ConsumerInfo } from './consumer-info.type';
+
+export type ConsumersMap = Map<string, ConsumerInfo>;

package/src/types/event-type-with-options.type.ts

@@ -0,0 +1,8 @@
+import type { EventType } from '@rsdk/events.common';
+
+import type { ConsumeOptions } from './consume.options';
+
+export type EventTypeWithOptions = {
+  eventType: EventType;
+  options?: ConsumeOptions;
+};

package/src/types/mapping.type.ts

@@ -0,0 +1,8 @@
+import type { MessageHandler } from '@nestjs/microservices';
+
+import type { EventTypeWithOptions } from './event-type-with-options.type';
+
+export type Mapping = Map<
+  string,
+  { deserializer: EventTypeWithOptions; handler: MessageHandler }
+>;

package/src/types/nats-jetstream-transport-options.type.ts

@@ -0,0 +1,3 @@
+import type { NatsJetStreamServerOptions } from '@nestjs-plugins/nestjs-nats-jetstream-transport';
+
+export type NatsJetstreamTransportOptions = Partial<NatsJetStreamServerOptions>;

package/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": [
+    "node_modules",
+    "dist",
+    "test",
+    "**/*.spec.ts",
+    "**/*.test.ts",
+    "**/*.test.e2e.ts",
+    "**/*.test.manual-e2e.ts",
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@rsdk/tsconfig/base.json",
+  "compilerOptions": {
+    "declaration": true,
+    "outDir": "dist"
+  }
+}