@application-kit/observability 0.8.2 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @application-kit/observability
 
+## 0.9.0
+
+### Minor Changes
+
+- 504f068: Вход `/http`: `resolveRequestFacts(request, { trustedHeaders })` отдаёт `{ ip, userAgent }`, не определившийся факт — `null`. `firstHeaderValue(value)` теперь в экспорте: первое значение повторяющегося заголовка без краевых пробелов, `null` у отсутствующего или пустого. `resolveClientIp` работает как раньше.
+
+## 0.8.3
+
+### Patch Changes
+
+- 3eb414e: Поведение не меняется — исходники проходят линт на `graphql` 17. Ошибка по-прежнему читается из `originalError`: в
+  `graphql` 16 из peer-диапазона `cause` у `GraphQLError` нет. Литералы видов узла в метриках GraphQL привязаны к `Kind`
+  без шаблонного типа: в `graphql` 17 член `Kind` уже строковый литерал.
+
 ## 0.8.2
 
 ### Patch Changes

package/README.md

@@ -21,7 +21,7 @@ Peer-зависимости: `@nestjs/common`, `@prometheus-io/client`; оста
 | `@application-kit/observability/health` | состав чека, пробы `/health/live` и `/health/ready`, `GET /health` | `@nestjs/terminus`, `@nestjs/typeorm`, `typeorm`, `@application-kit/typeorm`, `class-validator`, `class-transformer` |
 | `@application-kit/observability/health/graphql` | `query { health { status } }` | `/health` + `@nestjs/graphql` |
 | `@application-kit/observability/health/cli` | CLI-команда `<группа> health` | `/health` + `nestjs-console` |
-| `@application-kit/observability/http` | `resolveClientIp` — IP клиента за прокси | ничего |
+| `@application-kit/observability/http` | `resolveClientIp`, `resolveRequestFacts`, `firstHeaderValue` — IP клиента за прокси и факты запроса | ничего |
 | `@application-kit/observability/logging` | опции nestjs-pino, request-id, support-id, служебные пути, токен логгера | `@opentelemetry/api`, `class-validator`, `class-transformer`; типы — `nestjs-pino`, `pino` |
 | `@application-kit/observability/metrics` | реестр, гистограммы HTTP и GraphQL, `GET /metrics`, хуки Fastify, сервер `/metrics` | `@nestjs/common`, `@prometheus-io/client`; типы — `fastify`, `@nestjs/platform-fastify` |
 | `@application-kit/observability/tracing` | `startTracing` — OpenTelemetry NodeSDK для `node --import`, только ESM | `@opentelemetry/sdk-node`, `@opentelemetry/instrumentation`, `@opentelemetry/instrumentation-http`, `@opentelemetry/exporter-trace-otlp-grpc`, `@opentelemetry/semantic-conventions` |
@@ -146,6 +146,18 @@ export class WebModule {}
 const clientIp = resolveClientIp(request, { trustedHeaders: ['cf-connecting-ip'] })
 ```
 
+## Факты запроса
+
+`resolveRequestFacts(request, { trustedHeaders })` — `{ ip, userAgent }` для строки сессии или журнала: адрес берётся из
+`resolveClientIp` с теми же опциями, не определившийся факт — `null`. `firstHeaderValue(value)` — значение заголовка одной
+строкой: первое у повторяющегося, без краевых пробелов, `null` у отсутствующего или пустого.
+
+Где лежит текущий запрос и что ещё считать фактами (актор, роль), функция не знает: это решает приложение.
+
+```ts
+const facts = resolveRequestFacts(request, { trustedHeaders: ['cf-connecting-ip'] })
+```
+
 ## Трейсинг (`/tracing`)
 
 `startTracing({ esmHookedModules, instrumentations, resolveClientIp })` поднимает OpenTelemetry NodeSDK: OTLP gRPC-экспортёр,

package/dist/cjs/http/first-header-value.d.ts

@@ -0,0 +1 @@
+export declare const firstHeaderValue: (value: string | string[] | undefined) => null | string;

package/dist/cjs/http/first-header-value.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.firstHeaderValue = void 0;
+const firstHeaderValue = (value) => {
+    const single = Array.isArray(value) ? value[0] : value;
+    const trimmed = (single ?? '').trim();
+    return trimmed === '' ? null : trimmed;
+};
+exports.firstHeaderValue = firstHeaderValue;

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

@@ -1,2 +1,4 @@
 export * from './client-ip-options.interface.js';
+export * from './first-header-value.js';
 export * from './resolve-client-ip.js';
+export * from './resolve-request-facts.js';

package/dist/cjs/http/index.js

@@ -15,4 +15,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./client-ip-options.interface.js"), exports);
+__exportStar(require("./first-header-value.js"), exports);
 __exportStar(require("./resolve-client-ip.js"), exports);
+__exportStar(require("./resolve-request-facts.js"), exports);

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

@@ -1,13 +1,10 @@
 "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 first_header_value_js_1 = require("./first-header-value.js");
 const trustedHeaderIp = (request, trustedHeaders) => {
-    const values = trustedHeaders?.map((header) => firstHeaderValue(request.headers?.[header]));
-    return values?.find((value) => value !== '') ?? '';
+    const values = trustedHeaders?.map((header) => (0, first_header_value_js_1.firstHeaderValue)(request.headers?.[header]));
+    return values?.find((value) => value !== null) ?? '';
 };
 const rawSocketIp = (request) => request.raw?.socket?.remoteAddress ?? '';
 const socketIp = (request) => request.socket?.remoteAddress ?? rawSocketIp(request);

package/dist/cjs/http/resolve-request-facts.d.ts

@@ -0,0 +1,7 @@
+import type { ClientIpOptionsInterface } from './client-ip-options.interface.js';
+import type { ClientIpSourceInterface } from './resolve-client-ip.js';
+export interface RequestFactsInterface {
+    ip: null | string;
+    userAgent: null | string;
+}
+export declare const resolveRequestFacts: (request: ClientIpSourceInterface, options?: ClientIpOptionsInterface) => RequestFactsInterface;

package/dist/cjs/http/resolve-request-facts.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRequestFacts = void 0;
+const first_header_value_js_1 = require("./first-header-value.js");
+const resolve_client_ip_js_1 = require("./resolve-client-ip.js");
+const USER_AGENT_HEADER = 'user-agent';
+const resolveRequestFacts = (request, options = {}) => {
+    const ip = (0, resolve_client_ip_js_1.resolveClientIp)(request, options);
+    return {
+        ip: ip === '' ? null : ip,
+        userAgent: (0, first_header_value_js_1.firstHeaderValue)(request.headers?.[USER_AGENT_HEADER]),
+    };
+};
+exports.resolveRequestFacts = resolveRequestFacts;

package/dist/esm/http/first-header-value.d.ts

@@ -0,0 +1 @@
+export declare const firstHeaderValue: (value: string | string[] | undefined) => null | string;

package/dist/esm/http/first-header-value.js

@@ -0,0 +1,5 @@
+export const firstHeaderValue = (value) => {
+    const single = Array.isArray(value) ? value[0] : value;
+    const trimmed = (single ?? '').trim();
+    return trimmed === '' ? null : trimmed;
+};

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

@@ -1,2 +1,4 @@
 export * from './client-ip-options.interface.js';
+export * from './first-header-value.js';
 export * from './resolve-client-ip.js';
+export * from './resolve-request-facts.js';

package/dist/esm/http/index.js

@@ -1,2 +1,4 @@
 export * from './client-ip-options.interface.js';
+export * from './first-header-value.js';
 export * from './resolve-client-ip.js';
+export * from './resolve-request-facts.js';

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

@@ -1,10 +1,7 @@
-const firstHeaderValue = (value) => {
-    const single = Array.isArray(value) ? value[0] : value;
-    return (single ?? '').trim();
-};
+import { firstHeaderValue } from './first-header-value.js';
 const trustedHeaderIp = (request, trustedHeaders) => {
     const values = trustedHeaders?.map((header) => firstHeaderValue(request.headers?.[header]));
-    return values?.find((value) => value !== '') ?? '';
+    return values?.find((value) => value !== null) ?? '';
 };
 const rawSocketIp = (request) => request.raw?.socket?.remoteAddress ?? '';
 const socketIp = (request) => request.socket?.remoteAddress ?? rawSocketIp(request);

package/dist/esm/http/resolve-request-facts.d.ts

@@ -0,0 +1,7 @@
+import type { ClientIpOptionsInterface } from './client-ip-options.interface.js';
+import type { ClientIpSourceInterface } from './resolve-client-ip.js';
+export interface RequestFactsInterface {
+    ip: null | string;
+    userAgent: null | string;
+}
+export declare const resolveRequestFacts: (request: ClientIpSourceInterface, options?: ClientIpOptionsInterface) => RequestFactsInterface;

package/dist/esm/http/resolve-request-facts.js

@@ -0,0 +1,10 @@
+import { firstHeaderValue } from './first-header-value.js';
+import { resolveClientIp } from './resolve-client-ip.js';
+const USER_AGENT_HEADER = 'user-agent';
+export const resolveRequestFacts = (request, options = {}) => {
+    const ip = resolveClientIp(request, options);
+    return {
+        ip: ip === '' ? null : ip,
+        userAgent: firstHeaderValue(request.headers?.[USER_AGENT_HEADER]),
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@application-kit/observability",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Наблюдаемость NestJS-процесса: метрики Prometheus и RED-гистограммы, health-чеки и пробы, опции pino с request-id и trace-контекстом, логирование CQRS-шин, реальный IP клиента за прокси, трейсинг OpenTelemetry",
   "keywords": [
     "cqrs",