@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

package/content/extensions/components/mail/usage.md

@@ -1,4 +1,4 @@
-# Mail -- Usage & Examples
+# Mail - Usage & Examples
 
 > Practical examples for sending emails, using templates, queue executors, and verification generators.
 
@@ -72,7 +72,7 @@ async sendBulkNotifications(users: Array<{ email: string; name: string }>) {
 
 ### Message validation
 
-`MailService.validateMessage()` runs before every send and throws immediately -- before the transport is ever called -- if any of these hold:
+`MailService.validateMessage()` runs before every send. It throws immediately - before the transport is ever called - if any of these hold:
 
 | Condition | Error code | Message |
 |-----------|-----------|---------|
@@ -144,19 +144,19 @@ export class NotificationService extends BaseService {
 }
 ```
 
-- **Subject resolution order.** `options.subject` (explicit override) beats the template's own `subject` (rendered through the same engine) beats the literal fallback `'No Subject'`.
-- **`sendTemplate()` requires the template engine binding.** It throws `INVALID_CONFIGURATION` ("Template engine not configured") if `MailKeys.MAIL_TEMPLATE_ENGINE` was never injected -- the constructor parameter is `isOptional: true`, so a service that skips it degrades silently until the first `sendTemplate()` call.
+- **Subject resolution order.** `options.subject` wins if you pass it. Otherwise the template's own `subject` wins, rendered through the same engine. If neither is set, the subject falls back to the literal `'No Subject'`.
+- **`sendTemplate()` requires the template engine binding.** It throws `INVALID_CONFIGURATION` ("Template engine not configured") if `MailKeys.MAIL_TEMPLATE_ENGINE` was never injected. The constructor parameter is `isOptional: true`, so a service still compiles without it - but the first `sendTemplate()` call then fails.
 
 ### How rendering works
 
-`TemplateEngineService` keeps templates in an in-memory `Map<string, ITemplate>` and substitutes <code v-pre>{{variable}}</code> placeholders with regex `/\{\{(\s*[\w.]+\s*)\}\}/g`.
+`TemplateEngineService` keeps templates in an in-memory `Map<string, ITemplate>`. It substitutes <code v-pre>{{variable}}</code> placeholders using the regex `/\{\{(\s*[\w.]+\s*)\}\}/g`.
 
 - **Nested lookup.** A key is trimmed, then resolved by splitting on `.` and walking the data object (`user.profile.name`).
-- **Missing values are preserved, not blanked.** If a resolved value is `undefined` or `null`, the original <code v-pre>{{placeholder}}</code> text stays in the output and a warning is logged -- it is never replaced with an empty string.
-- **String coercion.** A resolved value is converted with `String(value)`.
+- **Missing values are preserved, not blanked.** If a resolved value is `undefined` or `null`, the original <code v-pre>{{placeholder}}</code> text stays in the output, and a warning is logged. The engine never replaces it with an empty string.
+- **String coercion.** The engine converts a resolved value with `String(value)`.
 
 > [!IMPORTANT]
-> Missing template variables are **not** replaced with empty strings. This makes debugging easier -- you can see which variables were not resolved directly in the rendered output.
+> Missing template variables are **not** replaced with empty strings. This makes debugging easier: the rendered output shows you exactly which variables did not resolve.
 
 ### Validate template data before sending
 
@@ -221,7 +221,7 @@ async syncTemplatesFromDatabase() {
 
 ## Queue executors
 
-`IMailQueueExecutor` is a separate subsystem from `MailService` -- it only exposes `enqueueVerificationEmail()` and `setProcessor()`, and never calls `send()` on its own. You provide the processor function (typically one that wraps `mailService.send()`); the executor's job is timing, retry, and delivery guarantees around calling it.
+`IMailQueueExecutor` is a separate subsystem from `MailService`. It only exposes `enqueueVerificationEmail()` and `setProcessor()`, and it never calls `send()` on its own. You provide the processor function - typically one that wraps `mailService.send()`. The executor's job is timing, retry, and delivery guarantees around calling that function.
 
 | Executor | Class | Backing |
 |----------|-------|---------|
@@ -231,17 +231,25 @@ async syncTemplatesFromDatabase() {
 
 ### Direct executor
 
-Calls the processor immediately, with no queueing. Returns `{ queued: false, ... }`. Throws `Processor not set. Call setProcessor() first.` if `enqueueVerificationEmail()` runs before `setProcessor()`. Use it for development or when a caller needs a synchronous result.
+The direct executor calls the processor immediately, with no queueing. It returns `{ queued: false, ... }`. If `enqueueVerificationEmail()` runs before `setProcessor()`, it throws `Processor not set. Call setProcessor() first.` Use it for development, or whenever a caller needs a synchronous result.
 
 ### Internal queue executor
 
-In-memory, single-instance, backed by `SequentialQueueHelper` from `@venizia/ignis-helpers` with `autoDispatch: true`.
+The internal queue executor is in-memory and single-instance, backed by `SequentialQueueHelper` from `@venizia/ignis-helpers` with `autoDispatch: true`.
 
 - Job IDs follow `job_<counter>_<timestamp>`.
 - A `delay` option schedules the enqueue itself via `setTimeout`, tracked in a `delayedJobs` map.
-- On failure (a thrown error, or the processor returning `{ success: false }`), it retries up to `options.attempts` (default `3`) with backoff: `exponential` is `delay * 2^(attempt - 1)`, `fixed` is the raw delay, and no `backoff` config at all defaults to `1000ms`.
+- On failure - a thrown error, or the processor returning `{ success: false }` - it retries up to `options.attempts` (default `3`).
 - Does not persist jobs across restarts. `close()` clears every pending delayed/retry timer.
 
+Retry backoff:
+
+| `backoff` config | Delay |
+|---|---|
+| `{ type: 'exponential', delay }` | `delay * 2^(attempt - 1)` |
+| `{ type: 'fixed', delay }` | the raw `delay` |
+| Not set | `1000ms` |
+
 ### BullMQ executor
 
 Redis-backed, distributed, backed by `BullMQHelper`. Job persistence, worker concurrency, prioritization, and delayed execution come from BullMQ itself. `removeOnComplete: true`, `removeOnFail: false` (failed jobs stay for debugging). Default enqueue options: `attempts: 3`, `backoff: { type: 'exponential', delay: 1000 }`.
@@ -255,9 +263,9 @@ Redis-backed, distributed, backed by `BullMQHelper`. Job persistence, worker con
 | `'both'` | Yes | Yes | Yes (requires `setProcessor()` first) | Yes |
 
 > [!IMPORTANT]
-> `'queue-only'` mode is the one exception to "call `setProcessor()` before you enqueue" -- `enqueueVerificationEmail()` only requires a processor when the mode is *not* `queue-only`. A producer instance can enqueue jobs a separate `worker-only` instance later processes.
+> `'queue-only'` mode is the one exception to "call `setProcessor()` before you enqueue." In that mode, `enqueueVerificationEmail()` does not need a processor. A producer instance can enqueue jobs that a separate `worker-only` instance later processes.
 
-**Dynamic worker management** -- get the bound instance and manage workers at runtime, no restart required:
+**Dynamic worker management.** Get the bound instance and manage workers at runtime - no restart required:
 
 ```typescript
 const executor = this.application.get<BullMQMailExecutorHelper>({
@@ -273,7 +281,7 @@ await executor.removeWorker(1); // remove by array index
 await executor.clearWorkers();  // close and remove every worker
 ```
 
-`setProcessor()` on the BullMQ executor is `async` and takes an optional second argument for worker configuration -- it clears all existing workers before creating new ones:
+`setProcessor()` on the BullMQ executor is `async` and takes an optional second argument for worker configuration. It clears all existing workers before creating new ones:
 
 ```typescript
 await executor.setProcessor(
@@ -291,7 +299,7 @@ await executor.setProcessor(
 
 ## Verification generators
 
-`MailComponent` binds three generators, all **transient** (a fresh instance per resolution, since none is registered with `.setScope('singleton')`):
+`MailComponent` binds three generators. All are **transient** - a fresh instance per resolution, since none is registered with `.setScope('singleton')`:
 
 | Generator | Implements | Behavior |
 |-----------|-----------|----------|
@@ -350,10 +358,10 @@ export class AuthService extends BaseService {
 
 ## Logging and credentials
 
-`MailComponent.createAndBindInstances()` logs only `mailOptions.provider` and `queueExecutorConfig.type` at `info` level -- by design, never the full config objects, so SMTP passwords, OAuth2 secrets, API keys, and Redis passwords never reach a log sink through the component itself.
+`MailComponent.createAndBindInstances()` logs only `mailOptions.provider` and `queueExecutorConfig.type`, at `info` level. It never logs the full config objects, by design. That keeps SMTP passwords, OAuth2 secrets, API keys, and Redis passwords out of the log sink - at least through the component itself.
 
 > [!WARNING]
-> That guarantee only covers what `MailComponent` logs internally. If your own wrapper component or bootstrap code logs the `TMailOptions` or `IMailQueueExecutorConfig` object directly (for example, while debugging a binding), you reintroduce the leak yourself -- log individual safe fields (`provider`, `type`) instead of the whole object.
+> That guarantee only covers what `MailComponent` logs internally. If your own wrapper component or bootstrap code logs the `TMailOptions` or `IMailQueueExecutorConfig` object directly, you reintroduce the leak yourself. This commonly happens while debugging a binding. Log individual safe fields (`provider`, `type`) instead of the whole object.
 
 ## See also
 

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

@@ -1,6 +1,6 @@
 # Request Tracker
 
-Automatic request logging middleware that assigns a UUID request ID to every request, then logs method, path, client IP, and timing on the way in and out.
+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 that assigns a UUID request ID to every req
 | **Package** | `@venizia/ignis` |
 | **Component** | `RequestTrackerComponent` |
 | **Middleware** | `RequestSpyMiddleware` |
-| **Utility** | `getIncomingIp()` |
+| **Utility** | `NetworkUtility.getIncomingIp()` |
 | **Runtimes** | Both (Bun and Node.js) |
 
 #### Import Paths
@@ -29,7 +29,8 @@ Nothing to configure - once the application starts, every request is logged auto
 [SpyMW] [<request-id>][127.0.0.1][<=] GET      /hello | Took: 1.23 (ms)
 ```
 
-In **production** (`NODE_ENV=production`), the body is omitted; 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: {}
@@ -45,14 +46,17 @@ The HTTP method is padded to 8 characters for consistent alignment.
 
 ## How it works
 
-- **Two middlewares, one component.** `binding()` registers Hono's own `requestId()` (from `hono/request-id`) first, then resolves `RequestSpyMiddleware` from the DI container and registers it - `requestId()` must run first so the spy can read the ID off the context.
-- **IP resolution is best-effort, never fatal.** The middleware tries `getIncomingIp()` (runtime connection info), then `x-real-ip`, then `x-forwarded-for`; if none resolve it logs `'unknown'` instead of failing the request - this middleware observes traffic, it does not gate it.
-- **Body logging is environment-gated.** `RequestSpyMiddleware` reads `NODE_ENV` once in its constructor: any value other than `'production'` logs the body; `'production'` logs query only. Query is always logged in every environment.
-- **Body parsing follows Content-Type.** JSON, multipart, and URL-encoded bodies use Hono's own parsers; `application/octet-stream` returns the raw stream; everything else is read as text. 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) and calls `.value()` to obtain the actual Hono handler.
+- **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.
+
+> [!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.
 
 > [!TIP]
-> The request ID is also available in the framework's error handlers (`notFoundHandler`, `AppErrorMiddleware`), making it easy to correlate error logs with the original request.
+> The request ID is also available in the framework's error handlers (`notFoundHandler`, `AppErrorMiddleware`) - the same ID correlates error logs with the original request.
 
 ## Common tasks
 
@@ -73,7 +77,7 @@ async parseBody(opts: { req: TContext['req'] }): Promise<unknown>
 ### Understand the client IP resolution order
 | Priority | Source | Notes |
 |----------|--------|-------|
-| 1 | `getIncomingIp(context)` | Native connection info - `hono/bun` on Bun, `@hono/node-server/conninfo` on Node.js |
+| 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 |
@@ -116,7 +120,7 @@ class RequestSpyMiddleware extends BaseHelper implements IProvider<MiddlewareHan
 
 ### Component lifecycle
 1. **`constructor()`** - Receives `BaseApplication` via DI. Defines the middleware binding as a singleton provider.
-2. **`binding()`** - Registers `requestId()` on the server. Resolves the `RequestSpyMiddleware` binding, throwing if it cannot be resolved. Registers the resolved middleware on the server.
+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.
 
 ## Troubleshooting
 
@@ -143,6 +147,6 @@ class RequestSpyMiddleware extends BaseHelper implements IProvider<MiddlewareHan
 
 **Files:**
 
-- [`packages/core/src/components/request-tracker/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/request-tracker/component.ts) - `RequestTrackerComponent`
-- [`packages/core/src/base/middlewares/request-spy/request-spy.middleware.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/middlewares/request-spy/request-spy.middleware.ts) - `RequestSpyMiddleware`
-- [`packages/core/src/utilities/network.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/utilities/network.utility.ts) - `getIncomingIp()`
+- [`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()`