@biorate/nestjs-tools 2.4.0 → 2.5.0

package/README.md

@@ -77,12 +77,12 @@ app.use(ResponseTimeMiddleware.create());
 
 Config options:
 
-| Path                                                | Default     |
-|-----------------------------------------------------|-------------|
-| `app.middleware.ResponseTimeMiddleware.suffix`       | `true`      |
-| `app.middleware.ResponseTimeMiddleware.header`       | `x-response-time` |
-| `app.middleware.ResponseTimeMiddleware.digits`       | `3`         |
-| `app.middleware.ResponseTimeMiddleware.log-base-url` | `false`     |
+| Path                                                 | Default                 |
+| ---------------------------------------------------- | ----------------------- |
+| `app.middleware.ResponseTimeMiddleware.suffix`       | `true`                  |
+| `app.middleware.ResponseTimeMiddleware.header`       | `x-response-time`       |
+| `app.middleware.ResponseTimeMiddleware.digits`       | `3`                     |
+| `app.middleware.ResponseTimeMiddleware.log-base-url` | `false`                 |
 | `ResponseTimeMiddleware.histogram.buckets`           | `[0.005, 0.01, … , 10]` |
 
 ### `ProxyPrometheusMiddleware`
@@ -92,13 +92,18 @@ Prometheus‑instrumented HTTP proxy via `http-proxy-middleware`.
 ```ts
 import { ProxyPrometheusMiddleware } from '@biorate/nestjs-tools';
 
-consumer.apply(ProxyPrometheusMiddleware.create({
-  target: 'http://upstream.service:8080',
-  changeOrigin: true,
-})).forRoutes('/api/v2/legacy');
+consumer
+  .apply(
+    ProxyPrometheusMiddleware.create({
+      target: 'http://upstream.service:8080',
+      changeOrigin: true,
+    }),
+  )
+  .forRoutes('/api/v2/legacy');
 ```
 
 Creates two metrics:
+
 - `http_proxy_server_requests_seconds_count` (counter)
 - `http_proxy_server_requests_seconds` (histogram)
 
@@ -145,7 +150,32 @@ incoming.response.data
 incoming.response.errorCode
 ```
 
-Config: `TracingInterceptor.excluded` — array of strings or RegExp to skip URLs.
+Config: `TracingInterceptor.excluded` — array of strings or RegExp to skip URLs
+(string entries match by substring inclusion, RegExp entries by test).
+
+#### Aspect exclusion
+
+Granular control over which span attributes are written:
+
+```json
+{
+  "TracingInterceptor": {
+    "excluded": ["/health"],
+    "excludedAttributes": ["response.data"],
+    "excludedByURL": [{ "url": "/files", "attributes": ["body", "response"] }]
+  }
+}
+```
+
+- `TracingInterceptor.excludedAttributes` — string[] of aspects to skip globally.
+- `TracingInterceptor.excludedByURL` — array of `{ url: string | RegExp, attributes: string[] }`
+  entries; aspects are skipped only for matching URLs (string entries match by
+  substring inclusion, RegExp entries by test).
+- An excluded item also matches aspect groups by prefix: `response` excludes
+  `response.headers`, `response.statusCode`, `response.data` and `response.errorCode`.
+- Accepted aliases: `url`, `method`, `headers`, `body`, `params`, `query`
+  (→ `incoming.request.*`), `statusCode`, `data`, `errorCode` (→ `incoming.response.*`);
+  full names (`request.body`, `response.data`, …) work as-is.
 
 ### `RoutesInterceptor`
 
@@ -164,7 +194,9 @@ HTTP Basic Authentication guard. Validates `Authorization: Basic …` against co
 export class MyController {
   @Get('/admin')
   @AuthBasic()
-  public admin() { return 'secret data'; }
+  public admin() {
+    return 'secret data';
+  }
 }
 ```
 
@@ -173,13 +205,22 @@ export class MyController {
 Bitmask‑based role guard. Use with `@Roles()` decorator:
 
 ```ts
+import { Controller, Get } from '@nestjs/common';
 import { Roles, UserRoles } from '@biorate/nestjs-tools';
 
-@Roles(UserRoles.Admin | UserRoles.Manager)
-@Get('/admin')
-public admin() { return 'ok'; }
+@Controller()
+export class AdminController {
+  @Roles(UserRoles.Admin, UserRoles.Basic)
+  @Get('/admin')
+  public admin() {
+    return 'ok';
+  }
+}
 ```
 
+`Roles(...)` accepts a variadic list of roles (combined into a bitmask via
+bitwise OR internally). Built-in `UserRoles`: `Basic` (`1 << 0`), `Admin` (`1 << 1`).
+
 Override `getUser()` to load the user from your database:
 
 ```ts
@@ -202,10 +243,10 @@ app.use(BootstrapProvider.create());
 
 ## Decorators
 
-| Decorator     | Composition                                      |
-|---------------|--------------------------------------------------|
-| `@Roles(...)` | `SetMetadata(ROLES_KEY, bitmask)`                |
-| `@AuthBasic()`| `ApiBasicAuth()` + `UseGuards(AuthGuardProvider)` |
+| Decorator      | Composition                                       |
+| -------------- | ------------------------------------------------- |
+| `@Roles(...)`  | `SetMetadata(ROLES_KEY, bitmask)`                 |
+| `@AuthBasic()` | `ApiBasicAuth()` + `UseGuards(AuthGuardProvider)` |
 
 ## CORS
 
@@ -225,9 +266,9 @@ Exposes `GET /metrics` with Prometheus metrics from the shared registry.
 
 ### `ProbeController`
 
-| Route           | Purpose             |
-|-----------------|---------------------|
-| `GET /probe`    | Liveness/readiness  |
+| Route        | Purpose            |
+| ------------ | ------------------ |
+| `GET /probe` | Liveness/readiness |
 
 ### `LocalesController`
 

package/dist/cjs/src/interceptors/tracing-interceptor.js

@@ -11,6 +11,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
+var TracingInterceptor_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TracingInterceptor = void 0;
 const json_stringify_safe_1 = __importDefault(require("json-stringify-safe"));
@@ -18,44 +19,78 @@ const rxjs_1 = require("rxjs");
 const opentelemetry_1 = require("@biorate/opentelemetry");
 const common_1 = require("@nestjs/common");
 const inversion_1 = require("@biorate/inversion");
-let TracingInterceptor = class TracingInterceptor {
+const lodash_es_1 = require("lodash-es");
+let TracingInterceptor = TracingInterceptor_1 = class TracingInterceptor {
+    static normalizeAspect(name) {
+        const aliased = (0, lodash_es_1.get)(TracingInterceptor_1.aspectAliases, name);
+        if (aliased)
+            return aliased;
+        if (name.startsWith('request.'))
+            return name.slice('request.'.length);
+        return name;
+    }
     stringify(data) {
         return typeof data === 'object' ? (0, json_stringify_safe_1.default)(data) : String(data);
     }
     excluded(url) {
         const excluded = this.config.get('TracingInterceptor.excluded', []);
         for (const item of excluded) {
-            if (typeof item === 'string' && url.startsWith(item))
+            if (typeof item === 'string' && url.includes(item))
                 return true;
             if (item instanceof RegExp && item.test(url))
                 return true;
         }
         return false;
     }
+    excludedAttribute(url, aspect) {
+        const canonical = TracingInterceptor_1.normalizeAspect(aspect);
+        const match = (list) => list.some((item) => {
+            const target = TracingInterceptor_1.normalizeAspect(item);
+            return canonical === target || canonical.startsWith(`${target}.`);
+        });
+        if (match(this.config.get('TracingInterceptor.excludedAttributes', [])))
+            return true;
+        const byUrl = this.config.get('TracingInterceptor.excludedByURL', []);
+        for (const entry of byUrl) {
+            const hit = typeof entry?.url === 'string'
+                ? url.includes(entry.url)
+                : entry?.url instanceof RegExp && entry.url.test(url);
+            if (!hit)
+                continue;
+            if (match(entry?.attributes ?? []))
+                return true;
+        }
+        return false;
+    }
+    attr(span, url, aspect, value) {
+        if (this.excludedAttribute(url, aspect))
+            return;
+        span.setAttribute(TracingInterceptor_1.aspectKeys[aspect], this.stringify(value));
+    }
     http(span, context, next) {
         const host = context.switchToHttp();
         const req = host.getRequest();
         const res = host.getResponse();
         if (this.excluded(req.url))
             return next.handle();
-        span.setAttribute('incoming.request.url', this.stringify(req.url));
-        span.setAttribute('incoming.request.body', this.stringify(req.body));
-        span.setAttribute('incoming.request.headers', this.stringify(req.headers));
-        span.setAttribute('incoming.request.method', this.stringify(req.method));
-        span.setAttribute('incoming.request.params', this.stringify(req.params));
-        span.setAttribute('incoming.request.query', this.stringify(req.query));
+        this.attr(span, req.url, 'url', req.url);
+        this.attr(span, req.url, 'body', req.body);
+        this.attr(span, req.url, 'headers', req.headers);
+        this.attr(span, req.url, 'method', req.method);
+        this.attr(span, req.url, 'params', req.params);
+        this.attr(span, req.url, 'query', req.query);
         return next.handle().pipe((0, rxjs_1.catchError)((e) => {
-            span.setAttribute('incoming.response.headers', this.stringify(res.headers));
-            span.setAttribute('incoming.response.statusCode', this.stringify(res.statusCode));
-            span.setAttribute('incoming.response.errorCode', this.stringify(e.code));
-            span.setAttribute('incoming.response.data', this.stringify(e?.response?.data));
+            this.attr(span, req.url, 'response.headers', res.headers);
+            this.attr(span, req.url, 'response.statusCode', res.statusCode);
+            this.attr(span, req.url, 'response.errorCode', e.code);
+            this.attr(span, req.url, 'response.data', e?.response?.data);
             span.recordException(e);
             span.setStatus({ code: opentelemetry_1.SpanStatusCode.ERROR });
             throw e;
         }), (0, rxjs_1.tap)((data) => {
-            span.setAttribute('incoming.response.headers', this.stringify(res.headers));
-            span.setAttribute('incoming.response.statusCode', this.stringify(res.statusCode));
-            span.setAttribute('incoming.response.data', this.stringify(data));
+            this.attr(span, req.url, 'response.headers', res.headers);
+            this.attr(span, req.url, 'response.statusCode', res.statusCode);
+            this.attr(span, req.url, 'response.data', data);
         }));
     }
     ws(span, context, next) {
@@ -73,10 +108,33 @@ let TracingInterceptor = class TracingInterceptor {
     }
 };
 exports.TracingInterceptor = TracingInterceptor;
+TracingInterceptor.aspectAliases = {
+    'request.url': 'url',
+    'request.method': 'method',
+    'request.headers': 'headers',
+    'request.body': 'body',
+    'request.params': 'params',
+    'request.query': 'query',
+    statusCode: 'response.statusCode',
+    data: 'response.data',
+    errorCode: 'response.errorCode',
+};
+TracingInterceptor.aspectKeys = {
+    url: 'incoming.request.url',
+    method: 'incoming.request.method',
+    headers: 'incoming.request.headers',
+    body: 'incoming.request.body',
+    params: 'incoming.request.params',
+    query: 'incoming.request.query',
+    'response.headers': 'incoming.response.headers',
+    'response.statusCode': 'incoming.response.statusCode',
+    'response.data': 'incoming.response.data',
+    'response.errorCode': 'incoming.response.errorCode',
+};
 __decorate([
     (0, inversion_1.inject)(inversion_1.Types.Config),
     __metadata("design:type", Object)
 ], TracingInterceptor.prototype, "config", void 0);
-exports.TracingInterceptor = TracingInterceptor = __decorate([
+exports.TracingInterceptor = TracingInterceptor = TracingInterceptor_1 = __decorate([
     (0, common_1.Injectable)()
 ], TracingInterceptor);

package/dist/esm/src/interceptors/tracing-interceptor.js

@@ -7,49 +7,84 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
+var TracingInterceptor_1;
 import stringify from 'json-stringify-safe';
 import { tap, catchError } from 'rxjs';
 import { trace, SpanStatusCode } from '@biorate/opentelemetry';
 import { Injectable, } from '@nestjs/common';
 import { inject, Types } from '@biorate/inversion';
-let TracingInterceptor = class TracingInterceptor {
+import { get } from 'lodash-es';
+let TracingInterceptor = TracingInterceptor_1 = class TracingInterceptor {
+    static normalizeAspect(name) {
+        const aliased = get(TracingInterceptor_1.aspectAliases, name);
+        if (aliased)
+            return aliased;
+        if (name.startsWith('request.'))
+            return name.slice('request.'.length);
+        return name;
+    }
     stringify(data) {
         return typeof data === 'object' ? stringify(data) : String(data);
     }
     excluded(url) {
         const excluded = this.config.get('TracingInterceptor.excluded', []);
         for (const item of excluded) {
-            if (typeof item === 'string' && url.startsWith(item))
+            if (typeof item === 'string' && url.includes(item))
                 return true;
             if (item instanceof RegExp && item.test(url))
                 return true;
         }
         return false;
     }
+    excludedAttribute(url, aspect) {
+        const canonical = TracingInterceptor_1.normalizeAspect(aspect);
+        const match = (list) => list.some((item) => {
+            const target = TracingInterceptor_1.normalizeAspect(item);
+            return canonical === target || canonical.startsWith(`${target}.`);
+        });
+        if (match(this.config.get('TracingInterceptor.excludedAttributes', [])))
+            return true;
+        const byUrl = this.config.get('TracingInterceptor.excludedByURL', []);
+        for (const entry of byUrl) {
+            const hit = typeof entry?.url === 'string'
+                ? url.includes(entry.url)
+                : entry?.url instanceof RegExp && entry.url.test(url);
+            if (!hit)
+                continue;
+            if (match(entry?.attributes ?? []))
+                return true;
+        }
+        return false;
+    }
+    attr(span, url, aspect, value) {
+        if (this.excludedAttribute(url, aspect))
+            return;
+        span.setAttribute(TracingInterceptor_1.aspectKeys[aspect], this.stringify(value));
+    }
     http(span, context, next) {
         const host = context.switchToHttp();
         const req = host.getRequest();
         const res = host.getResponse();
         if (this.excluded(req.url))
             return next.handle();
-        span.setAttribute('incoming.request.url', this.stringify(req.url));
-        span.setAttribute('incoming.request.body', this.stringify(req.body));
-        span.setAttribute('incoming.request.headers', this.stringify(req.headers));
-        span.setAttribute('incoming.request.method', this.stringify(req.method));
-        span.setAttribute('incoming.request.params', this.stringify(req.params));
-        span.setAttribute('incoming.request.query', this.stringify(req.query));
+        this.attr(span, req.url, 'url', req.url);
+        this.attr(span, req.url, 'body', req.body);
+        this.attr(span, req.url, 'headers', req.headers);
+        this.attr(span, req.url, 'method', req.method);
+        this.attr(span, req.url, 'params', req.params);
+        this.attr(span, req.url, 'query', req.query);
         return next.handle().pipe(catchError((e) => {
-            span.setAttribute('incoming.response.headers', this.stringify(res.headers));
-            span.setAttribute('incoming.response.statusCode', this.stringify(res.statusCode));
-            span.setAttribute('incoming.response.errorCode', this.stringify(e.code));
-            span.setAttribute('incoming.response.data', this.stringify(e?.response?.data));
+            this.attr(span, req.url, 'response.headers', res.headers);
+            this.attr(span, req.url, 'response.statusCode', res.statusCode);
+            this.attr(span, req.url, 'response.errorCode', e.code);
+            this.attr(span, req.url, 'response.data', e?.response?.data);
             span.recordException(e);
             span.setStatus({ code: SpanStatusCode.ERROR });
             throw e;
         }), tap((data) => {
-            span.setAttribute('incoming.response.headers', this.stringify(res.headers));
-            span.setAttribute('incoming.response.statusCode', this.stringify(res.statusCode));
-            span.setAttribute('incoming.response.data', this.stringify(data));
+            this.attr(span, req.url, 'response.headers', res.headers);
+            this.attr(span, req.url, 'response.statusCode', res.statusCode);
+            this.attr(span, req.url, 'response.data', data);
         }));
     }
     ws(span, context, next) {
@@ -66,11 +101,34 @@ let TracingInterceptor = class TracingInterceptor {
         return this[type](span, context, next);
     }
 };
+TracingInterceptor.aspectAliases = {
+    'request.url': 'url',
+    'request.method': 'method',
+    'request.headers': 'headers',
+    'request.body': 'body',
+    'request.params': 'params',
+    'request.query': 'query',
+    statusCode: 'response.statusCode',
+    data: 'response.data',
+    errorCode: 'response.errorCode',
+};
+TracingInterceptor.aspectKeys = {
+    url: 'incoming.request.url',
+    method: 'incoming.request.method',
+    headers: 'incoming.request.headers',
+    body: 'incoming.request.body',
+    params: 'incoming.request.params',
+    query: 'incoming.request.query',
+    'response.headers': 'incoming.response.headers',
+    'response.statusCode': 'incoming.response.statusCode',
+    'response.data': 'incoming.response.data',
+    'response.errorCode': 'incoming.response.errorCode',
+};
 __decorate([
     inject(Types.Config),
     __metadata("design:type", Object)
 ], TracingInterceptor.prototype, "config", void 0);
-TracingInterceptor = __decorate([
+TracingInterceptor = TracingInterceptor_1 = __decorate([
     Injectable()
 ], TracingInterceptor);
 export { TracingInterceptor };

package/dist/types/src/interceptors/tracing-interceptor.d.ts

@@ -2,9 +2,14 @@ import { Span } from '@biorate/opentelemetry';
 import { NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
 import { IConfig } from '@biorate/config';
 export declare class TracingInterceptor implements NestInterceptor {
+    protected static aspectAliases: Record<string, string>;
+    protected static aspectKeys: Record<string, string>;
+    protected static normalizeAspect(name: string): string;
     protected readonly config: IConfig;
     protected stringify(data: unknown): string;
     protected excluded(url: string): boolean;
+    protected excludedAttribute(url: string, aspect: string): boolean;
+    protected attr(span: Span, url: string, aspect: string, value: unknown): void;
     protected http(span: Span, context: ExecutionContext, next: CallHandler): import("rxjs").Observable<any>;
     protected ws(span: Span, context: ExecutionContext, next: CallHandler): import("rxjs").Observable<any>;
     protected rpc(span: Span, context: ExecutionContext, next: CallHandler): import("rxjs").Observable<any>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biorate/nestjs-tools",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "NestJS tools",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -45,7 +45,7 @@
   "keywords": [],
   "author": "llevkin",
   "license": "MIT",
-  "gitHead": "09ccd82d8fba90cb37750dccf41469452880b129",
+  "gitHead": "8c6857bfe61de7b03025b0d883c478045c14390a",
   "peerDependencies": {
     "@nestjs/common": ">=10.4.15",
     "@nestjs/core": ">=10.4.15",