@application-kit/observability 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @application-kit/observability
+
+## 0.2.0
+
+### Minor Changes
+
+- 06c0229: Вход `/cqrs`: `CqrsLoggerModule` и `CqrsLogger` — старт, длительность и исход каждой команды и запроса на шинах
+  `@nestjs/cqrs` (имя, а не полезная нагрузка); логгер приходит токеном `OBSERVABILITY_LOGGER` по контракту
+  `ObservabilityLoggerInterface`, `@nestjs/cqrs` — optional peer. Вход `/http`: `resolveClientIp(request, { trustedHeaders })` —
+  реальный IP клиента за прокси: доверенные заголовки по порядку, затем `request.ip` и адрес сокета; по умолчанию заголовкам
+  не доверяет.
+
+## 0.1.0
+
+### Minor Changes
+
+- 2f8c709: Первый выпуск: вход `/metrics` — `MetricsRegistry` (реестр Prometheus с метриками процесса Node), RED-гистограммы
+  `HttpMetrics` (ярлык маршрута — шаблон пути, `resolveRouteLabel`) и `GraphqlMetrics` (ярлык operation — корневые поля
+  документа, адаптер хуков `asMercuriusHook`), `startMetricsServer` — HTTP-сервер `/metrics` для процессов без веб-слоя.
+  Peer `graphql` — optional: из него берутся только типы, нужен лишь GraphQL-гистограмме.

package/README.md

@@ -1,7 +1,7 @@
 # @application-kit/observability
 
-Наблюдаемость NestJS-процесса. Первый вход — `/metrics`: реестр Prometheus с метриками процесса Node, RED-гистограммы
-HTTP и GraphQL и HTTP-сервер экспозиции для процессов без своего веб-слоя. Пакет не знает ни маршрутов, ни схемы,
+Наблюдаемость NestJS-процесса: метрики Prometheus (`/metrics`), логирование команд и запросов CQRS-шин (`/cqrs`)
+и реальный IP клиента за прокси (`/http`). Пакет не знает ни маршрутов, ни схемы,
 ни портов приложения: ярлыки и порт приходят параметрами, а хуки веб-сервера и контроллер скрейпа остаются у потребителя.
 
 ## Установка
@@ -10,13 +10,15 @@ HTTP и GraphQL и HTTP-сервер экспозиции для процесс
 yarn add @application-kit/observability
 ```
 
-Peer-зависимости: `@nestjs/common`, `@prometheus-io/client`; `graphql` — optional, нужен только GraphQL-гистограмме
-(из него берутся типы документа, сам вход грузится и без него).
+Peer-зависимости: `@nestjs/common`, `@prometheus-io/client`; optional — `graphql` (нужен только GraphQL-гистограмме,
+из него берутся типы документа) и `@nestjs/cqrs` (нужен только входу `/cqrs`).
 
 ## Входы
 
 | Вход | Для чего | Тянет |
 |------|----------|-------|
+| `@application-kit/observability/cqrs` | логирование команд и запросов обеих шин | `@nestjs/common`, `@nestjs/cqrs` |
+| `@application-kit/observability/http` | `resolveClientIp` — IP клиента за прокси | ничего |
 | `@application-kit/observability/metrics` | реестр, гистограммы HTTP и GraphQL, сервер `/metrics` | `@nestjs/common`, `@prometheus-io/client` |
 
 Корневого входа нет: каждый вход несёт свои peer-зависимости, и лишнего потребитель не ставит.
@@ -56,3 +58,38 @@ app.register(async (instance) => {
 ```ts
 const server = startMetricsServer({ onError: (error) => logger.error(error), port: 9464, registry })
 ```
+
+## Логирование CQRS-шин
+
+`CqrsLoggerModule` подключается корневым модулем процесса один раз. На каждую команду и запрос — запись о старте
+(подпиской на шину: видит все отправки) и о завершении с `durationMs` и `outcome` (обёрткой `execute` экземпляра шины:
+длительность и исход шина не публикует). В лог идёт ИМЯ класса, не полезная нагрузка; ошибка хендлера пишется на `error`
+и пробрасывается дальше.
+
+Логгер приложение приносит глобально токеном `OBSERVABILITY_LOGGER` — подходит любой логгер с `info(payload, message)`
+и `error(payload, message)`, например `PinoLogger` из `nestjs-pino`:
+
+```ts
+@Global()
+@Module({
+  exports: [OBSERVABILITY_LOGGER],
+  providers: [AppLogger, { provide: OBSERVABILITY_LOGGER, useExisting: AppLogger }],
+})
+export class CommonModule {}
+
+@Module({ imports: [CommonModule, CqrsLoggerModule] })
+export class AppModule {}
+```
+
+## IP клиента за прокси
+
+`resolveClientIp(request, { trustedHeaders })` принимает `IncomingMessage`, `FastifyRequest` или его обёртку из
+сериалайзера pino. Порядок: доверенные заголовки по порядку списка (первый непустой), затем `request.ip` (у Fastify —
+с учётом `trustProxy`), затем адрес сокета; источника нет — пустая строка.
+
+По умолчанию заголовкам не доверяет: в список кладётся только заголовок, который прокси перед процессом ставит и
+перезаписывает сам, — иначе клиент подставит в логи любой адрес.
+
+```ts
+const clientIp = resolveClientIp(request, { trustedHeaders: ['cf-connecting-ip'] })
+```

package/dist/cjs/cqrs/constants.d.ts

@@ -0,0 +1 @@
+export declare const OBSERVABILITY_LOGGER: unique symbol;

package/dist/cjs/cqrs/constants.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OBSERVABILITY_LOGGER = void 0;
+exports.OBSERVABILITY_LOGGER = Symbol('OBSERVABILITY_LOGGER');

package/dist/cjs/cqrs/cqrs-logger.d.ts

@@ -0,0 +1,12 @@
+import { OnApplicationBootstrap } from '@nestjs/common';
+import { CommandBus, QueryBus } from '@nestjs/cqrs';
+import type { ObservabilityLoggerInterface } from './observability-logger.interface.js';
+export declare class CqrsLogger implements OnApplicationBootstrap {
+    private readonly commandBus;
+    private readonly queryBus;
+    private readonly logger;
+    private instrumented;
+    constructor(commandBus: CommandBus, queryBus: QueryBus, logger: ObservabilityLoggerInterface);
+    onApplicationBootstrap(): void;
+    private instrumentCompletion;
+}

package/dist/cjs/cqrs/cqrs-logger.js

@@ -0,0 +1,72 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CqrsLogger = void 0;
+const common_1 = require("@nestjs/common");
+const cqrs_1 = require("@nestjs/cqrs");
+const node_perf_hooks_1 = require("node:perf_hooks");
+const constants_js_1 = require("./constants.js");
+const KIND_COMMAND = 'command';
+const KIND_QUERY = 'query';
+let CqrsLogger = class CqrsLogger {
+    commandBus;
+    queryBus;
+    logger;
+    instrumented = false;
+    constructor(commandBus, queryBus, logger) {
+        this.commandBus = commandBus;
+        this.queryBus = queryBus;
+        this.logger = logger;
+    }
+    onApplicationBootstrap() {
+        if (this.instrumented) {
+            return;
+        }
+        this.instrumented = true;
+        this.commandBus.subscribe((command) => {
+            this.logger.info({ [KIND_COMMAND]: command.constructor.name }, 'command started');
+        });
+        this.queryBus.subscribe((query) => {
+            this.logger.info({ [KIND_QUERY]: query.constructor.name }, 'query started');
+        });
+        this.instrumentCompletion(this.commandBus, KIND_COMMAND);
+        this.instrumentCompletion(this.queryBus, KIND_QUERY);
+    }
+    instrumentCompletion(bus, kind) {
+        const target = bus;
+        const original = target.execute.bind(target);
+        target.execute = async (payload, context) => {
+            const startedAt = node_perf_hooks_1.performance.now();
+            const { name } = payload.constructor;
+            try {
+                const result = await original(payload, context);
+                this.logger.info({ durationMs: node_perf_hooks_1.performance.now() - startedAt, [kind]: name, outcome: 'ok' }, `${kind} finished`);
+                return result;
+            }
+            catch (error) {
+                this.logger.error({ durationMs: node_perf_hooks_1.performance.now() - startedAt, err: error, [kind]: name, outcome: 'error' }, `${kind} failed`);
+                throw error;
+            }
+        };
+    }
+};
+exports.CqrsLogger = CqrsLogger;
+exports.CqrsLogger = CqrsLogger = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(cqrs_1.CommandBus)),
+    __param(1, (0, common_1.Inject)(cqrs_1.QueryBus)),
+    __param(2, (0, common_1.Inject)(constants_js_1.OBSERVABILITY_LOGGER)),
+    __metadata("design:paramtypes", [cqrs_1.CommandBus,
+        cqrs_1.QueryBus, Object])
+], CqrsLogger);

package/dist/cjs/cqrs/cqrs-logger.module.d.ts

@@ -0,0 +1,2 @@
+export declare class CqrsLoggerModule {
+}

package/dist/cjs/cqrs/cqrs-logger.module.js

@@ -0,0 +1,22 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CqrsLoggerModule = void 0;
+const common_1 = require("@nestjs/common");
+const cqrs_1 = require("@nestjs/cqrs");
+const cqrs_logger_js_1 = require("./cqrs-logger.js");
+let CqrsLoggerModule = class CqrsLoggerModule {
+};
+exports.CqrsLoggerModule = CqrsLoggerModule;
+exports.CqrsLoggerModule = CqrsLoggerModule = __decorate([
+    (0, common_1.Module)({
+        exports: [cqrs_logger_js_1.CqrsLogger],
+        imports: [cqrs_1.CqrsModule],
+        providers: [cqrs_logger_js_1.CqrsLogger],
+    })
+], CqrsLoggerModule);

package/dist/cjs/cqrs/index.d.ts

@@ -0,0 +1,4 @@
+export * from './constants.js';
+export * from './cqrs-logger.js';
+export * from './cqrs-logger.module.js';
+export * from './observability-logger.interface.js';

package/dist/cjs/cqrs/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./constants.js"), exports);
+__exportStar(require("./cqrs-logger.js"), exports);
+__exportStar(require("./cqrs-logger.module.js"), exports);
+__exportStar(require("./observability-logger.interface.js"), exports);

package/dist/cjs/cqrs/observability-logger.interface.d.ts

@@ -0,0 +1,4 @@
+export interface ObservabilityLoggerInterface {
+    error(payload: object, message: string): void;
+    info(payload: object, message: string): void;
+}

package/dist/cjs/cqrs/observability-logger.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/http/client-ip-options.interface.d.ts

@@ -0,0 +1,3 @@
+export interface ClientIpOptionsInterface {
+    readonly trustedHeaders?: readonly string[];
+}

package/dist/cjs/http/client-ip-options.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/http/index.d.ts

@@ -0,0 +1,2 @@
+export * from './client-ip-options.interface.js';
+export * from './resolve-client-ip.js';

package/dist/cjs/http/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./client-ip-options.interface.js"), exports);
+__exportStar(require("./resolve-client-ip.js"), exports);

package/dist/cjs/http/resolve-client-ip.d.ts

@@ -0,0 +1,14 @@
+import type { ClientIpOptionsInterface } from './client-ip-options.interface.js';
+export interface ClientIpSourceInterface {
+    headers?: Record<string, string | string[] | undefined> | undefined;
+    ip?: string | undefined;
+    raw?: {
+        socket?: SocketLikeInterface | undefined;
+    } | undefined;
+    socket?: SocketLikeInterface | undefined;
+}
+interface SocketLikeInterface {
+    remoteAddress?: string | undefined;
+}
+export declare const resolveClientIp: (request: ClientIpSourceInterface, options?: ClientIpOptionsInterface) => string;
+export {};

package/dist/cjs/http/resolve-client-ip.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveClientIp = void 0;
+const firstHeaderValue = (value) => {
+    const single = Array.isArray(value) ? value[0] : value;
+    return (single ?? '').trim();
+};
+const trustedHeaderIp = (request, trustedHeaders) => {
+    const values = trustedHeaders?.map((header) => firstHeaderValue(request.headers?.[header]));
+    return values?.find((value) => value !== '') ?? '';
+};
+const rawSocketIp = (request) => request.raw?.socket?.remoteAddress ?? '';
+const socketIp = (request) => request.socket?.remoteAddress ?? rawSocketIp(request);
+const fallbackIp = (request) => {
+    const proxyAwareIp = (request.ip ?? '').trim();
+    return proxyAwareIp === '' ? socketIp(request) : proxyAwareIp;
+};
+const resolveClientIp = (request, options = {}) => {
+    const headerIp = trustedHeaderIp(request, options.trustedHeaders);
+    return headerIp === '' ? fallbackIp(request) : headerIp;
+};
+exports.resolveClientIp = resolveClientIp;

package/dist/esm/cqrs/constants.d.ts

@@ -0,0 +1 @@
+export declare const OBSERVABILITY_LOGGER: unique symbol;

package/dist/esm/cqrs/constants.js

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

package/dist/esm/cqrs/cqrs-logger.d.ts

@@ -0,0 +1,12 @@
+import { OnApplicationBootstrap } from '@nestjs/common';
+import { CommandBus, QueryBus } from '@nestjs/cqrs';
+import type { ObservabilityLoggerInterface } from './observability-logger.interface.js';
+export declare class CqrsLogger implements OnApplicationBootstrap {
+    private readonly commandBus;
+    private readonly queryBus;
+    private readonly logger;
+    private instrumented;
+    constructor(commandBus: CommandBus, queryBus: QueryBus, logger: ObservabilityLoggerInterface);
+    onApplicationBootstrap(): void;
+    private instrumentCompletion;
+}

package/dist/esm/cqrs/cqrs-logger.js

@@ -0,0 +1,69 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from '@nestjs/common';
+import { CommandBus, QueryBus } from '@nestjs/cqrs';
+import { performance } from 'node:perf_hooks';
+import { OBSERVABILITY_LOGGER } from './constants.js';
+const KIND_COMMAND = 'command';
+const KIND_QUERY = 'query';
+let CqrsLogger = class CqrsLogger {
+    commandBus;
+    queryBus;
+    logger;
+    instrumented = false;
+    constructor(commandBus, queryBus, logger) {
+        this.commandBus = commandBus;
+        this.queryBus = queryBus;
+        this.logger = logger;
+    }
+    onApplicationBootstrap() {
+        if (this.instrumented) {
+            return;
+        }
+        this.instrumented = true;
+        this.commandBus.subscribe((command) => {
+            this.logger.info({ [KIND_COMMAND]: command.constructor.name }, 'command started');
+        });
+        this.queryBus.subscribe((query) => {
+            this.logger.info({ [KIND_QUERY]: query.constructor.name }, 'query started');
+        });
+        this.instrumentCompletion(this.commandBus, KIND_COMMAND);
+        this.instrumentCompletion(this.queryBus, KIND_QUERY);
+    }
+    instrumentCompletion(bus, kind) {
+        const target = bus;
+        const original = target.execute.bind(target);
+        target.execute = async (payload, context) => {
+            const startedAt = performance.now();
+            const { name } = payload.constructor;
+            try {
+                const result = await original(payload, context);
+                this.logger.info({ durationMs: performance.now() - startedAt, [kind]: name, outcome: 'ok' }, `${kind} finished`);
+                return result;
+            }
+            catch (error) {
+                this.logger.error({ durationMs: performance.now() - startedAt, err: error, [kind]: name, outcome: 'error' }, `${kind} failed`);
+                throw error;
+            }
+        };
+    }
+};
+CqrsLogger = __decorate([
+    Injectable(),
+    __param(0, Inject(CommandBus)),
+    __param(1, Inject(QueryBus)),
+    __param(2, Inject(OBSERVABILITY_LOGGER)),
+    __metadata("design:paramtypes", [CommandBus,
+        QueryBus, Object])
+], CqrsLogger);
+export { CqrsLogger };

package/dist/esm/cqrs/cqrs-logger.module.d.ts

@@ -0,0 +1,2 @@
+export declare class CqrsLoggerModule {
+}

package/dist/esm/cqrs/cqrs-logger.module.js

@@ -0,0 +1,19 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from '@nestjs/common';
+import { CqrsModule } from '@nestjs/cqrs';
+import { CqrsLogger } from './cqrs-logger.js';
+let CqrsLoggerModule = class CqrsLoggerModule {
+};
+CqrsLoggerModule = __decorate([
+    Module({
+        exports: [CqrsLogger],
+        imports: [CqrsModule],
+        providers: [CqrsLogger],
+    })
+], CqrsLoggerModule);
+export { CqrsLoggerModule };

package/dist/esm/cqrs/index.d.ts

@@ -0,0 +1,4 @@
+export * from './constants.js';
+export * from './cqrs-logger.js';
+export * from './cqrs-logger.module.js';
+export * from './observability-logger.interface.js';

package/dist/esm/cqrs/index.js

@@ -0,0 +1,4 @@
+export * from './constants.js';
+export * from './cqrs-logger.js';
+export * from './cqrs-logger.module.js';
+export * from './observability-logger.interface.js';

package/dist/esm/cqrs/observability-logger.interface.d.ts

@@ -0,0 +1,4 @@
+export interface ObservabilityLoggerInterface {
+    error(payload: object, message: string): void;
+    info(payload: object, message: string): void;
+}

package/dist/esm/cqrs/observability-logger.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/http/client-ip-options.interface.d.ts

@@ -0,0 +1,3 @@
+export interface ClientIpOptionsInterface {
+    readonly trustedHeaders?: readonly string[];
+}

package/dist/esm/http/client-ip-options.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/http/index.d.ts

@@ -0,0 +1,2 @@
+export * from './client-ip-options.interface.js';
+export * from './resolve-client-ip.js';

package/dist/esm/http/index.js

@@ -0,0 +1,2 @@
+export * from './client-ip-options.interface.js';
+export * from './resolve-client-ip.js';

package/dist/esm/http/resolve-client-ip.d.ts

@@ -0,0 +1,14 @@
+import type { ClientIpOptionsInterface } from './client-ip-options.interface.js';
+export interface ClientIpSourceInterface {
+    headers?: Record<string, string | string[] | undefined> | undefined;
+    ip?: string | undefined;
+    raw?: {
+        socket?: SocketLikeInterface | undefined;
+    } | undefined;
+    socket?: SocketLikeInterface | undefined;
+}
+interface SocketLikeInterface {
+    remoteAddress?: string | undefined;
+}
+export declare const resolveClientIp: (request: ClientIpSourceInterface, options?: ClientIpOptionsInterface) => string;
+export {};

package/dist/esm/http/resolve-client-ip.js

@@ -0,0 +1,18 @@
+const firstHeaderValue = (value) => {
+    const single = Array.isArray(value) ? value[0] : value;
+    return (single ?? '').trim();
+};
+const trustedHeaderIp = (request, trustedHeaders) => {
+    const values = trustedHeaders?.map((header) => firstHeaderValue(request.headers?.[header]));
+    return values?.find((value) => value !== '') ?? '';
+};
+const rawSocketIp = (request) => request.raw?.socket?.remoteAddress ?? '';
+const socketIp = (request) => request.socket?.remoteAddress ?? rawSocketIp(request);
+const fallbackIp = (request) => {
+    const proxyAwareIp = (request.ip ?? '').trim();
+    return proxyAwareIp === '' ? socketIp(request) : proxyAwareIp;
+};
+export const resolveClientIp = (request, options = {}) => {
+    const headerIp = trustedHeaderIp(request, options.trustedHeaders);
+    return headerIp === '' ? fallbackIp(request) : headerIp;
+};

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "@application-kit/observability",
-  "version": "0.0.0",
-  "description": "Наблюдаемость NestJS-процесса: реестр метрик Prometheus, RED-гистограммы HTTP и GraphQL, HTTP-сервер /metrics для процессов без веб-слоя",
+  "version": "0.2.0",
+  "description": "Наблюдаемость NestJS-процесса: реестр метрик Prometheus и RED-гистограммы, логирование команд и запросов CQRS-шин, реальный IP клиента за прокси",
   "keywords": [
+    "cqrs",
+    "logging",
     "metrics",
     "nestjs",
     "observability",
@@ -22,6 +24,26 @@
   "sideEffects": false,
   "type": "module",
   "exports": {
+    "./cqrs": {
+      "import": {
+        "types": "./dist/esm/cqrs/index.d.ts",
+        "default": "./dist/esm/cqrs/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/cqrs/index.d.ts",
+        "default": "./dist/cjs/cqrs/index.js"
+      }
+    },
+    "./http": {
+      "import": {
+        "types": "./dist/esm/http/index.d.ts",
+        "default": "./dist/esm/http/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/http/index.d.ts",
+        "default": "./dist/cjs/http/index.js"
+      }
+    },
     "./metrics": {
       "import": {
         "types": "./dist/esm/metrics/index.d.ts",
@@ -41,13 +63,16 @@
     "dist"
   ],
   "scripts": {
-    "build": "rm -rf ./dist && node ../../scripts/barrels.mjs create ./src/metrics && tsc --project tsconfig.build.json && tsc --project tsconfig.build.cjs.json && node ../../scripts/barrels.mjs clean ./src && node ../../scripts/mark-cjs.mjs ./dist/cjs",
+    "build": "rm -rf ./dist && node ../../scripts/barrels.mjs create ./src/cqrs && node ../../scripts/barrels.mjs create ./src/http && node ../../scripts/barrels.mjs create ./src/metrics && tsc --project tsconfig.build.json && tsc --project tsconfig.build.cjs.json && node ../../scripts/barrels.mjs clean ./src && node ../../scripts/mark-cjs.mjs ./dist/cjs",
     "lint:tsc": "tsc --noEmit --pretty --project .",
     "test:mutation": "stryker run",
     "test:unit": "vitest run"
   },
   "devDependencies": {
     "@nestjs/common": "^11.2.7",
+    "@nestjs/core": "^11.2.7",
+    "@nestjs/cqrs": "^11.0.3",
+    "@nestjs/testing": "^11.2.7",
     "@prometheus-io/client": "^0.16.0",
     "@stryker-mutator/core": "^10.0.0",
     "@stryker-mutator/vitest-runner": "^10.0.0",
@@ -60,10 +85,14 @@
   },
   "peerDependencies": {
     "@nestjs/common": "^11.0.0",
+    "@nestjs/cqrs": "^11.0.0",
     "@prometheus-io/client": "^0.16.0",
     "graphql": "^16.0.0"
   },
   "peerDependenciesMeta": {
+    "@nestjs/cqrs": {
+      "optional": true
+    },
     "graphql": {
       "optional": true
     }