npm - @venizia/ignis-docs - Versions diffs - 0.0.5 → 0.0.6-0 - Mend

@venizia/ignis-docs 0.0.5 → 0.0.6-0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (98) hide show

package/package.json +1 -1
package/wiki/best-practices/architecture-decisions.md +0 -8
package/wiki/best-practices/code-style-standards/control-flow.md +1 -1
package/wiki/best-practices/performance-optimization.md +3 -3
package/wiki/best-practices/security-guidelines.md +2 -2
package/wiki/best-practices/troubleshooting-tips.md +1 -1
package/wiki/guides/core-concepts/components-guide.md +1 -1
package/wiki/guides/core-concepts/components.md +2 -2
package/wiki/guides/core-concepts/dependency-injection.md +1 -1
package/wiki/guides/core-concepts/services.md +1 -1
package/wiki/guides/tutorials/building-a-crud-api.md +1 -1
package/wiki/guides/tutorials/ecommerce-api.md +2 -2
package/wiki/guides/tutorials/realtime-chat.md +6 -6
package/wiki/guides/tutorials/testing.md +1 -1
package/wiki/references/base/bootstrapping.md +0 -2
package/wiki/references/base/components.md +2 -2
package/wiki/references/base/controllers.md +0 -1
package/wiki/references/base/datasources.md +1 -1
package/wiki/references/base/dependency-injection.md +1 -1
package/wiki/references/base/filter-system/quick-reference.md +0 -14
package/wiki/references/base/middlewares.md +0 -8
package/wiki/references/base/providers.md +0 -9
package/wiki/references/base/services.md +0 -1
package/wiki/references/components/authentication/api.md +444 -0
package/wiki/references/components/authentication/errors.md +177 -0
package/wiki/references/components/authentication/index.md +571 -0
package/wiki/references/components/authentication/usage.md +781 -0
package/wiki/references/components/health-check.md +292 -103
package/wiki/references/components/index.md +14 -12
package/wiki/references/components/mail/api.md +505 -0
package/wiki/references/components/mail/errors.md +176 -0
package/wiki/references/components/mail/index.md +535 -0
package/wiki/references/components/mail/usage.md +404 -0
package/wiki/references/components/request-tracker.md +229 -25
package/wiki/references/components/socket-io/api.md +1051 -0
package/wiki/references/components/socket-io/errors.md +119 -0
package/wiki/references/components/socket-io/index.md +410 -0
package/wiki/references/components/socket-io/usage.md +322 -0
package/wiki/references/components/static-asset/api.md +261 -0
package/wiki/references/components/static-asset/errors.md +89 -0
package/wiki/references/components/static-asset/index.md +617 -0
package/wiki/references/components/static-asset/usage.md +364 -0
package/wiki/references/components/swagger.md +390 -110
package/wiki/references/components/template/api-page.md +125 -0
package/wiki/references/components/template/errors-page.md +100 -0
package/wiki/references/components/template/index.md +104 -0
package/wiki/references/components/template/setup-page.md +134 -0
package/wiki/references/components/template/single-page.md +132 -0
package/wiki/references/components/template/usage-page.md +127 -0
package/wiki/references/components/websocket/api.md +508 -0
package/wiki/references/components/websocket/errors.md +123 -0
package/wiki/references/components/websocket/index.md +453 -0
package/wiki/references/components/websocket/usage.md +475 -0
package/wiki/references/helpers/cron/index.md +224 -0
package/wiki/references/helpers/crypto/index.md +537 -0
package/wiki/references/helpers/env/index.md +214 -0
package/wiki/references/helpers/error/index.md +232 -0
package/wiki/references/helpers/index.md +16 -15
package/wiki/references/helpers/inversion/index.md +608 -0
package/wiki/references/helpers/logger/index.md +600 -0
package/wiki/references/helpers/network/api.md +986 -0
package/wiki/references/helpers/network/index.md +620 -0
package/wiki/references/helpers/queue/index.md +589 -0
package/wiki/references/helpers/redis/index.md +495 -0
package/wiki/references/helpers/socket-io/api.md +497 -0
package/wiki/references/helpers/socket-io/index.md +513 -0
package/wiki/references/helpers/storage/api.md +705 -0
package/wiki/references/helpers/storage/index.md +583 -0
package/wiki/references/helpers/template/index.md +66 -0
package/wiki/references/helpers/template/single-page.md +126 -0
package/wiki/references/helpers/testing/index.md +510 -0
package/wiki/references/helpers/types/index.md +512 -0
package/wiki/references/helpers/uid/index.md +272 -0
package/wiki/references/helpers/websocket/api.md +736 -0
package/wiki/references/helpers/websocket/index.md +574 -0
package/wiki/references/helpers/worker-thread/index.md +470 -0
package/wiki/references/quick-reference.md +3 -18
package/wiki/references/utilities/jsx.md +1 -8
package/wiki/references/utilities/statuses.md +0 -7
package/wiki/references/components/authentication.md +0 -476
package/wiki/references/components/mail.md +0 -687
package/wiki/references/components/socket-io.md +0 -562
package/wiki/references/components/static-asset.md +0 -1277
package/wiki/references/helpers/cron.md +0 -108
package/wiki/references/helpers/crypto.md +0 -132
package/wiki/references/helpers/env.md +0 -83
package/wiki/references/helpers/error.md +0 -97
package/wiki/references/helpers/inversion.md +0 -176
package/wiki/references/helpers/logger.md +0 -296
package/wiki/references/helpers/network.md +0 -396
package/wiki/references/helpers/queue.md +0 -150
package/wiki/references/helpers/redis.md +0 -142
package/wiki/references/helpers/socket-io.md +0 -932
package/wiki/references/helpers/storage.md +0 -665
package/wiki/references/helpers/testing.md +0 -133
package/wiki/references/helpers/types.md +0 -167
package/wiki/references/helpers/uid.md +0 -167
package/wiki/references/helpers/worker-thread.md +0 -178

package/wiki/references/components/mail/usage.md ADDED Viewed

@@ -0,0 +1,404 @@
+# Mail -- Usage & Examples
+> Practical examples for sending emails, using templates, queue executors, verification generators, and batch operations.
+## Sending Emails
+Inject `IMailService` via the `MailKeys.MAIL_SERVICE` binding key to send emails from any service.
+**Sending a simple email:**
+```typescript
+import { BaseService, inject } from '@venizia/ignis';
+import { MailKeys, type IMailService } from '@venizia/ignis/mail';
+export class UserService extends BaseService {
+  constructor(
+    @inject({ key: MailKeys.MAIL_SERVICE })
+    private _mailService: IMailService,
+  ) {
+    super({ scope: UserService.name });
+  }
+  async sendWelcomeEmail(opts: { userEmail: string; userName: string }) {
+    const result = await this._mailService.send({
+      to: opts.userEmail,
+      subject: 'Welcome to Our App!',
+      html: `<h1>Welcome ${opts.userName}!</h1><p>Thanks for joining us.</p>`,
+      text: `Welcome ${opts.userName}! Thanks for joining us.`,
+    });
+    if (result.success) {
+      this.logger.info('[sendWelcomeEmail] Email sent: %s', result.messageId);
+    } else {
+      this.logger.error('[sendWelcomeEmail] Failed to send email: %s', result.error);
+    }
+    return result;
+  }
+}
+```
+**Batch email sending:**
+```typescript
+async sendBulkNotifications(users: Array<{ email: string; name: string }>) {
+  const messages = users.map(user => ({
+    to: user.email,
+    subject: 'Important Update',
+    html: `<p>Hello ${user.name}, we have an important update for you.</p>`,
+  }));
+  const results = await this.mailService.sendBatch(messages, {
+    concurrency: 5, // Send 5 emails at a time
+  });
+  const successCount = results.filter(r => r.success).length;
+  this.logger.info(
+    '[sendBulkNotifications] Sent %d/%d emails successfully',
+    successCount,
+    results.length,
+  );
+  return results;
+}
+```
+**Message validation:**
+The `MailService` validates every message before sending via its internal `validateMessage()` method. This pre-transport check throws immediately if any of these conditions is met:
+| Condition | Error Code | Message |
+|-----------|-----------|---------|
+| `to` is missing or empty array | `MailErrorCodes.INVALID_RECIPIENT` | `Recipient email address is required` |
+| `subject` is missing | `MailErrorCodes.INVALID_CONFIGURATION` | `Email subject is required` |
+| Both `text` and `html` are missing | `MailErrorCodes.INVALID_CONFIGURATION` | `Email must have either text or html content` |
+```typescript
+// This will throw BEFORE reaching the transport
+await mailService.send({
+  to: 'user@example.com',
+  subject: '', // Empty subject triggers validation error
+  html: '<p>Hello</p>',
+});
+// Error: { statusCode: 400, messageCode: 'MAIL_INVALID_CONFIGURATION', message: 'Email subject is required' }
+```
+## Template Engine
+### Using Templates
+Inject both `IMailTemplateEngine` and `IMailService` to register templates and send template-based emails.
+```typescript
+import { BaseService, inject } from '@venizia/ignis';
+import { MailKeys, type IMailTemplateEngine, type IMailService } from '@venizia/ignis/mail';
+export class NotificationService extends BaseService {
+  constructor(
+    @inject({ key: MailKeys.MAIL_TEMPLATE_ENGINE })
+    private templateEngine: IMailTemplateEngine,
+    @inject({ key: MailKeys.MAIL_SERVICE })
+    private mailService: IMailService,
+  ) {
+    super({ scope: NotificationService.name });
+    this.registerTemplates();
+  }
+  registerTemplates() {
+    // Register a welcome email template
+    this.templateEngine.registerTemplate({
+      name: 'welcome-email',
+      content: `
+        <html>
+          <body>
+            <h1>Welcome {{userName}}!</h1>
+            <p>Your account has been created successfully.</p>
+            <p>Your verification code is: <strong>{{verificationCode}}</strong></p>
+          </body>
+        </html>
+      `,
+      options: {
+        subject: 'Welcome to {{appName}}',
+        description: 'Welcome email for new users',
+      },
+    });
+  }
+  async sendWelcomeEmail(userEmail: string, userName: string, verificationCode: string) {
+    const result = await this.mailService.sendTemplate({
+      templateName: 'welcome-email',
+      data: {
+        userName,
+        verificationCode,
+        appName: 'My Application',
+      },
+      recipients: userEmail,
+      options: {
+        // Optional: override template subject or add attachments
+        attachments: [
+          {
+            filename: 'logo.png',
+            path: '/path/to/logo.png',
+            cid: 'logo',
+          },
+        ],
+      },
+    });
+    return result;
+  }
+}
+```
+### Template Rendering
+The `TemplateEngineService` provides a simple <code v-pre>{{variable}}</code> substitution engine using an in-memory `Map<string, ITemplate>` as its template store.
+The `renderSimpleTemplate()` method uses regex `/\{\{(\s*[\w.]+\s*)\}\}/g` to find placeholders. For each match:
+1. The key is trimmed of whitespace
+2. Nested value lookup via dot notation (e.g., `user.profile.name` resolves by splitting on `.` and walking the object)
+3. If the value is `undefined` or `null`, the **original placeholder is preserved as-is** (e.g., <code v-pre>{{missingKey}}</code> remains literally in the output). A warning is logged
+4. Otherwise, the value is converted to string via `String(value)`
+> [!IMPORTANT]
+> Missing template variables are **not** replaced with empty strings. The original <code v-pre>{{placeholder}}</code> text is preserved in the output. This makes debugging easier since you can see which variables were not resolved.
+**Template Features:**
+- Simple <code v-pre>{{variable}}</code> syntax (no loops or conditionals)
+- Nested object access via dot notation: <code v-pre>{{user.profile.name}}</code>
+- Subject line templating (subjects are rendered through the same engine)
+- HTML and plain text support
+- Validation before rendering (optional, throws on missing keys)
+- In-memory template registry (`Map<string, ITemplate>`)
+- Template metadata (subject, description via `ITemplate`)
+- Missing placeholders preserved as-is (not replaced with empty strings)
+- `clearTemplates()` to reset the entire registry
+### Template Validation
+`validateTemplateData()` extracts all unique placeholder keys from a template string and checks if each key resolves to a non-null, non-undefined value in the data object. It returns:
+```typescript
+{
+  isValid: boolean;      // true if all placeholders have values
+  missingKeys: string[]; // placeholder names missing from data
+  allKeys: string[];     // all unique placeholder names found
+}
+```
+When `requireValidate: true` is passed to `render()` or `renderSimpleTemplate()`, validation runs first and throws with `MailErrorCodes.INVALID_CONFIGURATION` if any keys are missing.
+Template validation example:
+```typescript
+const template = '<h1>Hello {{userName}}, your code is {{code}}</h1>';
+const data = { userName: 'John' }; // Missing 'code'
+const validation = this.templateEngine.validateTemplateData({ template, data });
+if (!validation.isValid) {
+  console.error('Missing template variables:', validation.missingKeys);
+  // Output: ['code']
+}
+// Render with validation
+try {
+  const html = this.templateEngine.render({
+    templateData: template,
+    data,
+    requireValidate: true, // Throws error if validation fails
+  });
+} catch (error) {
+  console.error('Template rendering failed:', error.message);
+}
+```
+### Syncing Templates from a Database
+```typescript
+async syncTemplatesFromDatabase() {
+  const templateEngine = this.application.get<IMailTemplateEngine>({
+    key: MailKeys.MAIL_TEMPLATE_ENGINE,
+  });
+  const configRepository = this.application.get<ConfigurationRepository>({
+    key: 'repositories.ConfigurationRepository',
+  });
+  const templateConfigs = await configRepository.find({
+    filter: {
+      where: {
+        code: { inq: ['MAIL_TEMPLATE_WELCOME', 'MAIL_TEMPLATE_VERIFICATION'] },
+      },
+    },
+  });
+  templateConfigs.forEach(config => {
+    templateEngine.registerTemplate({
+      name: config.code,
+      content: config.jValue.content,
+      options: {
+        subject: config.jValue.subject,
+        description: config.jValue.description,
+      },
+    });
+    this.logger.info('[syncTemplates] Registered template: %s', config.code);
+  });
+}
+```
+## Queue Executors
+### Direct Executor
+The simplest executor. `DirectMailExecutorHelper` extends `BaseHelper`. Calls the processor function immediately without any queueing. Returns `{ queued: false, ... }` to indicate no queue was used. Throws if `setProcessor()` has not been called. Useful for development environments or when you need guaranteed synchronous email sending.
+### Internal Queue Executor
+`InternalQueueMailExecutorHelper` extends `BaseHelper`. Uses the in-memory `QueueHelper` from `@venizia/ignis-helpers` with `autoDispatch: true`. Key behaviors:
+- Generates job IDs in the format `job_<counter>_<timestamp>`
+- Supports delayed jobs via `setTimeout` (stored in a `delayedJobs` Map)
+- Retry logic: on failure, retries up to `options.attempts` (default 3) with configurable backoff
+- Backoff calculation: `exponential` uses `delay * 2^(attempt-1)`, `fixed` uses the raw delay, no backoff config defaults to 1000ms
+- Does not persist jobs across restarts
+- Logs queue state changes and individual job lifecycle events
+### BullMQ Executor
+`BullMQMailExecutorHelper` extends `BaseHelper`. Full-featured Redis-backed queue with:
+- Job persistence across restarts
+- Distributed worker support
+- Configurable retry strategies (exponential by default, with 1000ms base delay)
+- Job prioritization
+- Delayed job execution
+- Job progress tracking via worker callbacks
+- `removeOnComplete: true`, `removeOnFail: false` (failed jobs retained for debugging)
+**Mode behavior:**
+| Mode | Queue Initialized | Workers Created | Can Enqueue | Can Process |
+|------|-------------------|-----------------|-------------|-------------|
+| `'queue-only'` | Yes | No (skipped in `setProcessor`) | Yes | No |
+| `'worker-only'` | No | Yes | No (throws) | Yes |
+| `'both'` | Yes | Yes | Yes | Yes |
+## Verification Generators
+Three generators are registered by `MailComponent`:
+- **`NumericCodeGenerator`** -- Implements `IVerificationCodeGenerator`. Generates numeric verification codes of configurable length (e.g., 6-digit `"482917"`)
+- **`RandomTokenGenerator`** -- Implements `IVerificationTokenGenerator`. Generates cryptographically random **base64url**-encoded tokens of configurable byte length
+- **`DefaultVerificationDataGenerator`** -- Implements `IVerificationDataGenerator`. Composes both generators via `@inject` and produces a full `IVerificationData` object with expiry timestamps
+**NumericCodeGenerator:**
+Generates cryptographically random numeric codes. Uses `crypto.randomInt(0, 10^length)` to ensure uniform distribution. The result is zero-padded to the requested length via `padStart()` (e.g., code `42` with length 6 becomes `"000042"`).
+**RandomTokenGenerator:**
+Generates URL-safe random tokens using `crypto.randomBytes(bytes).toString('base64url')`. The output is **base64url-encoded** (not hex). For 32 bytes of input, this produces a 43-character base64url string (not 64 hex characters). Base64url encoding uses characters `A-Z`, `a-z`, `0-9`, `-`, `_` with no padding.
+**DefaultVerificationDataGenerator:**
+Uses `@inject` to receive both `NumericCodeGenerator` (via `MailKeys.MAIL_VERIFICATION_CODE_GENERATOR`) and `RandomTokenGenerator` (via `MailKeys.MAIL_VERIFICATION_TOKEN_GENERATOR`). Produces a complete verification data object with:
+- A short numeric code for manual entry (SMS, email)
+- A long random base64url token for URL-based verification
+- Separate expiry times: code uses `getExpiryTime(minutes)`, token uses `getExpiryTimeInHours(hours)`
+- Generation timestamps in ISO 8601 format
+- Attempt counter (set to 0 initially)
+- `lastCodeSentAt` set to `now`
+**Email verification flow example:**
+```typescript
+import { BaseService, inject } from '@venizia/ignis';
+import {
+  MailKeys,
+  type IMailService,
+  type IVerificationDataGenerator,
+} from '@venizia/ignis/mail';
+export class AuthService extends BaseService {
+  constructor(
+    @inject({ key: MailKeys.MAIL_SERVICE })
+    private mailService: IMailService,
+    @inject({ key: MailKeys.MAIL_VERIFICATION_DATA_GENERATOR })
+    private verificationGenerator: IVerificationDataGenerator,
+  ) {
+    super({ scope: AuthService.name });
+  }
+  async sendVerificationEmail(userEmail: string) {
+    // Generate verification code and token
+    const verificationData = this.verificationGenerator.generateVerificationData({
+      codeLength: 6, // 6-digit code
+      tokenBytes: 32, // 32-byte token
+      codeExpiryMinutes: 10, // Code expires in 10 minutes
+      tokenExpiryHours: 24, // Token expires in 24 hours
+    });
+    // Save verification data to database
+    // await this.saveVerificationData(userEmail, verificationData);
+    // Send verification email
+    const result = await this.mailService.send({
+      to: userEmail,
+      subject: 'Email Verification',
+      html: `
+        <h2>Verify Your Email</h2>
+        <p>Your verification code is: <strong>${verificationData.verificationCode}</strong></p>
+        <p>This code expires at: ${verificationData.codeExpiresAt}</p>
+        <p>Or click this link: https://example.com/verify?token=${verificationData.verificationToken}</p>
+      `,
+    });
+    return { result, verificationData };
+  }
+}
+```
+**Storing verification data:**
+```typescript
+const verificationData = this.verificationGenerator.generateVerificationData({
+  codeLength: 6, // 6-digit code
+  tokenBytes: 32, // 32-byte token -> 43-char base64url string
+  codeExpiryMinutes: 10, // Code expires in 10 minutes
+  tokenExpiryHours: 24, // Token expires in 24 hours
+});
+// Store in database
+await this.userRepo.update({
+  where: { id: userId },
+  data: {
+    verificationCode: verificationData.verificationCode,
+    verificationCodeExpiresAt: new Date(verificationData.codeExpiresAt),
+    verificationToken: verificationData.verificationToken,
+    verificationTokenExpiresAt: new Date(verificationData.tokenExpiresAt),
+  },
+});
+```
+## Security Note
+The `MailComponent.createAndBindInstances()` method logs the full `mailOptions` object at `info` level:
+```typescript
+this.logger.for(this.createAndBindInstances.name).info('Mail Options: %j', mailOptions);
+```
+This includes sensitive fields such as SMTP passwords, OAuth2 client secrets, refresh tokens, and API keys. Similarly, the queue executor config (which may contain Redis passwords) is logged. In production environments, ensure your logging configuration either:
+- Sets the mail component scope to a level higher than `info`
+- Uses a log pipeline that redacts sensitive fields
+- Strips credential fields before binding the options
+## See Also
+- [Setup & Configuration](./) -- Quick reference, setup steps, configuration options, and binding keys
+- [API Reference](./api) -- Architecture, interfaces, and internals
+- [Error Reference](./errors) -- Error codes and troubleshooting

package/wiki/references/components/request-tracker.md CHANGED Viewed

@@ -1,50 +1,254 @@
-# Request Tracker Component
+# Request Tracker
-The Request Tracker component logs incoming requests and adds a unique request ID for tracing purposes.
+Automatic request logging middleware with unique request IDs, client IP detection, body parsing, and timing -- auto-registered by the framework.
-## Overview
+> [!IMPORTANT]
+> This component is **auto-registered** by `BaseApplication` during `initialize()`. No manual registration is needed.
--   **Feature Name:** Request Tracker
--   **Purpose:** To log incoming requests and add a unique request ID for tracing purposes.
--   **Background:** In a production environment, it is crucial to have detailed logs for debugging and monitoring. The Request Tracker component provides a way to automatically log every incoming request with a unique ID, making it easier to trace the entire lifecycle of a request.
--   **Related Features/Modules:** This component is a default middleware that is registered at the application level and integrates with the core logging feature.
+## Quick Reference
-## Design and Architecture
+| Item | Value |
+|------|-------|
+| **Package** | `@venizia/ignis` |
+| **Component** | `RequestTrackerComponent` |
+| **Middleware** | `RequestSpyMiddleware` |
+| **Utility** | `getIncomingIp()` |
+| **Runtimes** | Both (Bun and Node.js) |
--   **`RequestTrackerComponent`:** This component registers the `RequestSpyMiddleware`.
--   **`RequestSpyMiddleware`:** A middleware that intercepts incoming requests, logs them, and adds a request ID to the context. It uses the `requestId` middleware from `hono/request-id` to generate the unique ID.
+#### Import Paths
+```typescript
+import { RequestTrackerComponent } from '@venizia/ignis';
+```
+## Setup
+### Step 1: Bind Configuration
+No configuration binding is required. The component has no user-facing configuration options.
+### Step 2: Register Component
-## Implementation Details
+This happens automatically inside `BaseApplication.initialize()`:
-### Tech Stack
+```typescript
+// Internal to BaseApplication -- shown for reference only
+this.component(RequestTrackerComponent);
+```
+The component registers two Hono middlewares on the application server during its `binding()` phase:
+1. `requestId()` from `hono/request-id` -- generates a UUID and stores it on the Hono context under the key `'requestId'`
+2. `RequestSpyMiddleware` -- logs request start/end with IP, method, path, query, body, and timing
+### Step 3: Use
--   **Hono**
--   **`hono/request-id`**
+No injection or manual usage is needed. Once the application starts, every incoming request is automatically logged with a unique request ID.
-### Configuration
+A sample log output in **non-production** mode looks like this:
-The `RequestTrackerComponent` is enabled by default in `BaseApplication` and requires no manual registration or configuration. It is automatically registered as part of the application's default middleware stack during the `initialize()` lifecycle step.
+```
+[SpyMW] [<request-id>][127.0.0.1][=>] GET      /hello | query: {} | body: null
+[SpyMW] [<request-id>][127.0.0.1][<=] GET      /hello | Took: 1.23 (ms)
+```
-When the component is active, it adds the `requestId` and `RequestSpyMiddleware` to the Hono application instance. A sample log output for a request would look like this:
+In **production** mode (`NODE_ENV=production`), body is excluded but query is still logged:
 ```
-[spy][<request-id>] START | Handling Request | forwardedIp: 127.0.0.1 | path: /hello | method: GET
-[spy][<request-id>] DONE  | Handling Request | forwardedIp: 127.0.0.1 | path: /hello | method: GET | Took: 1.234 (ms)
+[SpyMW] [<request-id>][127.0.0.1][=>] GET      /hello | query: {}
+[SpyMW] [<request-id>][127.0.0.1][<=] GET      /hello | Took: 1.23 (ms)
 ```
-This feature is essential for building production-ready applications with proper logging and traceability.
+The log format follows this structure:
+| Direction | Format |
+|-----------|--------|
+| Incoming (`=>`) | `[requestId][clientIp][=>] METHOD   path \| query: {...} \| body: {...}` |
+| Outgoing (`<=`) | `[requestId][clientIp][<=] METHOD   path \| Took: X.XX (ms)` |
+The HTTP method is padded to 8 characters for consistent alignment in log output.
+> [!TIP]
+> The request ID is also available in error middleware contexts (`NotFoundMiddleware`, `AppErrorMiddleware`), making it easy to correlate error logs with the original request.
+## Configuration
+The Request Tracker component has no user-configurable options. Its behavior is fully automatic.
+| Behavior | Description |
+|----------|-------------|
+| **Request ID** | Generated automatically via `hono/request-id` middleware (UUID), stored on context as `'requestId'` |
+| **IP Detection** | Priority: (1) connection info via `getIncomingIp()`, (2) `x-real-ip` header, (3) `x-forwarded-for` header |
+| **Body Logging** | Logs request body in non-production environments only. Query is always logged |
+| **Timing** | Measures and logs request duration in milliseconds (2 decimal places) via `performance.now()` |
+| **Scope** | Registered as a singleton provider |
+> [!NOTE]
+> In **production** (`NODE_ENV=production`), only the request **body** is excluded from log output to prevent sensitive data exposure. Query parameters are still logged in all environments.
+## Internals
+### RequestTrackerComponent
+The component class extends `BaseComponent`. It receives `BaseApplication` via `@inject({ key: CoreBindings.APPLICATION_INSTANCE })` in its constructor.
+During construction, it creates a singleton binding for the middleware:
+```typescript
+Binding.bind({ key: RequestTrackerComponent.REQUEST_TRACKER_MW_BINDING_KEY })
+  .toProvider(RequestSpyMiddleware)
+  .setScope(BindingScopes.SINGLETON)
+```
+The binding key is constructed as `BindingNamespaces.MIDDLEWARE + '.' + RequestSpyMiddleware.name`, which resolves to `'middlewares.RequestSpyMiddleware'`.
+#### Component Lifecycle
+1. **`constructor()`** -- Receives `BaseApplication` via DI. Defines the middleware binding as a singleton provider.
+2. **`binding()`** -- Registers `requestId()` middleware on the server. Resolves the `RequestSpyMiddleware` binding from the DI container. Throws if the middleware cannot be resolved. Registers the resolved middleware on the server.
+### RequestSpyMiddleware
+The middleware class extends `BaseHelper` with scope `'SpyMW'` and implements `IProvider<MiddlewareHandler>`.
+```typescript
+class RequestSpyMiddleware extends BaseHelper implements IProvider<MiddlewareHandler> {
+  static readonly REQUEST_ID_KEY = 'requestId';
+  private isDebugMode: boolean;
+  // ...
+}
+```
+#### IProvider Pattern
+`RequestSpyMiddleware` implements the `IProvider<T>` interface from `@venizia/ignis-inversion`. This interface requires a single method:
+```typescript
+interface IProvider<T> {
+  value(container: Container): T;
+}
+```
+When the DI container resolves the binding (via `.toProvider(RequestSpyMiddleware)`), it instantiates the class and calls `value()` to obtain the actual `MiddlewareHandler`. This pattern allows the middleware to hold state (like `isDebugMode`) while producing a clean middleware function.
+#### Debug Mode Detection
+The constructor checks `process.env.NODE_ENV`:
+```typescript
+constructor() {
+  super({ scope: 'SpyMW' });
+  const env = process.env.NODE_ENV?.toLowerCase();
+  this.isDebugMode = env !== Environment.PRODUCTION;
+}
+```
+When `isDebugMode` is `true` (any environment other than `'production'`), the incoming request log includes both `query` and `body`. When `false`, only `query` is logged.
+#### value() -- Middleware Handler
+The `value()` method returns a Hono middleware created via `createMiddleware()` from `hono/factory`. The middleware performs the following steps:
+1. Starts a performance timer via `performance.now()`
+2. Extracts the request ID from the Hono context (set by `requestId()` middleware)
+3. Resolves the client IP using the priority chain (see IP Detection below)
+4. Throws `'Malformed Connection Info'` (400) if both `incomingIp` and `forwardedIp` are `null`
+5. Extracts method, path, and query from the request
+6. Parses the request body via `parseBody()`
+7. Logs the incoming request with `[=>]` direction marker
+8. Calls `await next()` to proceed to the next middleware/handler
+9. Calculates duration and logs the outgoing response with `[<=]` direction marker
+#### parseBody()
+A public method that parses the request body based on `Content-Type` and `Content-Length` headers.
+```typescript
+async parseBody(opts: { req: TContext['req'] }): Promise<unknown>
+```
+**Return conditions:**
+| Condition | Result |
+|-----------|--------|
+| No `Content-Type` header | Returns `null` |
+| No `Content-Length` header or value is `'0'` | Returns `null` |
+| `Content-Type` includes `application/json` | Calls `req.json()` |
+| `Content-Type` includes `multipart/form-data` | Calls `req.parseBody()` |
+| `Content-Type` includes `application/x-www-form-urlencoded` | Calls `req.parseBody()` |
+| Any other `Content-Type` (text, html, xml, etc.) | Calls `req.text()` |
+| Parsing fails for any content type | Throws `'Malformed Body Payload'` (HTTP 400) |
+### getIncomingIp() Utility
+A utility function that attempts to extract the client IP address from the Hono context using runtime-specific connection info.
+```typescript
+const getIncomingIp = (context: Context): string | null
+```
+**Runtime detection:**
+- Uses `RuntimeModules.isBun()` from `@venizia/ignis-helpers` to detect the runtime
+- On **Bun**: imports `getConnInfo` from `hono/bun`
+- On **Node.js**: imports `getConnInfo` from `@hono/node-server/conninfo`
+- Returns `connInfo.remote.address` if available, `null` otherwise
+- Returns `null` if `getConnInfo` is unavailable or throws
+#### IP Detection Priority
+The middleware resolves the client IP using a three-step fallback chain:
+| Priority | Source | Description |
+|----------|--------|-------------|
+| 1 | `getIncomingIp(context)` | Direct connection info from the runtime (Bun or Node.js) |
+| 2 | `x-real-ip` header | Set by reverse proxies (e.g., Nginx `proxy_set_header X-Real-IP`) |
+| 3 | `x-forwarded-for` header | Standard proxy header with original client IP |
+The `clientIp` used in log output is resolved as `incomingIp ?? forwardedIp` -- meaning connection info takes precedence when available.
+If **all three** sources return `null`, the middleware throws a `'Malformed Connection Info'` error with HTTP 400 status.
+## Binding Keys
+| Key | Constant | Type | Required | Default |
+|-----|----------|------|----------|---------|
+| `middlewares.RequestSpyMiddleware` | `RequestTrackerComponent.REQUEST_TRACKER_MW_BINDING_KEY` | `MiddlewareHandler` | Auto | Provided by component |
+The key is constructed from `BindingNamespaces.MIDDLEWARE` (`'middlewares'`) + `RequestSpyMiddleware.name` (`'RequestSpyMiddleware'`). The component binds `RequestSpyMiddleware` as a singleton provider at this key during construction.
+## Troubleshooting
+### "Invalid middleware to init request tracker | Please check again binding value"
+**Cause:** The `RequestSpyMiddleware` binding could not be resolved from the DI container during the component's `binding()` phase. This typically means the binding was removed or overwritten before `binding()` executed.
+**Fix:** Ensure no custom code unbinds or replaces the `middlewares.RequestSpyMiddleware` key. If you need to customize request logging, extend the component rather than removing the binding.
+### "Malformed Body Payload"
+**Cause:** The `RequestSpyMiddleware` attempted to parse the request body based on the `Content-Type` header, but the body content was malformed (e.g., invalid JSON with `application/json` content type, or corrupt form data).
+**Fix:** Ensure clients send valid body content that matches the declared `Content-Type` header. This error returns HTTP 400 Bad Request.
+### "Malformed Connection Info"
+**Cause:** The middleware could not determine the client IP address from any source. All three must have failed: (1) `getIncomingIp()` returned `null` (runtime connection info unavailable), (2) `x-real-ip` header was absent, and (3) `x-forwarded-for` header was absent. This error returns HTTP 400 Bad Request.
+**Fix:** Ensure your reverse proxy (e.g., Nginx, Caddy) forwards at least one of these headers:
+- `x-real-ip`
+- `x-forwarded-for`
+If running without a proxy, ensure the runtime provides connection info (Bun does this natively; Node.js requires `@hono/node-server`).
 ## See Also
-- **Related Concepts:**
+- **Guides:**
   - [Components Overview](/guides/core-concepts/components) - Component system basics
   - [Middlewares](/references/base/middlewares) - Request middleware system
-- **Other Components:**
-  - [Components Index](./index) - All built-in components
+- **Components:**
+  - [All Components](./index) - Built-in components list
-- **References:**
-  - [Logger Helper](/references/helpers/logger) - Logging utilities
+- **Helpers:**
+  - [Logger Helper](/references/helpers/logger/) - Logging utilities
 - **Best Practices:**
   - [Troubleshooting Tips](/best-practices/troubleshooting-tips) - Debugging with request IDs