@rsdk/logging 5.10.0 → 5.10.1-next.1

package/dist/metadata/logger-metadata.registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger-metadata.registry.js","sourceRoot":"","sources":["../../src/metadata/logger-metadata.registry.ts"],"names":[],"mappings":";;;AAIA,MAAa,sBAAsB;IACzB,MAAM,CAAU,WAAW,GAAG,IAAI,GAAG,EAG1C,CAAC;IAEJ,MAAM,CAAC,kBAAkB,CACvB,MAAmB,EACnB,QAAkC;QAElC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED,MAAM,CAAC,cAAc;QACnB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/C,CAAC;;AAfH,wDAgBC"}

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { Constructor } from '@rsdk/common';
 import type pino from 'pino';
+import type { TransportMultiOptions } from 'pino';
 export declare enum LogLevel {
     fatal = "fatal",
     error = "error",
@@ -8,11 +9,33 @@ export declare enum LogLevel {
     debug = "debug",
     trace = "trace"
 }
+export declare enum LogTimestampFormat {
+    epochTime = "epochTime",
+    unixTime = "unixTime",
+    nullTime = "nullTime",
+    isoTime = "isoTime"
+}
+export type TimeFn = () => string;
 export type Params = Record<string, unknown>;
-export interface LoggerOptions {
+export interface LoggerOptionsBase {
     level: LogLevel;
     redact: string[];
-    stream: pino.DestinationStream;
+    timestampFormat: LogTimestampFormat;
 }
+/**
+ * `stream` и `transport` — взаимоисключающие способы доставки (pino не
+ * принимает оба сразу). Это закодировано в типе: задание одного запрещает
+ * другой.
+ */
+export type LoggerOptions = LoggerOptionsBase & ({
+    stream?: pino.DestinationStream;
+    transport?: never;
+} | {
+    stream?: never;
+    transport?: TransportMultiOptions;
+});
 export type LoggingContext = string | Constructor;
 export type OnMessage = (level: LogLevel, data: Record<string, unknown>) => void;
+export interface LoggerSerializerMetadata {
+    target: Constructor;
+}

package/dist/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogLevel = void 0;
+exports.LogTimestampFormat = exports.LogLevel = void 0;
 var LogLevel;
 (function (LogLevel) {
     LogLevel["fatal"] = "fatal";
@@ -10,4 +10,11 @@ var LogLevel;
     LogLevel["debug"] = "debug";
     LogLevel["trace"] = "trace";
 })(LogLevel || (exports.LogLevel = LogLevel = {}));
+var LogTimestampFormat;
+(function (LogTimestampFormat) {
+    LogTimestampFormat["epochTime"] = "epochTime";
+    LogTimestampFormat["unixTime"] = "unixTime";
+    LogTimestampFormat["nullTime"] = "nullTime";
+    LogTimestampFormat["isoTime"] = "isoTime";
+})(LogTimestampFormat || (exports.LogTimestampFormat = LogTimestampFormat = {}));
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAGA,IAAY,QAOX;AAPD,WAAY,QAAQ;IAClB,2BAAe,CAAA;IACf,2BAAe,CAAA;IACf,yBAAa,CAAA;IACb,yBAAa,CAAA;IACb,2BAAe,CAAA;IACf,2BAAe,CAAA;AACjB,CAAC,EAPW,QAAQ,wBAAR,QAAQ,QAOnB"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAIA,IAAY,QAOX;AAPD,WAAY,QAAQ;IAClB,2BAAe,CAAA;IACf,2BAAe,CAAA;IACf,yBAAa,CAAA;IACb,yBAAa,CAAA;IACb,2BAAe,CAAA;IACf,2BAAe,CAAA;AACjB,CAAC,EAPW,QAAQ,wBAAR,QAAQ,QAOnB;AAED,IAAY,kBAKX;AALD,WAAY,kBAAkB;IAC5B,6CAAuB,CAAA;IACvB,2CAAqB,CAAA;IACrB,2CAAqB,CAAA;IACrB,yCAAmB,CAAA;AACrB,CAAC,EALW,kBAAkB,kCAAlB,kBAAkB,QAK7B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsdk/logging",
-  "version": "5.10.0",
+  "version": "5.10.1-next.1",
   "description": "Base framework independent logging functionality",
   "license": "Apache License 2.0",
   "publishConfig": {
@@ -11,11 +11,12 @@
   },
   "main": "dist/index.js",
   "dependencies": {
-    "pino": "^8.0.0 || ^9.0.0"
+    "pino": "^8.0.0 || ^9.0.0",
+    "reflect-metadata": "^0.1.12 || ^0.2.0"
   },
   "peerDependencies": {
     "@rsdk/common": "*",
     "rxjs": "^7.1.0"
   },
-  "gitHead": "02b07a4fd5e0bc3894b043a662f5a1faad82618d"
+  "gitHead": "793a6c54dc689007b86a8a817d0ed198ee83ec5d"
 }

package/src/decorators/log-serializer.decorator.ts

@@ -0,0 +1,21 @@
+import type { Constructor } from '@rsdk/common';
+
+import 'reflect-metadata';
+
+import { LOGGER_METADATA_KEY } from '../metadata/constants';
+import { LoggerMetadataRegistry } from '../metadata/logger-metadata.registry';
+import type { LoggerSerializerMetadata } from '../types';
+
+const logSerializerDecorator: ClassDecorator = function (
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  target: Function,
+): void {
+  const metadata: LoggerSerializerMetadata = {
+    target: target as Constructor,
+  };
+
+  Reflect.defineMetadata(LOGGER_METADATA_KEY, metadata, target);
+  LoggerMetadataRegistry.registerSerializer(target as Constructor, metadata);
+};
+
+export const LogSerializer = (): ClassDecorator => logSerializerDecorator;

package/src/implementations/pino-logger.class.ts

@@ -1,9 +1,9 @@
-import type { ErrorLike, NormalizeOptions } from '@rsdk/common';
-import { isErrorLike, normalizer, sortErrorKeys } from '@rsdk/common';
+import type { ErrorLike } from '@rsdk/common';
+import { isErrorLike } from '@rsdk/common';
 import type { Logger as Pino } from 'pino';
 
 import { stringifyContext } from '../helpers';
-import type { ILogger } from '../logger.interface';
+import type { ILogger, LogSerializerBase } from '../logger.interface';
 import type { LoggingContext, OnMessage, Params } from '../types';
 import { LogLevel } from '../types';
 
@@ -23,11 +23,18 @@ export class PinoLogger implements ILogger {
    */
   private readonly _pino: GetLogger;
   private readonly emit: OnMessage;
-
-  constructor(pino: GetLogger, emit: OnMessage, context: LoggingContext) {
+  private readonly getSerializers: () => LogSerializerBase[];
+
+  constructor(
+    pino: GetLogger,
+    emit: OnMessage,
+    context: LoggingContext,
+    getSerializers: () => LogSerializerBase[],
+  ) {
     this._pino = pino;
     this.emit = emit;
     this.context = stringifyContext(context);
+    this.getSerializers = getSerializers;
   }
 
   get pino(): Pino {
@@ -106,20 +113,42 @@ export class PinoLogger implements ILogger {
     }
 
     const paramsOrError = typeof arg1 === 'string' ? arg2 : arg1;
-
     if (paramsOrError) {
-      const options: NormalizeOptions = {
-        sortKeys: sortErrorKeys,
-      };
-
       if (level === 'fatal' || level === 'error') {
-        args['error'] = normalizer()(paramsOrError, options);
+        args.error = paramsOrError;
       } else {
-        Object.assign(args, normalizer()(paramsOrError, options));
+        Object.assign(args, paramsOrError);
+      }
+    }
+
+    if (message) {
+      args.message = message;
+    }
+
+    const serializers = this.getSerializers();
+
+    for (const [key, value] of Object.entries(args)) {
+      // Пропускаем ненужные поля
+      if (key === 'context' || key === 'message') continue;
+      if (value == null || typeof value !== 'object') continue;
+
+      for (const serializer of serializers) {
+        try {
+          // eslint-disable-next-line unicorn/prefer-regexp-test
+          if (serializer.match(value)) {
+            const serialized = serializer.serialize(value);
+            if (serialized && typeof serialized === 'object') {
+              args[key] = serialized;
+            }
+
+            // Можно прервать цикл — нашли нужный сериалайзер
+            break;
+          }
+        } catch {}
       }
     }
 
-    this.emit(level, { ...args, message });
-    this.pino[level](args, message);
+    this.emit(level, args);
+    this.pino[level](args);
   }
 }

package/src/index.ts

@@ -1,7 +1,16 @@
 export { DEFAULT_LEVEL } from './defaults';
 
-export * from './implementations';
-export * from './types';
-export * from './logger.interface';
-export * from './helpers';
-export * from './logger.factory';
+export { PinoLogger } from './implementations/pino-logger.class';
+export {
+  LogLevel,
+  Params,
+  LoggerOptions,
+  LoggingContext,
+  OnMessage,
+  LoggerSerializerMetadata,
+  LogTimestampFormat,
+} from './types';
+export { ILogger, ILogSerializer, LogSerializerBase } from './logger.interface';
+export { stringifyContext } from './helpers';
+export { LoggerFactory } from './logger.factory';
+export { LogSerializer } from './decorators/log-serializer.decorator';

package/src/logger.factory.ts

@@ -1,21 +1,44 @@
-import EventEmitter from 'node:events';
+import { EventEmitter } from 'node:events';
 import type _pino from 'pino';
-import type { Logger as Pino } from 'pino';
+import type {
+  DestinationStream,
+  Logger as Pino,
+  LoggerOptions as LoggerOptsPino,
+  TransportMultiOptions,
+} from 'pino';
 
+import { LoggerMetadataRegistry } from './metadata/logger-metadata.registry';
 import { DEFAULT_LEVEL } from './defaults';
 import { PinoLogger } from './implementations';
-import type { ILogger } from './logger.interface';
+import type { ILogger, LogSerializerBase } from './logger.interface';
 import type {
   LoggerOptions,
+  LoggerOptionsBase,
+  LoggerSerializerMetadata,
   LoggingContext,
   LogLevel,
   OnMessage,
+  TimeFn,
 } from './types';
+import { LogTimestampFormat } from './types';
+
+/** Хэндл worker-транспорта pino (thread-stream) для teardown воркеров. */
+interface TransportStream extends DestinationStream {
+  end(): void;
+  flush(cb?: (err?: Error) => void): void;
+  flushSync(): void;
+  unref(): void;
+  on(event: string, listener: (...args: unknown[]) => void): void;
+  removeAllListeners(event?: string): void;
+}
+
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 1000;
 
 /**
  * ATTENTION: require('pino') тут не просто так, в общем они нужны для корректной работы хуков из `@opentelemetry/instrumentation-pino`
  */
 const requirePino = (): typeof _pino => {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
   return require('pino');
 };
 
@@ -25,7 +48,21 @@ const requirePino = (): typeof _pino => {
  */
 export class LoggerFactory {
   // eslint-disable-next-line unicorn/prefer-event-target
-  private static events = new EventEmitter();
+  private static readonly events = new EventEmitter();
+
+  private static opts: LoggerOptions = {
+    level: DEFAULT_LEVEL,
+    redact: [],
+    stream: requirePino().destination(),
+    timestampFormat: LogTimestampFormat.isoTime,
+  };
+
+  private static pinoTimestampFormatMap: Record<LogTimestampFormat, TimeFn> = {
+    [LogTimestampFormat.epochTime]: requirePino().stdTimeFunctions.epochTime,
+    [LogTimestampFormat.unixTime]: requirePino().stdTimeFunctions.unixTime,
+    [LogTimestampFormat.nullTime]: requirePino().stdTimeFunctions.nullTime,
+    [LogTimestampFormat.isoTime]: requirePino().stdTimeFunctions.isoTime,
+  };
 
   /**
    * Under the hood every logger instance will use this
@@ -36,16 +73,19 @@ export class LoggerFactory {
    * Downside is that the idea is not composable with child
    * loggers (which are no used anywhere yet)
    */
-  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
   private static _globalPino: Pino = requirePino()({
     level: DEFAULT_LEVEL,
+    timestamp: this.pinoTimestampFormatMap[this.opts.timestampFormat],
   });
 
-  private static opts: LoggerOptions = {
-    level: DEFAULT_LEVEL,
-    redact: [],
-    stream: requirePino().destination(),
-  };
+  private static _serializers: Map<string, LogSerializerBase> | null = null;
+
+  /** Ссылка на активный worker-транспорт для закрытия его воркеров. */
+  private static _activeTransport: TransportStream | null = null;
+
+  /** Конфиг, по которому собран _activeTransport (для переиспользования воркера). */
+  private static _activeTransportConfig: TransportMultiOptions | null = null;
 
   /**
    * Переконфигурация pino нужна потому, что изначально логгер инициализируется
@@ -57,9 +97,7 @@ export class LoggerFactory {
   static reconfigure(opts: Partial<LoggerOptions>): void {
     this.applyOptions(opts);
 
-    const { stream, ...other } = this.opts;
-
-    this._globalPino = requirePino()(other, stream);
+    this._globalPino = this.instantiatePino();
   }
 
   /**
@@ -80,43 +118,64 @@ export class LoggerFactory {
   static applyInstrumentations<T extends Record<string, any>>(
     logHookFunction?: (record: T) => void,
   ): void {
-    const { stream, ...other } = this.opts;
-
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    this._globalPino = requirePino()(
-      {
-        ...other,
-
-        /**
-         * Функция которая позволяет добавить дополнительные данные в логи Pino
-         */
-        hooks: logHookFunction
-          ? {
-              /**
-               * Реализация взята с официальной документации
-               * https://getpino.io/#/docs/api?id=logmethod
-               */
-              logMethod: function (
-                inputArgs: any[],
-                // eslint-disable-next-line @typescript-eslint/ban-types
-                method: Function,
-              ): unknown {
-                if (inputArgs.length >= 2) {
-                  const arg1: T = inputArgs.shift() || {};
-                  const arg2 = inputArgs.shift();
-
-                  logHookFunction(arg1);
-
-                  // eslint-disable-next-line unicorn/prefer-reflect-apply
-                  return method.apply(this, [arg1, arg2, ...inputArgs]);
-                }
-                return method.apply(this, inputArgs);
-              },
-            }
-          : {},
-      },
-      stream,
-    );
+    this._globalPino = this.instantiatePino({
+      /**
+       * Функция которая позволяет добавить дополнительные данные в логи Pino
+       */
+      hooks: logHookFunction
+        ? {
+            /**
+             * Реализация взята с официальной документации
+             * https://getpino.io/#/docs/api?id=logmethod
+             */
+            // eslint-disable-next-line @typescript-eslint/ban-types
+            logMethod: function (inputArgs: any[], method: Function): unknown {
+              const arg1 = inputArgs[0];
+              if (arg1 && typeof arg1 === 'object') {
+                logHookFunction(arg1 as T);
+              }
+              // eslint-disable-next-line unicorn/prefer-reflect-apply
+              return method.apply(this, inputArgs);
+            },
+          }
+        : {},
+    });
+  }
+
+  /**
+   * Сливает буфер worker-транспорта и завершает его воркеры. Без вызова на
+   * остановке приложения забуференные логи теряются, а воркеры висят.
+   */
+  static async shutdown(
+    timeoutMs: number = DEFAULT_SHUTDOWN_TIMEOUT_MS,
+  ): Promise<void> {
+    const stream = this._activeTransport;
+
+    if (!stream) return;
+
+    this._activeTransport = null;
+    this._activeTransportConfig = null;
+
+    await new Promise<void>((resolve) => {
+      let settled = false;
+
+      const finish = (): void => {
+        if (settled) return;
+        settled = true;
+        resolve();
+      };
+
+      try {
+        stream.on('close', finish);
+        stream.flush(() => stream.end());
+      } catch {
+        finish();
+      }
+
+      const timer = setTimeout(finish, timeoutMs);
+
+      timer.unref?.();
+    });
   }
 
   static onMessage(handler: OnMessage): void {
@@ -128,12 +187,187 @@ export class LoggerFactory {
       () => this._globalPino,
       (level: LogLevel, data: unknown) => this.events.emit('msg', level, data),
       context,
+      () => this.getSerializers(),
     );
   }
 
+  static getSerializers(): LogSerializerBase[] {
+    if (this._serializers) return Array.from(this._serializers.values());
+
+    const metas: LoggerSerializerMetadata[] =
+      LoggerMetadataRegistry.getSerializers();
+
+    this._serializers = new Map<string, LogSerializerBase>();
+
+    for (const meta of metas) {
+      try {
+        const instance = Reflect.construct(meta.target, []);
+        const serializerName = meta.target.name || meta.target.constructor.name;
+
+        this._serializers.set(serializerName, instance);
+      } catch {}
+    }
+
+    return Array.from(this._serializers.values());
+  }
+
+  /**
+   * Manually set a serializer instance. Useful when using without DI.
+   * @param {string} name Unique name for the serializer
+   * @param {LogSerializerBase} serializer Serializer instance
+   */
+  static setSerializer(name: string, serializer: LogSerializerBase): void {
+    this._serializers ??= new Map<string, LogSerializerBase>();
+    this._serializers.set(name, serializer);
+  }
+
+  /**
+   * Remove a serializer by name.
+   * @param {string} name Name of the serializer to remove
+   * @returns {boolean} true if the serializer was removed, false if it didn't exist
+   */
+  static deleteSerializer(name: string): boolean {
+    if (!this._serializers) return false;
+
+    return this._serializers.delete(name);
+  }
+
+  /**
+   * Check if a serializer exists by name.
+   * @param {string} name Name of the serializer to check
+   * @returns {boolean} true if the serializer exists, false otherwise
+   */
+  static hasSerializer(name: string): boolean {
+    if (!this._serializers) return false;
+
+    return this._serializers.has(name);
+  }
+
   private static applyOptions(opts: Partial<LoggerOptions>): void {
-    const { redact, level, stream = requirePino().destination() } = opts || {};
+    const { redact, level, stream, transport, timestampFormat } = opts || {};
+
+    const base: LoggerOptionsBase = {
+      redact: redact ?? this.opts.redact ?? [],
+      level: level ?? DEFAULT_LEVEL,
+      timestampFormat: timestampFormat ?? LogTimestampFormat.isoTime,
+    };
+
+    /**
+     * Выбираем ровно один способ доставки. Если ни stream, ни transport не
+     * переданы — сохраняем текущий, чтобы частичный reconfigure({ level }) не
+     * сбрасывал ранее заданный transport.
+     */
+    if (transport) {
+      this.opts = { ...base, transport };
+    } else if (stream) {
+      this.opts = { ...base, stream };
+    } else if (this.opts.transport) {
+      this.opts = { ...base, transport: this.opts.transport };
+    } else {
+      this.opts = {
+        ...base,
+        stream: this.opts.stream ?? requirePino().destination(),
+      };
+    }
+  }
+
+  /**
+   * `stream`/`transport` исключаем из опций: способ доставки задаётся вторым
+   * аргументом `pino()`, а pino запрещает одновременно `transport` в опциях и
+   * stream-аргумент.
+   */
+  private static buildPinoOptions(
+    extra: Partial<LoggerOptsPino> = {},
+  ): LoggerOptsPino {
+    const {
+      timestampFormat,
+      stream: _stream,
+      transport: _transport,
+      ...other
+    } = this.opts;
+
+    return {
+      ...other,
+      timestamp: this.pinoTimestampFormatMap[timestampFormat],
+      ...extra,
+    };
+  }
+
+  /**
+   * Создаёт инстанс pino. Воркер транспорта переиспользуется, если объект
+   * конфига транспорта тот же по ссылке (сравнение identity, не по значению).
+   * Это покрывает связку reconfigure→applyInstrumentations (между ними
+   * this.opts.transport не пересобирается) и не даёт пересоздавать и тут же
+   * закрывать только что поднятый, возможно медленный, OTEL-воркер. Новый
+   * объект конфига (например, при config.onUpdate) ожидаемо пересоздаёт воркер.
+   */
+  private static instantiatePino(extra: Partial<LoggerOptsPino> = {}): Pino {
+    const pino = requirePino();
+    const options = this.buildPinoOptions(extra);
+
+    if (!this.opts.transport) {
+      this.disposeActiveTransport();
+
+      return pino(options, this.opts.stream);
+    }
+
+    const reuse =
+      this._activeTransport &&
+      this.opts.transport === this._activeTransportConfig;
+
+    const stream = reuse
+      ? this._activeTransport!
+      : this.createTransport(this.opts.transport);
+
+    return pino(options, stream);
+  }
+
+  /**
+   * Поднимает worker-транспорт, закрыв предыдущий. Обработчик 'error' не даёт
+   * асинхронной ошибке воркера уронить процесс, но делает её видимой в stderr
+   * (сам логгер использовать нельзя — упал его транспорт). Ошибку резолва
+   * таргета pino.transport(...) бросает синхронно — она долетает до старта.
+   */
+  private static createTransport(
+    transport: TransportMultiOptions,
+  ): TransportStream {
+    this.disposeActiveTransport();
+
+    const stream = requirePino().transport(transport) as TransportStream;
+
+    stream.on('error', (...args: unknown[]) => {
+      const error = args[0];
+      const message = error instanceof Error ? error.message : String(error);
+
+      process.stderr.write(`[@rsdk/logging] transport error: ${message}\n`);
+    });
+
+    this._activeTransport = stream;
+    this._activeTransportConfig = transport;
+
+    return stream;
+  }
+
+  /**
+   * Завершает воркеры предыдущего транспорта (best-effort, не блокируя). stdout
+   * не затрагивается: для него хэндл не сохраняется.
+   */
+  private static disposeActiveTransport(): void {
+    const previous = this._activeTransport;
+
+    if (!previous) return;
+
+    this._activeTransport = null;
+    this._activeTransportConfig = null;
+
+    // на teardown ошибки ожидаемы (например, "end() took too long" у медленных
+    // транспортов) — глушим их молча и не держим event loop
+    previous.unref?.();
+    previous.removeAllListeners?.('error');
+    previous.on('error', () => {});
 
-    Object.assign(this.opts, { redact, level: level ?? DEFAULT_LEVEL, stream });
+    try {
+      previous.end();
+    } catch {}
   }
 }

package/src/logger.interface.ts

@@ -37,3 +37,10 @@ export interface ILogger {
   log(level: LogLevel, message: string, params?: Params): void;
   log(level: LogLevel, message: string, error?: ErrorLike): void;
 }
+
+export interface ILogSerializer<TEntry, TSerialized> {
+  match(entry: unknown): entry is TEntry;
+  serialize(entry: TEntry): TSerialized;
+}
+
+export type LogSerializerBase = ILogSerializer<unknown, unknown>;

package/src/metadata/constants.ts

@@ -0,0 +1 @@
+export const LOGGER_METADATA_KEY = Symbol('LOGGER_METADATA_KEY');

package/src/metadata/logger-metadata.registry.ts

@@ -0,0 +1,21 @@
+import type { Constructor } from '@rsdk/common';
+
+import type { LoggerSerializerMetadata } from '../types';
+
+export class LoggerMetadataRegistry {
+  private static readonly serializers = new Map<
+    Constructor,
+    LoggerSerializerMetadata
+  >();
+
+  static registerSerializer(
+    target: Constructor,
+    metadata: LoggerSerializerMetadata,
+  ): void {
+    this.serializers.set(target, metadata);
+  }
+
+  static getSerializers(): LoggerSerializerMetadata[] {
+    return Array.from(this.serializers.values());
+  }
+}