Merge pull request #250 from memplethee-lab/feat/Correlation

feat(security+observability): domain-safe error handling + request correlation

Author: RUKAYAT-CODER

src/common/interceptors/global-exception.filter.spec.ts

@@ -0,0 +1,38 @@
+import { GlobalExceptionFilter } from './global-exception.filter';
+import { HttpStatus } from '@nestjs/common';
+import { runWithCorrelationId } from '../utils/correlation.utils';
+
+describe('GlobalExceptionFilter', () => {
+  it('adds correlation ID to error response and header', () => {
+    const filter = new GlobalExceptionFilter();
+
+    const req: any = { method: 'GET', url: '/test' };
+    const responseHeaders: Record<string, string> = {};
+    const res: any = {
+      status: (code: number) => {
+        res.statusCode = code;
+        return res;
+      },
+      json: (body: any) => {
+        res.body = body;
+        return res;
+      },
+      setHeader: (name: string, value: string) => {
+        responseHeaders[name.toLowerCase()] = value;
+      },
+      getHeader: (name: string) => responseHeaders[name.toLowerCase()],
+    };
+
+    runWithCorrelationId(() => {
+      filter.catch(new Error('Test error'), {
+        switchToHttp: () => ({ getRequest: () => req, getResponse: () => res }),
+      } as any);
+    }, 'cid-123');
+
+    const body = res.body;
+
+    expect(res.statusCode).toBe(HttpStatus.INTERNAL_SERVER_ERROR);
+    expect(body.correlationId).toBe('cid-123');
+    expect(body.message).toBe('Test error');
+  });
+});

src/common/interceptors/global-exception.filter.ts

@@ -9,6 +9,7 @@ import {
 import { Request, Response } from 'express';
 import { QueryFailedError, EntityNotFoundError } from 'typeorm';
 import { ApiError, ValidationErrorDetail } from '../../interfaces/api-error.interface';
+import { CORRELATION_ID_HEADER, getCorrelationId } from '../utils/correlation.utils';
 
 @Catch()
 export class GlobalExceptionFilter implements ExceptionFilter {
@@ -22,16 +23,23 @@ export class GlobalExceptionFilter implements ExceptionFilter {
 
     const { statusCode, message, error, details, stack } = this.resolveException(exception);
 
+    const correlationId = getCorrelationId();
+
     const errorResponse: ApiError = {
       statusCode,
       message,
       error,
       timestamp: new Date().toISOString(),
       path: request.url,
+      correlationId,
       ...(details?.length && { details }),
       ...(!this.isProduction && stack && { stack }),
     };
 
+    if (correlationId) {
+      response.setHeader(CORRELATION_ID_HEADER, correlationId);
+    }
+
     this.logger.error(
       `[${request.method}] ${request.url} → ${statusCode} ${error}: ${
         Array.isArray(message) ? message.join(', ') : message

src/common/interceptors/logging.interceptor.spec.ts

@@ -0,0 +1,33 @@
+import { LoggingInterceptor } from './logging.interceptor';
+import { of, firstValueFrom } from 'rxjs';
+
+describe('LoggingInterceptor', () => {
+  it('attaches and propagates correlation ID header', async () => {
+    const interceptor = new LoggingInterceptor();
+
+    const req: any = { method: 'GET', url: '/spam', headers: {} };
+    const headers: Record<string, string> = {};
+    const res: any = {
+      statusCode: 200,
+      setHeader: (name: string, value: string) => {
+        headers[name.toLowerCase()] = value;
+      },
+      getHeader: (name: string) => headers[name.toLowerCase()],
+    };
+
+    const context: any = {
+      getType: () => 'http',
+      switchToHttp: () => ({ getRequest: () => req, getResponse: () => res }),
+    };
+
+    const next: any = {
+      handle: () => of({ success: true }),
+    };
+
+    await firstValueFrom(interceptor.intercept(context, next));
+
+    const correlationId = res.getHeader('x-request-id');
+    expect(typeof correlationId).toBe('string');
+    expect(correlationId).toMatch(/^cid-/);
+  });
+});

src/common/interceptors/logging.interceptor.ts

@@ -2,6 +2,7 @@ import { Injectable, NestInterceptor, ExecutionContext, CallHandler, Logger } fr
 import { Observable, throwError } from 'rxjs';
 import { tap, catchError } from 'rxjs/operators';
 import { Request, Response } from 'express';
+import { CORRELATION_ID_HEADER, getCorrelationId } from '../utils/correlation.utils';
 
 export interface RequestLog {
   requestId: string;
@@ -49,7 +50,10 @@ export class LoggingInterceptor implements NestInterceptor {
     }
 
     const startTime = Date.now();
-    const requestId = this.generateRequestId();
+    const requestId = getCorrelationId() || this.generateRequestId();
+
+    const response = httpCtx.getResponse<Response>();
+    response?.setHeader(CORRELATION_ID_HEADER, requestId);
 
     const baseLog: RequestLog = {
       requestId,
@@ -67,12 +71,12 @@ export class LoggingInterceptor implements NestInterceptor {
 
     return next.handle().pipe(
       tap(() => {
-        const response = httpCtx.getResponse<Response>();
+        const res = httpCtx.getResponse<Response>();
         this.logOutgoing({
           ...baseLog,
-          statusCode: response.statusCode,
+          statusCode: res.statusCode,
           responseTimeMs: Date.now() - startTime,
-          contentLength: this.getContentLength(response),
+          contentLength: this.getContentLength(res),
         });
       }),
       catchError((error: unknown) => {

src/common/utils/correlation.utils.spec.ts

@@ -0,0 +1,50 @@
+import {
+  correlationMiddleware,
+  getCorrelationId,
+  injectCorrelationIdToHeaders,
+  CORRELATION_ID_HEADER,
+} from './correlation.utils';
+
+describe('correlation.utils', () => {
+  it('generates and propagates correlation ID through middleware', (done) => {
+    const req: any = { method: 'GET', url: '/test', headers: {} };
+    const headers: Record<string, string> = {};
+    const res: any = {
+      setHeader: (name: string, value: string) => {
+        headers[name.toLowerCase()] = value;
+      },
+      getHeader: (name: string) => headers[name.toLowerCase()],
+    };
+
+    correlationMiddleware(req, res, () => {
+      const id = getCorrelationId();
+      expect(typeof id).toBe('string');
+      expect(res.getHeader(CORRELATION_ID_HEADER)).toBe(id);
+      done();
+    });
+  });
+
+  it('respects incoming x-request-id header', (done) => {
+    const incomingId = 'test-correlation-id';
+    const req: any = { method: 'GET', url: '/test', headers: { 'x-request-id': incomingId } };
+    const headers: Record<string, string> = {};
+    const res: any = {
+      setHeader: (name: string, value: string) => {
+        headers[name.toLowerCase()] = value;
+      },
+      getHeader: (name: string) => headers[name.toLowerCase()],
+    };
+
+    correlationMiddleware(req, res, () => {
+      expect(getCorrelationId()).toBe(incomingId);
+      expect(res.getHeader(CORRELATION_ID_HEADER)).toBe(incomingId);
+      done();
+    });
+  });
+
+  it('injects correlation header into outgoing request headers', () => {
+    const custom = injectCorrelationIdToHeaders({ Authorization: 'Bearer token' }, 'cid-1');
+    expect(custom[CORRELATION_ID_HEADER]).toBe('cid-1');
+    expect(custom.Authorization).toBe('Bearer token');
+  });
+});

src/common/utils/correlation.utils.ts

@@ -0,0 +1,51 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import { Request, Response, NextFunction } from 'express';
+
+export const CORRELATION_ID_HEADER = 'x-request-id';
+
+export interface CorrelationContext {
+  correlationId: string;
+}
+
+const correlationStorage = new AsyncLocalStorage<CorrelationContext>();
+
+export function generateCorrelationId(): string {
+  return `cid-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+export function getCorrelationId(): string | undefined {
+  const store = correlationStorage.getStore();
+  return store?.correlationId;
+}
+
+export function setCorrelationId(req: Request, res: Response, correlationId: string): void {
+  (req as Request & { correlationId?: string }).correlationId = correlationId;
+  res.setHeader(CORRELATION_ID_HEADER, correlationId);
+}
+
+export function correlationMiddleware(req: Request, res: Response, next: NextFunction): void {
+  const incoming =
+    (req.headers[CORRELATION_ID_HEADER] as string) || (req.headers['x-correlation-id'] as string);
+  const correlationId = incoming || generateCorrelationId();
+
+  correlationStorage.run({ correlationId }, () => {
+    setCorrelationId(req, res, correlationId);
+    next();
+  });
+}
+
+export function runWithCorrelationId<T>(callback: () => T, correlationId?: string): T {
+  const id = correlationId || generateCorrelationId();
+  return correlationStorage.run({ correlationId: id }, callback);
+}
+
+export function injectCorrelationIdToHeaders(
+  headers: Record<string, any> = {},
+  correlationId?: string,
+): Record<string, any> {
+  const id = correlationId || getCorrelationId() || generateCorrelationId();
+  return {
+    ...headers,
+    [CORRELATION_ID_HEADER]: id,
+  };
+}

src/main.ts

@@ -9,6 +9,8 @@ import Redis from 'ioredis';
 import { AppModule } from './app.module';
 import { GlobalExceptionFilter } from './common/interceptors/global-exception.filter';
 import { ResponseTransformInterceptor } from './common/interceptors/response-transform.interceptor';
+import { LoggingInterceptor } from './common/interceptors/logging.interceptor';
+import { correlationMiddleware } from './common/utils/correlation.utils';
 import { sessionConfig } from './config/cache.config';
 import { SESSION_REDIS_CLIENT } from './session/session.constants';
 
@@ -26,6 +28,8 @@ async function bootstrapWorker() {
     expressApp.set('trust proxy', 1);
   }
 
+  app.use(correlationMiddleware);
+
   app.use(
     session({
       store: new RedisStore({
@@ -50,6 +54,9 @@ async function bootstrapWorker() {
   // ─── Global Exception Filter ──────────────────────────────────────────────
   app.useGlobalFilters(new GlobalExceptionFilter());
 
+  // ─── Global Logging Interceptor ───────────────────────────────────────────
+  app.useGlobalInterceptors(new LoggingInterceptor());
+
   // ─── Global Response Transform Interceptor ───────────────────────────────
   app.useGlobalInterceptors(new ResponseTransformInterceptor());
 

src/orchestration/service-mesh/service-mesh.service.spec.ts

@@ -0,0 +1,24 @@
+import { ServiceMeshService } from './service-mesh.service';
+import { of } from 'rxjs';
+
+describe('ServiceMeshService', () => {
+  it('propagates correlation ID to external API call headers', async () => {
+    const serviceDiscovery: any = {
+      getService: jest.fn().mockResolvedValue({ baseUrl: 'http://localhost' }),
+      markUnhealthy: jest.fn(),
+    };
+    const httpService: any = {
+      request: jest.fn().mockReturnValue(of({ data: { ok: true } })),
+    };
+
+    const service = new ServiceMeshService(serviceDiscovery, httpService);
+
+    await expect(service.request('dummy', '/ping', 'GET')).resolves.toEqual({ ok: true });
+
+    expect(httpService.request).toHaveBeenCalledWith(
+      expect.objectContaining({
+        headers: expect.objectContaining({ 'x-request-id': expect.any(String) }),
+      }),
+    );
+  });
+});

src/orchestration/service-mesh/service-mesh.service.ts

@@ -3,6 +3,10 @@ import { HttpService } from '@nestjs/axios';
 import { firstValueFrom } from 'rxjs';
 import { AxiosResponse } from 'axios';
 import { ServiceDiscoveryService } from '../discovery/service-discovery.service';
+import {
+  injectCorrelationIdToHeaders,
+  getCorrelationId,
+} from '../../common/utils/correlation.utils';
 
 @Injectable()
 export class ServiceMeshService {
@@ -20,13 +24,16 @@ export class ServiceMeshService {
     const service = await this.discovery.getService(serviceName);
     const url = `${service.baseUrl}${path}`;
 
+    const correlationId = getCorrelationId();
+
     try {
       const response: AxiosResponse<T> = await firstValueFrom(
         this.httpService.request<T>({
           url,
           method,
           data,
           timeout: 5000,
+          headers: injectCorrelationIdToHeaders(undefined, correlationId),
         }),
       );