@infineit/winston-logger 1.0.39 → 1.0.40

package/README.md

@@ -45,11 +45,12 @@ npm install @infineit/winston-logger
 
 This package requires the following peer dependencies (usually already installed in NestJS projects):
 
-- `@nestjs/common` 11.1.9
-- `@nestjs/config` 4.2.0
-- `@nestjs/core` 11.1.9
-- `nestjs-cls` 5.0.1
-- `uuid` (required for correlation ID generation in HTTP contexts)
+- `@nestjs/common` ^11.1.11
+- `@nestjs/config` ^4.0.2
+- `@nestjs/core` ^11.1.11
+- `nestjs-cls` ^6.2.0 (required for CLS context management - correlation IDs)
+
+**Note:** The `uuid` package is **NOT** required by this library. If you need correlation ID generation in your application code (e.g., in middleware), you can install `uuid` separately. The library itself does not generate correlation IDs - it only reads them from CLS context.
 
 ### ⚠️ Critical Setup Requirement
 
@@ -251,9 +252,9 @@ You can also configure via `@nestjs/config`:
 ```typescript
 // .env
 NODE_ENV=production
-SLACK_WEBHOOK=https://hooks.slack.com/services/...
-CONSOLE_PRINT=true
-LOG_IN_FILE=true
+LOGGER_SLACK_INC_WEBHOOK_URL=https://hooks.slack.com/services/...
+LOGGER_CONSOLE_PRINT=true
+LOGGER_LOG_IN_FILE=true
 LOGGER_ORGANIZATION=my-org
 LOGGER_CONTEXT=user-service
 LOGGER_APP=api-gateway
@@ -271,19 +272,24 @@ LOGGER_HTTP_ENDPOINT=https://logging-service.example.com/api/logs
 // logger.config.ts
 import { registerAs } from '@nestjs/config';
 
+const getBooleanEnvVar = (key: string, defaultValue: boolean = false): boolean => {
+    const value = process.env[key];
+    return value ? value.toLowerCase() === 'true' : defaultValue;
+};
+
 export default registerAs('logger', () => ({
-  nodeEnv: process.env.NODE_ENV,
-  slack_webhook: process.env.SLACK_WEBHOOK,
-  console_print: process.env.CONSOLE_PRINT,
-  log_in_file: process.env.LOG_IN_FILE,
-  organization: process.env.LOGGER_ORGANIZATION,
-  context: process.env.LOGGER_CONTEXT,
-  app: process.env.LOGGER_APP,
+  nodeEnv: process.env.NODE_ENV || 'development',
+  slack_webhook: process.env.LOGGER_SLACK_INC_WEBHOOK_URL || undefined,
+  console_print: getBooleanEnvVar('LOGGER_CONSOLE_PRINT', false),
+  log_in_file: getBooleanEnvVar('LOGGER_LOG_IN_FILE', false),
+  organization: process.env.LOGGER_ORGANIZATION || undefined,
+  context: process.env.LOGGER_CONTEXT || undefined,
+  app: process.env.LOGGER_APP || undefined,
   // Optional: Central log forwarding
-  forwardToCentral: process.env.LOGGER_FORWARD_TO_CENTRAL,
-  transportType: process.env.LOGGER_TRANSPORT_TYPE,
-  httpEndpoint: process.env.LOGGER_HTTP_ENDPOINT,
-  kafkaTopic: process.env.LOGGER_KAFKA_TOPIC,
+  forwardToCentral: process.env.LOGGER_FORWARD_TO_CENTRAL === 'true' || process.env.LOGGER_FORWARD_TO_CENTRAL === true,
+  transportType: process.env.LOGGER_TRANSPORT_TYPE as 'http' | 'kafka' | undefined,
+  httpEndpoint: process.env.LOGGER_HTTP_ENDPOINT || undefined,
+  kafkaTopic: process.env.LOGGER_KAFKA_TOPIC || undefined,
 }));
 ```
 
@@ -312,17 +318,29 @@ export class AppModule {}
 | `organization` | `string` | No | `undefined` | Organization or project name |
 | `context` | `string` | No | `undefined` | Bounded context name |
 | `app` | `string` | No | `undefined` | Application or microservice name |
-| `forwardToCentral` | `boolean \| string` | No | `false` | Enable forwarding to centralized logging service (`true`/`false` or `'true'`/`'false'`) |
-| `transportType` | `'kafka' \| 'http'` | No | `undefined` | Transport type for central forwarding (required if `forwardToCentral=true`) |
-| `httpEndpoint` | `string` | No | `undefined` | HTTP endpoint for central forwarding (required if `transportType='http'`) |
-| `kafkaTopic` | `string` | No | `undefined` | Kafka topic for central forwarding (required if `transportType='kafka'`) |
+| `forwardToCentral` | `boolean \| string` | No | `false` | Enable forwarding to centralized logging service. Accepts: `true`, `false`, `'true'`, `'false'`, or `undefined`. Only `true` or `'true'` enables forwarding. |
+| `transportType` | `'kafka' \| 'http'` | No | `undefined` | Transport type for central forwarding. **Required** if `forwardToCentral=true`. Invalid config returns `null` (logged to console.error, no exception thrown). |
+| `httpEndpoint` | `string` | No | `undefined` | HTTP endpoint for central forwarding. **Required** if `transportType='http'`. Invalid config returns `null`. HTTP requests have 5-second timeout. |
+| `kafkaTopic` | `string` | No | `undefined` | Kafka topic for central forwarding. **Required** if `transportType='kafka'`. Invalid config returns `null`. Requires `KafkaProducerKey` provider. |
 
 ### Default Behavior
 
-- **Development/Testing**: Console and file logging enabled by default
-- **Production**: Console and file logging disabled by default (unless explicitly enabled)
-- **Slack**: Only enabled in production/testing when `slack_webhook` is provided
-- **Central Forwarding**: Disabled by default (set `forwardToCentral=true` to enable)
+**Console and File Logging:**
+- **Development environments** (`NODE_ENV='development'` or `undefined`): Console and file logging are **automatically enabled** regardless of `console_print`/`log_in_file` settings (code: `(!isProduction && !isTesting) || consolePrint`)
+- **Production or testing environments** (`NODE_ENV='production'` or `'testing'`): Console and file logging are **disabled by default** and must be explicitly enabled via `LOGGER_CONSOLE_PRINT=true` or `LOGGER_LOG_IN_FILE=true`
+
+**Slack:**
+- Only enabled in **production or testing** when `slack_webhook` is provided
+- Disabled in development environments
+
+**Central Forwarding:**
+- **Disabled by default** (set `forwardToCentral=true` to enable)
+- Requires `transportType` ('http' or 'kafka') and corresponding endpoint/topic
+
+**Configuration Merge Precedence:**
+- `LoggerModule.forRoot(config)` parameter takes precedence over `ConfigService` values
+- If both are provided, parameter values override ConfigService values
+- If forwarding is disabled (false/undefined), `CentralLogForwarder` returns `null` (no errors thrown)
 
 ### Environment-Specific Configuration Tips
 
@@ -330,10 +348,10 @@ export class AppModule {}
 ```bash
 # Disable forwarding in development (optional)
 LOGGER_FORWARD_TO_CENTRAL=false
-# OR use local endpoint for testing
+# OR use local endpoint for testing (separate service/port required)
 LOGGER_FORWARD_TO_CENTRAL=true
 LOGGER_TRANSPORT_TYPE=http
-LOGGER_HTTP_ENDPOINT=http://localhost:3000/api/logs
+LOGGER_HTTP_ENDPOINT=http://127.0.0.1:3062/api/logs  # Different port/service
 ```
 
 **Production:**
@@ -341,7 +359,7 @@ LOGGER_HTTP_ENDPOINT=http://localhost:3000/api/logs
 # Enable forwarding in production
 LOGGER_FORWARD_TO_CENTRAL=true
 LOGGER_TRANSPORT_TYPE=http
-LOGGER_HTTP_ENDPOINT=https://central-logging.example.com/api/logs
+LOGGER_HTTP_ENDPOINT=https://central-logging.example.com/api/logs  # Separate service
 # OR use Kafka for better performance
 # LOGGER_TRANSPORT_TYPE=kafka
 # LOGGER_KAFKA_TOPIC=project-logs-<project-name>
@@ -796,18 +814,18 @@ Central log forwarding is completely fire-and-forget:
 # Option 1: Disable forwarding in development
 LOGGER_FORWARD_TO_CENTRAL=false
 
-# Option 2: Use local endpoint for testing
+# Option 2: Use local endpoint for testing (separate service/port required)
 LOGGER_FORWARD_TO_CENTRAL=true
 LOGGER_TRANSPORT_TYPE=http
-LOGGER_HTTP_ENDPOINT=http://localhost:3000/api/logs
+LOGGER_HTTP_ENDPOINT=http://127.0.0.1:3062/api/logs  # Different port/service
 ```
 
 **Production:**
 ```bash
-# HTTP forwarding (simpler setup)
+# HTTP forwarding (simpler setup, separate service required)
 LOGGER_FORWARD_TO_CENTRAL=true
 LOGGER_TRANSPORT_TYPE=http
-LOGGER_HTTP_ENDPOINT=https://central-logging.example.com/api/logs
+LOGGER_HTTP_ENDPOINT=https://central-logging.example.com/api/logs  # Separate service
 
 # OR Kafka forwarding (better performance, requires Kafka producer)
 LOGGER_FORWARD_TO_CENTRAL=true
@@ -831,11 +849,16 @@ LOGGER_KAFKA_TOPIC=project-logs-common
 ### Troubleshooting
 
 **Forwarding Not Working:**
-1. Check configuration: `LOGGER_FORWARD_TO_CENTRAL` must be `'true'` or `true`
-2. Verify transport type: Must be `'http'` or `'kafka'`
-3. Check endpoint/topic: Must be configured correctly
-4. For Kafka: Ensure `KafkaProducerKey` is provided in module providers
-5. Check console errors: Forwarding errors are logged to `console.error` with message `"CentralLogForwarder forward error (swallowed): <error>"`
+1. Check configuration: `LOGGER_FORWARD_TO_CENTRAL` must be `'true'` or `true` (not `'false'`, `false`, or `undefined`)
+2. Verify transport type: Must be exactly `'http'` or `'kafka'` (case-sensitive)
+3. Check endpoint/topic: Must be configured correctly (HTTP endpoint must be valid URL, Kafka topic must be non-empty string)
+4. For Kafka: Ensure `KafkaProducerKey` is provided in module providers (otherwise forwarding is silently skipped)
+5. Check console errors: Forwarding errors are logged to `console.error` with messages:
+   - `"CentralLogForwarder: Invalid configuration - transportType and endpoint/topic required"` (factory returns `null` for invalid config)
+   - `"[HttpCentralLogForwarder] Forward error (swallowed): <error>"` (HTTP forwarding errors during forward())
+   - `"HttpCentralLogForwarder error (swallowed): <error>"` (HTTP request errors)
+   - `"KafkaCentralLogForwarder forward error (swallowed): <error>"` (Kafka forwarding errors)
+   - `"KafkaCentralLogForwarder send error (swallowed): <error>"` (Kafka producer send() errors)
 
 **Correlation ID Missing:**
 - Ensure `ContextModule` is imported: `ContextModule` automatically configures `ClsModule` with `generateId: true`
@@ -843,10 +866,11 @@ LOGGER_KAFKA_TOPIC=project-logs-common
 - Check that original logs have `correlationId` field (if not, forwarded logs won't either)
 
 **HTTP Forwarding Timeout:**
-- HTTP forwarding has a 5-second timeout
-- Timeouts are swallowed (no errors thrown)
-- Consider using Kafka instead if central service is slow
-- Or improve central service performance
+- HTTP forwarding has a **5-second timeout** (code: `req.setTimeout(5000)`)
+- Timeouts are swallowed (no errors thrown, request destroyed silently)
+- If timeout occurs, request is destroyed (`req.destroy()`) and error is logged to `console.error`
+- Consider using Kafka instead if central service is slow or unreliable
+- Or improve central service performance/availability
 
 **Note:** Forwarding failures do not affect your application. Original logging continues normally, and business logic is never impacted.
 
@@ -2272,6 +2296,122 @@ export class AppModule {}
 
 ---
 
+---
+
+## Configuration Truth Table
+
+### Environment Variable → Behavior Mapping
+
+| Environment Variable | Value | Behavior |
+|---------------------|-------|----------|
+| `NODE_ENV` | `'production'` or `'testing'` | Console/file logging **disabled by default** (must explicitly set `LOGGER_CONSOLE_PRINT=true` or `LOGGER_LOG_IN_FILE=true`); Slack enabled if webhook provided |
+| `NODE_ENV` | `'development'` or `undefined` | Console/file logging **enabled automatically** (code: `(!isProduction && !isTesting) || consolePrint`); `console_print`/`log_in_file` settings ignored |
+| `LOGGER_CONSOLE_PRINT` | `true` or `'true'` | Console logging enabled (overrides environment default) |
+| `LOGGER_CONSOLE_PRINT` | `false`, `'false'`, or `undefined` | Console logging follows environment default (disabled in prod/testing, enabled in development) |
+| `LOGGER_LOG_IN_FILE` | `true` or `'true'` | File logging enabled (overrides environment default) |
+| `LOGGER_LOG_IN_FILE` | `false`, `'false'`, or `undefined` | File logging follows environment default (disabled in prod/testing, enabled in development) |
+| `LOGGER_FORWARD_TO_CENTRAL` | `true` or `'true'` | Central forwarding **enabled** (requires `transportType` and endpoint/topic) |
+| `LOGGER_FORWARD_TO_CENTRAL` | `false`, `'false'`, `undefined`, or not set | Central forwarding **disabled** (returns `null`, no errors) |
+| `LOGGER_TRANSPORT_TYPE` | `'http'` | HTTP forwarding enabled (requires `LOGGER_HTTP_ENDPOINT`) |
+| `LOGGER_TRANSPORT_TYPE` | `'kafka'` | Kafka forwarding enabled (requires `LOGGER_KAFKA_TOPIC` and `KafkaProducerKey` provider) |
+| `LOGGER_TRANSPORT_TYPE` | Invalid or `undefined` | Forwarding disabled (returns `null`, logs error to console.error) |
+| `LOGGER_HTTP_ENDPOINT` | Valid URL | HTTP forwarding active (5-second timeout) |
+| `LOGGER_HTTP_ENDPOINT` | Invalid or `undefined` | Forwarding disabled if `transportType='http'` (returns `null`, logs error) |
+| `LOGGER_KAFKA_TOPIC` | Valid string | Kafka forwarding active (if `KafkaProducerKey` provided) |
+| `LOGGER_KAFKA_TOPIC` | `undefined` | Forwarding disabled if `transportType='kafka'` (returns `null`, logs error) |
+
+### Configuration Precedence Rules
+
+1. **`LoggerModule.forRoot(config)` parameter** takes precedence over `ConfigService` values
+2. If `forwardToCentral` is `false`, `undefined`, or invalid → `CentralLogForwarder` returns `null` (no exceptions)
+3. If `transportType` or endpoint/topic is invalid → `CentralLogForwarder` returns `null` (logs error, no exceptions)
+4. Invalid configuration does **not** throw errors - failures are swallowed to preserve fire-and-forget behavior
+
+---
+
+## Code Audit Summary
+
+### Verified Behavior (as implemented)
+
+**Configuration Reading:**
+- Configuration can be provided via `LoggerModule.forRoot(config)` parameter OR `ConfigService`
+- Parameter config takes precedence over `ConfigService` when both are provided
+- Factory merges both sources: `loggerConfig.forwardToCentral ?? configFromService?.forwardToCentral`
+- Invalid configuration returns `null` (does not throw exceptions)
+
+**Environment-Based Defaults:**
+- **Non-production/non-testing**: Console and file transports automatically enabled (code: `(!isProduction && !isTesting) || consolePrint`)
+- **Production/testing**: Console and file transports disabled unless explicitly enabled via `console_print`/`log_in_file`
+- Slack transport only enabled in production/testing when `slack_webhook` is provided
+
+**Central Forwarding:**
+- `forwardToCentral` must be exactly `true` or `'true'` to enable (string comparison: `=== 'true'`)
+- HTTP forwarding uses Node.js built-in `http`/`https` modules (no external dependencies)
+- HTTP requests have 5-second timeout (code: `req.setTimeout(5000)`)
+- Kafka forwarding requires `KafkaProducerKey` provider (optional injection, returns `null` if not provided)
+- Forwarding failures are swallowed (logged to `console.error`, never throw)
+
+**Fire-and-Forget Guarantee:**
+- All logging methods return `void` (non-blocking)
+- All transport errors are caught and swallowed (never propagate)
+- Central forwarding errors are caught at multiple levels (forwarder, service, transport)
+- No async/await in logging code (all synchronous fire-and-forget)
+
+**Dependency Injection:**
+- `LoggerService` is provided both via `LoggerKey` (Symbol) and class token
+- Direct class injection works: `constructor(private readonly logger: LoggerService)`
+- `CentralLogForwarder` is optional injection (`@Optional()`) - returns `null` if not configured
+- `KafkaProducerKey` is optional injection in factory - returns `null` if not provided
+
+**CLS Integration:**
+- `ContextModule` uses `nestjs-cls@6.2.0` (not 5.0.1) with `mount: true` and `generateId: true`
+- Correlation ID is optional (`undefined` is valid)
+- Correlation ID is included in HTTP header (`x-correlation-id`) when forwarding
+- Correlation ID is included in Kafka message key and headers when forwarding
+
+### Unused / Removable Dependencies (Safe to Remove)
+
+**Root `package.json` (`/package.json`):**
+- `uuid` (version 13.0.0) - **NOT used in library code** (`libs/src/`). Only appears in README examples. **Safe to remove** if application code (`apps/`) doesn't use it for correlation ID generation.
+
+**Note:** The library does **not** generate correlation IDs. Applications must either:
+- Rely on `ContextModule`'s automatic generation (HTTP contexts via `ClsModule` with `generateId: true`)
+- Generate IDs manually in application code (e.g., middleware, Kafka consumers)
+- Pass correlation IDs from external sources (HTTP headers, Kafka message headers)
+
+**Library `package.json` (`libs/package.json`):**
+- ✅ **REMOVED**: `@types/uuid` (version ^9.0.6) - **NOT used** in library code. Removed from devDependencies.
+- All other dependencies are **verified as used**:
+  - `@nestjs/common`, `@nestjs/config`, `@nestjs/core` - Core NestJS dependencies
+  - `nestjs-cls@6.2.0` - Used in `ContextModule` and `NestjsClsContextStorageService`
+  - `winston`, `winston-daily-rotate-file`, `winston-slack-webhook-transport` - Used in Winston transports
+  - `reflect-metadata`, `rxjs` - Required by NestJS
+
+**Dead Code (Not Removed - Exported for Manual Use):**
+- `CentralLogForwarder` class exists but is **not used by `LoggerModule`**. The module factory creates `HttpCentralLogForwarder` or `KafkaCentralLogForwarder` directly. However, the class is exported in `index.ts` for potential manual use, so it's kept for backward compatibility.
+
+### Environment Variable Name Corrections
+
+**Actual environment variable names (as implemented in `apps/src/config/logger.config.ts`):**
+- ✅ `LOGGER_SLACK_INC_WEBHOOK_URL` (not `SLACK_WEBHOOK`)
+- ✅ `LOGGER_CONSOLE_PRINT` (not `CONSOLE_PRINT`)
+- ✅ `LOGGER_LOG_IN_FILE` (not `LOG_IN_FILE`)
+- ✅ `LOGGER_ORGANIZATION`, `LOGGER_CONTEXT`, `LOGGER_APP` (correct)
+- ✅ `LOGGER_FORWARD_TO_CENTRAL`, `LOGGER_TRANSPORT_TYPE`, `LOGGER_HTTP_ENDPOINT`, `LOGGER_KAFKA_TOPIC` (correct)
+
+### Fail-Fast Behavior
+
+**Important:** The library does **NOT** fail-fast for invalid configuration:
+- Invalid `forwardToCentral` → Returns `null`, no error thrown
+- Invalid `transportType` → Returns `null`, logs to `console.error`, no exception
+- Missing `httpEndpoint` or `kafkaTopic` → Returns `null`, logs to `console.error`, no exception
+- Invalid HTTP endpoint URL → Constructor throws (expected - invalid URL is a programming error)
+- Missing `KafkaProducerKey` → Kafka forwarding silently skipped (returns `null`, no error)
+
+**Rationale:** Fail-fast behavior would violate the fire-and-forget guarantee. Invalid configuration should not crash the application - it should gracefully degrade (disable forwarding) and log the issue.
+
+---
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infineit/winston-logger",
-  "version": "1.0.39",
+  "version": "1.0.40",
   "description": "Enterprise-level logger integration package",
   "main": "index.js",
   "types": "index.d.ts",
@@ -21,7 +21,6 @@
     "winston-slack-webhook-transport": "2.3.6"
   },
   "devDependencies": {
-    "@types/uuid": "^9.0.6",
     "@types/winston": "^2.4.4",
     "rimraf": "^6.0.1"
   },