@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/extensions/components/request-tracker.md

@@ -1,6 +1,6 @@
 # Request Tracker
 
-Automatic request logging middleware with unique request IDs, client IP detection, body parsing, and timing -- auto-registered by the framework.
+Automatic request logging middleware that assigns a UUID request ID to every request. It logs method, path, client IP, and timing on the way in and out.
 
 > [!IMPORTANT]
 > This component is **auto-registered** by `BaseApplication` during `initialize()`. No manual registration is needed.
@@ -12,7 +12,7 @@ Automatic request logging middleware with unique request IDs, client IP detectio
 | **Package** | `@venizia/ignis` |
 | **Component** | `RequestTrackerComponent` |
 | **Middleware** | `RequestSpyMiddleware` |
-| **Utility** | `getIncomingIp()` |
+| **Utility** | `NetworkUtility.getIncomingIp()` |
 | **Runtimes** | Both (Bun and Node.js) |
 
 #### Import Paths
@@ -20,225 +20,116 @@ Automatic request logging middleware with unique request IDs, client IP detectio
 import { RequestTrackerComponent } from '@venizia/ignis';
 ```
 
-## Setup
+## In one example
 
-### Step 1: Bind Configuration
-
-No configuration binding is required. The component has no user-facing configuration options.
-
-### Step 2: Register Component
-
-This happens automatically inside `BaseApplication.initialize()`:
-
-```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
-
-No injection or manual usage is needed. Once the application starts, every incoming request is automatically logged with a unique request ID.
-
-A sample log output in **non-production** mode looks like this:
+Nothing to configure - once the application starts, every request is logged automatically.
 
 ```
 [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)
 ```
 
-In **production** mode (`NODE_ENV=production`), body is excluded but query is still logged:
+Bodies are logged only in a development environment. Everywhere else - including when `NODE_ENV` is
+unset - the body is omitted and query is still logged:
 
 ```
 [SpyMW] [<request-id>][127.0.0.1][=>] GET      /hello | query: {}
 [SpyMW] [<request-id>][127.0.0.1][<=] GET      /hello | Took: 1.23 (ms)
 ```
 
-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 the framework's error handlers (`notFoundHandler`, `appErrorHandler`), 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.
+The HTTP method is padded to 8 characters for consistent alignment.
 
-| 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 |
+## How it works
 
-> [!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.
+- **One middleware, and an ID it does not install.** `requestId()` comes from `RestApplication.registerDefaultMiddlewares()`, which runs before any component, so it is already in place when `binding()` resolves `RequestSpyMiddleware` from the DI container and registers it. The generator is IGNIS's `RequestIdGenerator`, not hono's `crypto.randomUUID` default - that keeps a server and a browser-Worker BFF stamping the same format.
+- **IP resolution is best-effort, never fatal.** The middleware falls through several sources before giving up - see the resolution order below. An unresolved IP never fails the request; this middleware observes traffic, it does not gate it.
+- **Body logging is environment-gated, and it fails closed.** `RequestSpyMiddleware` reads `NODE_ENV` once in its constructor and logs the body only when the value is one of `local`, `debug`, `development`, `dev`, `sit`. Anything else - `staging`, `uat`, `production`, or `NODE_ENV` unset entirely - logs query only. Query is always logged in every environment.
 
-## 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;
-}
-```
+> [!WARNING]
+> This rule used to be "anything that is not `production`", which logged full request bodies in `staging`, `uat` and with `NODE_ENV` unset. If you relied on bodies appearing outside a development environment, set `NODE_ENV` to one of the five values above.
+- **Body parsing follows Content-Type.** See the outcomes table below for what each Content-Type resolves to. A parse failure throws `'Malformed Body Payload'` (HTTP 400).
+- **The middleware is an `IProvider`, not a plain function.** `RequestSpyMiddleware` implements `IProvider<MiddlewareHandler>` from `@venizia/ignis-inversion`. The container instantiates the class, so it can hold `isDebugMode` state as an instance field. It then calls `.value()` to obtain the actual Hono handler.
 
-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.
+> [!TIP]
+> The request ID is also available in the framework's error handlers (`notFoundHandler`, `AppErrorMiddleware`) - the same ID correlates error logs with the original request.
 
-#### Debug Mode Detection
+## Common tasks
 
-The constructor checks `process.env.NODE_ENV`:
+### Correlate logs with a request
+Read the `requestId` context value inside your own handlers or middleware - the same ID appears in every `[SpyMW]` log line for that request.
 
 ```typescript
-constructor() {
-  super({ scope: 'SpyMW' });
-  const env = process.env.NODE_ENV?.toLowerCase();
-  this.isDebugMode = env !== Environment.PRODUCTION;
-}
+const requestId = context.get('requestId');
 ```
 
-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.
+### Reuse `parseBody` for your own middleware
+`parseBody` is a public method - reuse it wherever you need the same Content-Type-aware parsing.
 
 ```typescript
 async parseBody(opts: { req: TContext['req'] }): Promise<unknown>
 ```
 
-**Return conditions:**
+### Understand the client IP resolution order
+| Priority | Source | Notes |
+|----------|--------|-------|
+| 1 | `NetworkUtility.getIncomingIp(context)` | Native connection info - `hono/bun` on Bun, `@hono/node-server/conninfo` on 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 |
+| 4 | `'unknown'` | Logged when none of the above resolve - the request still proceeds |
 
+### Understand body-parsing outcomes
 | 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 |
+| No `Content-Type` header | `null` |
+| `Content-Length` is `'0'`, or no body stream present | `null` |
+| `Content-Type` includes `application/json` | `req.json()` |
+| `Content-Type` includes `multipart/form-data` or `application/x-www-form-urlencoded` | `req.parseBody()` |
+| `Content-Type` is `application/octet-stream` | Raw body stream |
+| Any other `Content-Type` (text, html, xml, etc.) | `req.text()` |
+| Parsing throws for any content type | `'Malformed Body Payload'` (HTTP 400) |
 
-The `clientIp` used in log output is resolved as `incomingIp ?? forwardedIp` -- meaning connection info takes precedence when available.
+## Reference
 
-If **all three** sources return `null`, the middleware throws a `'Malformed Connection Info'` error with HTTP 400 status.
-
-## Binding Keys
+### Configuration
+No user-configurable options - behavior is fully automatic.
 
+### 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"
+| `middlewares.RequestSpyMiddleware` | `RequestTrackerComponent.REQUEST_TRACKER_MW_BINDING_KEY` | `MiddlewareHandler` | Auto | Singleton provider, registered by the constructor |
 
-**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.
+The key is built as `BindingNamespaces.MIDDLEWARE` (`'middlewares'`) + `.` + `RequestSpyMiddleware.name`.
 
-**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.
+### RequestSpyMiddleware
+```typescript
+class RequestSpyMiddleware extends BaseHelper implements IProvider<MiddlewareHandler> {
+  static readonly REQUEST_ID_KEY = 'requestId';
+  private isDebugMode: boolean;
+  // ...
+}
+```
 
-### "Malformed Connection Info"
+- Extends `BaseHelper` with scope `'SpyMW'`
+- Constructor sets `isDebugMode = process.env.NODE_ENV?.toLowerCase() !== Environment.PRODUCTION`
+- `value()` returns a Hono middleware built via `createMiddleware()` from `hono/factory`
 
-**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.
+### Component lifecycle
+1. **`constructor()`** - Receives `BaseApplication` via DI. Defines the middleware binding as a singleton provider.
+2. **`binding()`** - Resolves the `RequestSpyMiddleware` binding, throwing if it cannot be resolved. Registers the resolved middleware on the server. The request ID is already installed by the application's default stack.
 
-**Fix:** Ensure your reverse proxy (e.g., Nginx, Caddy) forwards at least one of these headers:
-- `x-real-ip`
-- `x-forwarded-for`
+## Troubleshooting
 
-If running without a proxy, ensure the runtime provides connection info (Bun does this natively; Node.js requires `@hono/node-server`).
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `Invalid middleware to init request tracker \| Please check again binding value` | `RequestSpyMiddleware` binding was unbound or overwritten before `binding()` ran | Don't unbind or replace `middlewares.RequestSpyMiddleware`; extend the component instead of removing its binding |
+| `Malformed Body Payload` (400) | Body content didn't match its declared `Content-Type` (e.g., invalid JSON with `application/json`) | Ensure clients send body content that matches the `Content-Type` header |
 
-## See Also
+## See also
 
 - **Guides:**
   - [Components Overview](/guides/core-concepts/components) - Component system basics
@@ -253,3 +144,9 @@ If running without a proxy, ensure the runtime provides connection info (Bun doe
 - **Best Practices:**
   - [Troubleshooting Tips](/best-practices/troubleshooting-tips) - Debugging with request IDs
   - [Deployment Strategies](/best-practices/deployment-strategies) - Production logging
+
+**Files:**
+
+- [`packages/core-server/src/components/request-tracker/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/request-tracker/component.ts) - `RequestTrackerComponent`
+- [`packages/core-server/src/base/middlewares/request-spy/request-spy.middleware.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/base/middlewares/request-spy/request-spy.middleware.ts) - `RequestSpyMiddleware`
+- [`packages/core-server/src/utilities/network.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/utilities/network.utility.ts) - `NetworkUtility.getIncomingIp()`