cariff-logger 0.0.0-stage → 1.0.1

package/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to NPM
+
+on:
+  release:
+    types: [created]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies & Build
+        run: |
+          npm install
+          npm run build
+
+      - name: Publish to NPM
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# cariff-logger
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Стандартизированный модуль структурированного JSON логирования и распределенного трейсинга для микросервисов платформы **Cariff**.
+
+## 🚀 Особенности
+
+- **Zero heavy runtime dependencies:** работает нативно поверх `stdout`/`stderr` и Node.js `AsyncLocalStorage`.
+- **Строгая NDJSON схема в production:**
+  - `timestamp`: ISO 8601
+  - `level`: `INFO`, `WARN`, `ERROR`, `FATAL` (уровень `DEBUG` подавлен в проде)
+  - `service`: идентификатор сервиса (`api-gateway`, `auth-service` и т.д.)
+  - `message`: понятный текст события
+  - `correlationId`: сквозной идентификатор запроса (автоматически пробрасывается из контекста)
+  - `context`, `metadata`, `stack`
+- **Readable colored output в development:** цветной читаемый вывод для локальной разработки.
+- **Интеграция с NestJS:** реализует `LoggerService`.
+
+## 📦 Установка
+
+```bash
+yarn add cariff-logger
+# или
+npm install cariff-logger
+```
+
+## 🛠 Использование в NestJS
+
+### 1. Подключение глобального логгера (`main.ts`)
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+import { CariffLogger, setupGlobalErrorHandlers } from 'cariff-logger';
+
+async function bootstrap() {
+  const serviceName = 'auth-service';
+  setupGlobalErrorHandlers(serviceName);
+
+  const app = await NestFactory.create(AppModule, {
+    logger: new CariffLogger(serviceName),
+  });
+
+  await app.listen(3333);
+}
+bootstrap();
+```
+
+### 2. Подключение Middleware для Correlation ID (`app.module.ts`)
+
+```typescript
+import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
+import { CorrelationIdMiddleware } from 'cariff-logger';
+
+@Module({})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(new CorrelationIdMiddleware('api-gateway')).forRoutes('*');
+  }
+}
+```
+
+### 3. Логирование внутри сервисов
+
+Используйте стандартный NestJS `Logger` — все вызовы автоматически будут отформатированы по стандарту:
+
+```typescript
+import { Injectable, Logger } from '@nestjs/common';
+
+@Injectable()
+export class UserService {
+  private readonly logger = new Logger(UserService.name);
+
+  async getUser(id: string) {
+    this.logger.log('Fetching user details'); // Автоматически прикрепит correlationId!
+  }
+}
+```

package/dist/context.d.ts

@@ -0,0 +1,10 @@
+export interface LogContext {
+    correlationId?: string;
+    [key: string]: unknown;
+}
+export declare class LoggerContextStore {
+    static run<R>(context: LogContext, fn: () => R): R;
+    static getCorrelationId(): string | undefined;
+    static getContext(): LogContext | undefined;
+    static set(key: string, value: unknown): void;
+}

package/dist/context.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoggerContextStore = void 0;
+const async_hooks_1 = require("async_hooks");
+const asyncLocalStorage = new async_hooks_1.AsyncLocalStorage();
+class LoggerContextStore {
+    static run(context, fn) {
+        return asyncLocalStorage.run(context, fn);
+    }
+    static getCorrelationId() {
+        return asyncLocalStorage.getStore()?.correlationId;
+    }
+    static getContext() {
+        return asyncLocalStorage.getStore();
+    }
+    static set(key, value) {
+        const store = asyncLocalStorage.getStore();
+        if (store) {
+            store[key] = value;
+        }
+    }
+}
+exports.LoggerContextStore = LoggerContextStore;

package/dist/fatal.d.ts

@@ -0,0 +1 @@
+export declare function setupGlobalErrorHandlers(serviceName: string): void;

package/dist/fatal.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupGlobalErrorHandlers = setupGlobalErrorHandlers;
+const logger_service_1 = require("./logger.service");
+function setupGlobalErrorHandlers(serviceName) {
+    const logger = new logger_service_1.CariffLogger(serviceName);
+    process.on('uncaughtException', (error) => {
+        logger.fatal({
+            message: `Uncaught Exception: ${error?.message || error}`,
+            error: error?.message,
+        }, error?.stack, 'Process');
+        // Allow stdout/stderr to flush before exiting
+        setTimeout(() => {
+            process.exit(1);
+        }, 100);
+    });
+    process.on('unhandledRejection', (reason) => {
+        const error = reason instanceof Error ? reason : new Error(String(reason));
+        logger.fatal({
+            message: `Unhandled Rejection: ${error.message}`,
+            error: error.message,
+        }, error.stack, 'Process');
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './context';
+export * from './logger.service';
+export * from './middleware';
+export * from './fatal';

package/dist/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("./context"), exports);
+__exportStar(require("./logger.service"), exports);
+__exportStar(require("./middleware"), exports);
+__exportStar(require("./fatal"), exports);

package/dist/logger.service.d.ts

@@ -0,0 +1,29 @@
+import { LoggerService } from '@nestjs/common';
+export type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    service: string;
+    message: string;
+    correlationId?: string;
+    context?: string;
+    stack?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface LoggerOptions {
+    serviceName: string;
+    isProduction?: boolean;
+}
+export declare class CariffLogger implements LoggerService {
+    private serviceName;
+    private isProduction;
+    constructor(serviceNameOrOptions?: string | LoggerOptions);
+    setServiceName(name: string): void;
+    log(message: any, context?: string): void;
+    error(message: any, trace?: string, context?: string): void;
+    warn(message: any, context?: string): void;
+    debug?(message: any, context?: string): void;
+    verbose?(message: any, context?: string): void;
+    fatal(message: any, trace?: string, context?: string): void;
+    private writeLog;
+}

package/dist/logger.service.js

@@ -0,0 +1,128 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CariffLogger = void 0;
+const common_1 = require("@nestjs/common");
+const context_1 = require("./context");
+let CariffLogger = class CariffLogger {
+    serviceName;
+    isProduction;
+    constructor(serviceNameOrOptions = 'cariff-service') {
+        if (typeof serviceNameOrOptions === 'string') {
+            this.serviceName = serviceNameOrOptions;
+            this.isProduction = process.env.NODE_ENV === 'production';
+        }
+        else {
+            this.serviceName = serviceNameOrOptions.serviceName;
+            this.isProduction = serviceNameOrOptions.isProduction ?? process.env.NODE_ENV === 'production';
+        }
+    }
+    setServiceName(name) {
+        this.serviceName = name;
+    }
+    log(message, context) {
+        this.writeLog('INFO', message, context);
+    }
+    error(message, trace, context) {
+        this.writeLog('ERROR', message, context, trace);
+    }
+    warn(message, context) {
+        this.writeLog('WARN', message, context);
+    }
+    debug(message, context) {
+        if (this.isProduction) {
+            return; // Suppress DEBUG in production according to spec
+        }
+        this.writeLog('DEBUG', message, context);
+    }
+    verbose(message, context) {
+        if (this.isProduction) {
+            return;
+        }
+        this.writeLog('DEBUG', message, context);
+    }
+    fatal(message, trace, context) {
+        this.writeLog('FATAL', message, context, trace);
+    }
+    writeLog(level, message, context, stack) {
+        const timestamp = new Date().toISOString();
+        const correlationId = context_1.LoggerContextStore.getCorrelationId();
+        let textMessage = '';
+        let metadata;
+        if (typeof message === 'object' && message !== null) {
+            if (message instanceof Error) {
+                textMessage = message.message;
+                stack = stack || message.stack;
+            }
+            else {
+                const { msg, message: msgField, ...rest } = message;
+                textMessage = (msgField || msg || JSON.stringify(message));
+                if (Object.keys(rest).length > 0) {
+                    metadata = rest;
+                }
+            }
+        }
+        else {
+            textMessage = String(message);
+        }
+        if (this.isProduction) {
+            // Production: strict single-line flat NDJSON to stdout/stderr
+            const logEntry = {
+                timestamp,
+                level,
+                service: this.serviceName,
+                message: textMessage,
+                ...(correlationId ? { correlationId } : {}),
+                ...(context ? { context } : {}),
+                ...(stack ? { stack } : {}),
+                ...(metadata ? { metadata } : {}),
+            };
+            const jsonString = JSON.stringify(logEntry) + '\n';
+            if (level === 'ERROR' || level === 'FATAL') {
+                process.stderr.write(jsonString);
+            }
+            else {
+                process.stdout.write(jsonString);
+            }
+        }
+        else {
+            // Development: Human-friendly colored terminal output
+            const colors = {
+                DEBUG: '\x1b[34m', // Blue
+                INFO: '\x1b[32m', // Green
+                WARN: '\x1b[33m', // Yellow
+                ERROR: '\x1b[31m', // Red
+                FATAL: '\x1b[35;1m', // Magenta bold
+            };
+            const reset = '\x1b[0m';
+            const gray = '\x1b[90m';
+            const cyan = '\x1b[36m';
+            const color = colors[level] || reset;
+            const ctx = context ? ` ${cyan}[${context}]${reset}` : '';
+            const corr = correlationId ? ` ${gray}(corr: ${correlationId})${reset}` : '';
+            const formatted = `${gray}${timestamp}${reset} ${color}${level.padEnd(5)}${reset} ${gray}[${this.serviceName}]${reset}${ctx}${corr} ${textMessage}`;
+            if (level === 'ERROR' || level === 'FATAL') {
+                process.stderr.write(formatted + '\n');
+                if (stack) {
+                    process.stderr.write(`${gray}${stack}${reset}\n`);
+                }
+            }
+            else {
+                process.stdout.write(formatted + '\n');
+            }
+        }
+    }
+};
+exports.CariffLogger = CariffLogger;
+exports.CariffLogger = CariffLogger = __decorate([
+    (0, common_1.Injectable)({ scope: common_1.Scope.DEFAULT }),
+    __metadata("design:paramtypes", [Object])
+], CariffLogger);

package/dist/middleware.d.ts

@@ -0,0 +1,22 @@
+import { NestMiddleware } from '@nestjs/common';
+export declare const CORRELATION_ID_HEADER = "x-correlation-id";
+export interface HttpRequestLike {
+    headers: Record<string, string | string[] | undefined>;
+    method: string;
+    url: string;
+    originalUrl?: string;
+    ip?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+}
+export interface HttpResponseLike {
+    statusCode: number;
+    setHeader(name: string, value: string): void;
+    on(event: 'finish' | string, listener: () => void): this;
+}
+export declare class CorrelationIdMiddleware implements NestMiddleware {
+    private readonly logger;
+    constructor(serviceName?: string);
+    use(req: HttpRequestLike, res: HttpResponseLike, next: (error?: any) => void): void;
+}

package/dist/middleware.js

@@ -0,0 +1,67 @@
+"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.CorrelationIdMiddleware = exports.CORRELATION_ID_HEADER = void 0;
+const common_1 = require("@nestjs/common");
+const crypto_1 = require("crypto");
+const context_1 = require("./context");
+const logger_service_1 = require("./logger.service");
+exports.CORRELATION_ID_HEADER = 'x-correlation-id';
+let CorrelationIdMiddleware = class CorrelationIdMiddleware {
+    logger;
+    constructor(serviceName) {
+        this.logger = new logger_service_1.CariffLogger(serviceName || 'api-gateway');
+    }
+    use(req, res, next) {
+        const rawId = req.headers[exports.CORRELATION_ID_HEADER] || req.headers['x-request-id'];
+        const correlationId = (Array.isArray(rawId) ? rawId[0] : rawId) || (0, crypto_1.randomUUID)();
+        // Propagate in response header
+        res.setHeader(exports.CORRELATION_ID_HEADER, correlationId);
+        const startTime = Date.now();
+        context_1.LoggerContextStore.run({ correlationId }, () => {
+            // Log on response finish
+            res.on('finish', () => {
+                const durationMs = Date.now() - startTime;
+                const statusCode = res.statusCode;
+                const method = req.method;
+                const url = req.originalUrl || req.url;
+                const message = `${method} ${url} ${statusCode} - ${durationMs}ms`;
+                const metadata = {
+                    method,
+                    url,
+                    statusCode,
+                    durationMs,
+                    ip: req.ip || req.socket?.remoteAddress,
+                    userAgent: req.headers['user-agent'],
+                };
+                if (statusCode >= 500) {
+                    this.logger.error({ message, ...metadata }, undefined, 'HTTP');
+                }
+                else if (statusCode >= 400) {
+                    this.logger.warn({ message, ...metadata }, 'HTTP');
+                }
+                else {
+                    this.logger.log({ message, ...metadata }, 'HTTP');
+                }
+            });
+            next();
+        });
+    }
+};
+exports.CorrelationIdMiddleware = CorrelationIdMiddleware;
+exports.CorrelationIdMiddleware = CorrelationIdMiddleware = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Optional)()),
+    __metadata("design:paramtypes", [String])
+], CorrelationIdMiddleware);

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "cariff-logger",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Unified structured JSON logger and correlation ID tracing module for Cariff microservices",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "cariff",
+    "nestjs",
+    "logger",
+    "structured-logging",
+    "json-logging",
+    "correlation-id",
+    "loki"
+  ],
+  "author": "Cariff Marketplace",
+  "license": "MIT",
+  "peerDependencies": {
+    "@nestjs/common": ">=9.0.0",
+    "@nestjs/core": ">=9.0.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/core": "^11.0.1",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/context.ts

@@ -0,0 +1,29 @@
+import { AsyncLocalStorage } from 'async_hooks';
+
+export interface LogContext {
+  correlationId?: string;
+  [key: string]: unknown;
+}
+
+const asyncLocalStorage = new AsyncLocalStorage<LogContext>();
+
+export class LoggerContextStore {
+  static run<R>(context: LogContext, fn: () => R): R {
+    return asyncLocalStorage.run(context, fn);
+  }
+
+  static getCorrelationId(): string | undefined {
+    return asyncLocalStorage.getStore()?.correlationId;
+  }
+
+  static getContext(): LogContext | undefined {
+    return asyncLocalStorage.getStore();
+  }
+
+  static set(key: string, value: unknown): void {
+    const store = asyncLocalStorage.getStore();
+    if (store) {
+      store[key] = value;
+    }
+  }
+}

package/src/fatal.ts

@@ -0,0 +1,32 @@
+import { CariffLogger } from './logger.service';
+
+export function setupGlobalErrorHandlers(serviceName: string): void {
+  const logger = new CariffLogger(serviceName);
+
+  process.on('uncaughtException', (error: Error) => {
+    logger.fatal(
+      {
+        message: `Uncaught Exception: ${error?.message || error}`,
+        error: error?.message,
+      },
+      error?.stack,
+      'Process',
+    );
+    // Allow stdout/stderr to flush before exiting
+    setTimeout(() => {
+      process.exit(1);
+    }, 100);
+  });
+
+  process.on('unhandledRejection', (reason: unknown) => {
+    const error = reason instanceof Error ? reason : new Error(String(reason));
+    logger.fatal(
+      {
+        message: `Unhandled Rejection: ${error.message}`,
+        error: error.message,
+      },
+      error.stack,
+      'Process',
+    );
+  });
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './context';
+export * from './logger.service';
+export * from './middleware';
+export * from './fatal';

package/src/logger.service.ts

@@ -0,0 +1,140 @@
+import { Injectable, LoggerService, Scope } from '@nestjs/common';
+import { LoggerContextStore } from './context';
+
+export type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
+
+export interface LogEntry {
+  timestamp: string;
+  level: LogLevel;
+  service: string;
+  message: string;
+  correlationId?: string;
+  context?: string;
+  stack?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface LoggerOptions {
+  serviceName: string;
+  isProduction?: boolean;
+}
+
+@Injectable({ scope: Scope.DEFAULT })
+export class CariffLogger implements LoggerService {
+  private serviceName: string;
+  private isProduction: boolean;
+
+  constructor(serviceNameOrOptions: string | LoggerOptions = 'cariff-service') {
+    if (typeof serviceNameOrOptions === 'string') {
+      this.serviceName = serviceNameOrOptions;
+      this.isProduction = process.env.NODE_ENV === 'production';
+    } else {
+      this.serviceName = serviceNameOrOptions.serviceName;
+      this.isProduction = serviceNameOrOptions.isProduction ?? process.env.NODE_ENV === 'production';
+    }
+  }
+
+  setServiceName(name: string): void {
+    this.serviceName = name;
+  }
+
+  log(message: any, context?: string): void {
+    this.writeLog('INFO', message, context);
+  }
+
+  error(message: any, trace?: string, context?: string): void {
+    this.writeLog('ERROR', message, context, trace);
+  }
+
+  warn(message: any, context?: string): void {
+    this.writeLog('WARN', message, context);
+  }
+
+  debug?(message: any, context?: string): void {
+    if (this.isProduction) {
+      return; // Suppress DEBUG in production according to spec
+    }
+    this.writeLog('DEBUG', message, context);
+  }
+
+  verbose?(message: any, context?: string): void {
+    if (this.isProduction) {
+      return;
+    }
+    this.writeLog('DEBUG', message, context);
+  }
+
+  fatal(message: any, trace?: string, context?: string): void {
+    this.writeLog('FATAL', message, context, trace);
+  }
+
+  private writeLog(level: LogLevel, message: any, context?: string, stack?: string): void {
+    const timestamp = new Date().toISOString();
+    const correlationId = LoggerContextStore.getCorrelationId();
+
+    let textMessage = '';
+    let metadata: Record<string, unknown> | undefined;
+
+    if (typeof message === 'object' && message !== null) {
+      if (message instanceof Error) {
+        textMessage = message.message;
+        stack = stack || message.stack;
+      } else {
+        const { msg, message: msgField, ...rest } = message;
+        textMessage = (msgField || msg || JSON.stringify(message)) as string;
+        if (Object.keys(rest).length > 0) {
+          metadata = rest;
+        }
+      }
+    } else {
+      textMessage = String(message);
+    }
+
+    if (this.isProduction) {
+      // Production: strict single-line flat NDJSON to stdout/stderr
+      const logEntry: LogEntry = {
+        timestamp,
+        level,
+        service: this.serviceName,
+        message: textMessage,
+        ...(correlationId ? { correlationId } : {}),
+        ...(context ? { context } : {}),
+        ...(stack ? { stack } : {}),
+        ...(metadata ? { metadata } : {}),
+      };
+
+      const jsonString = JSON.stringify(logEntry) + '\n';
+      if (level === 'ERROR' || level === 'FATAL') {
+        process.stderr.write(jsonString);
+      } else {
+        process.stdout.write(jsonString);
+      }
+    } else {
+      // Development: Human-friendly colored terminal output
+      const colors: Record<LogLevel, string> = {
+        DEBUG: '\x1b[34m',   // Blue
+        INFO: '\x1b[32m',    // Green
+        WARN: '\x1b[33m',    // Yellow
+        ERROR: '\x1b[31m',   // Red
+        FATAL: '\x1b[35;1m', // Magenta bold
+      };
+      const reset = '\x1b[0m';
+      const gray = '\x1b[90m';
+      const cyan = '\x1b[36m';
+
+      const color = colors[level] || reset;
+      const ctx = context ? ` ${cyan}[${context}]${reset}` : '';
+      const corr = correlationId ? ` ${gray}(corr: ${correlationId})${reset}` : '';
+      const formatted = `${gray}${timestamp}${reset} ${color}${level.padEnd(5)}${reset} ${gray}[${this.serviceName}]${reset}${ctx}${corr} ${textMessage}`;
+
+      if (level === 'ERROR' || level === 'FATAL') {
+        process.stderr.write(formatted + '\n');
+        if (stack) {
+          process.stderr.write(`${gray}${stack}${reset}\n`);
+        }
+      } else {
+        process.stdout.write(formatted + '\n');
+      }
+    }
+  }
+}

package/src/middleware.ts

@@ -0,0 +1,70 @@
+import { Injectable, NestMiddleware, Optional } from '@nestjs/common';
+import { randomUUID } from 'crypto';
+import { LoggerContextStore } from './context';
+import { CariffLogger } from './logger.service';
+
+export const CORRELATION_ID_HEADER = 'x-correlation-id';
+
+export interface HttpRequestLike {
+  headers: Record<string, string | string[] | undefined>;
+  method: string;
+  url: string;
+  originalUrl?: string;
+  ip?: string;
+  socket?: { remoteAddress?: string };
+}
+
+export interface HttpResponseLike {
+  statusCode: number;
+  setHeader(name: string, value: string): void;
+  on(event: 'finish' | string, listener: () => void): this;
+}
+
+@Injectable()
+export class CorrelationIdMiddleware implements NestMiddleware {
+  private readonly logger: CariffLogger;
+
+  constructor(@Optional() serviceName?: string) {
+    this.logger = new CariffLogger(serviceName || 'api-gateway');
+  }
+
+  use(req: HttpRequestLike, res: HttpResponseLike, next: (error?: any) => void): void {
+    const rawId = req.headers[CORRELATION_ID_HEADER] || req.headers['x-request-id'];
+    const correlationId = (Array.isArray(rawId) ? rawId[0] : rawId) || randomUUID();
+
+    // Propagate in response header
+    res.setHeader(CORRELATION_ID_HEADER, correlationId);
+
+    const startTime = Date.now();
+
+    LoggerContextStore.run({ correlationId }, () => {
+      // Log on response finish
+      res.on('finish', () => {
+        const durationMs = Date.now() - startTime;
+        const statusCode = res.statusCode;
+        const method = req.method;
+        const url = req.originalUrl || req.url;
+
+        const message = `${method} ${url} ${statusCode} - ${durationMs}ms`;
+        const metadata = {
+          method,
+          url,
+          statusCode,
+          durationMs,
+          ip: req.ip || req.socket?.remoteAddress,
+          userAgent: req.headers['user-agent'],
+        };
+
+        if (statusCode >= 500) {
+          this.logger.error({ message, ...metadata }, undefined, 'HTTP');
+        } else if (statusCode >= 400) {
+          this.logger.warn({ message, ...metadata }, 'HTTP');
+        } else {
+          this.logger.log({ message, ...metadata }, 'HTTP');
+        }
+      });
+
+      next();
+    });
+  }
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "types": ["node"],
+    "module": "commonjs",
+    "target": "ES2022",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "baseUrl": ".",
+    "paths": {
+      "*": ["/Users/molix/cariff-backend/api-gateway/node_modules/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist"]
+}