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

package/content/extensions/helpers/network/api.md

@@ -8,6 +8,20 @@ difficulty: intermediate
 
 Exhaustive reference for `BaseNetworkRequest` and its fetchers, the TCP/TLS client-server hierarchy, `NetworkUdpClient`, and every option type. For a readable introduction and the most common tasks, start with the [Network overview](/extensions/helpers/network/).
 
+## Find what you need
+
+| You're looking for | Go to |
+|---|---|
+| The HTTP client base class and URL helpers | [BaseNetworkRequest](#basenetworkrequest) |
+| Axios-backed HTTP client | [AxiosFetcher](#axiosfetcher) / [AxiosNetworkRequest](#axiosnetworkrequest) |
+| Native-`fetch`-backed HTTP client | [NodeFetcher](#nodefetcher) / [NodeFetchNetworkRequest](#nodefetchnetworkrequest) |
+| Why the `QUERY` method must reach the wire uppercase | [HTTP.Methods](#http-methods) |
+| Secret redaction in request logs | [Request Logging and Redaction](#request-logging-and-redaction) |
+| Plain TCP or TLS server, client tracking, authentication | [BaseNetworkTcpServer](#basenetworktcpserver) |
+| Plain TCP or TLS client, auto-reconnect behavior | [BaseNetworkTcpClient](#basenetworktcpclient) |
+| UDP client and multicast | [NetworkUdpClient](#networkudpclient) |
+| Every option and type in one place | [Types Reference](#types-reference) |
+
 **Files:**
 
 - [`packages/helpers/src/modules/network/http-request/base-network-request.helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/network/http-request/base-network-request.helper.ts) - `BaseNetworkRequest`
@@ -48,7 +62,7 @@ AbstractNetworkFetchableHelper<V, RQ, RS>  (implements IFetchable, NOT a BaseHel
   └── NodeFetcher                      (V = 'node-fetch')
 ```
 
-All classes that extend `BaseHelper` inherit scoped logging via `this.logger`. `AbstractNetworkFetchableHelper` and its two fetchers do **not** extend `BaseHelper` - they accept an optional `logger` parameter per call instead (see the Request Logging & Redaction section under HTTP Request API).
+Every class that extends `BaseHelper` inherits scoped logging via `this.logger`. `AbstractNetworkFetchableHelper` and its two fetchers do **not** extend `BaseHelper`. They accept an optional `logger` parameter per call instead - see [Request Logging and Redaction](#request-logging-and-redaction).
 
 ---
 
@@ -161,7 +175,7 @@ interface IFetchable<
 }
 ```
 
-All HTTP method shortcuts (`get`, `post`, `put`, `patch`, `delete`, `query`) delegate to `send()` with the `method` field set accordingly. `query` sends the HTTP `QUERY` method ([RFC 9110/10008](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-10.html)) - a `GET`-semantics request that carries a body, useful for search payloads too large for a query string.
+All HTTP method shortcuts (`get`, `post`, `put`, `patch`, `delete`, `query`) delegate to `send()` with the `method` field set accordingly. `query` sends the HTTP `QUERY` method ([RFC 9110/10008](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-10.html)). It behaves like `GET` but carries a body - useful for search payloads too large to fit a query string.
 
 ### IRequestOptions
 
@@ -175,7 +189,9 @@ interface IRequestOptions {
 }
 ```
 
-### HTTP.Methods - the const-class every fetcher dispatches on
+### HTTP.Methods
+
+The const-class every fetcher dispatches on:
 
 ```typescript
 HTTP.Methods = {
@@ -188,9 +204,15 @@ type THttpMethod = ValueOf<typeof HTTP.Methods> | Uppercase<ValueOf<typeof HTTP.
 
 > [!IMPORTANT]
 > - **Every `HTTP.Methods` token is lowercase.** `@hono/zod-openapi` route definitions accept no other case.
-> - **Both fetchers accept either case on input** (`method: 'post'` or `method: 'POST'`) but always call `method.toUpperCase()` immediately before dispatching to their transport.
-> - **This is not cosmetic.** Node's undici (the `fetch` implementation on Node, not Bun) auto-normalizes only `DELETE`/`GET`/`HEAD`/`OPTIONS`/`POST`/`PUT` and sends any other token (`PATCH`, `QUERY`) through verbatim - a lowercase `patch` would reach the server unchanged and most servers reject it.
-> - **Bun and Axios hide the bug.** Bun's `fetch` and Axios (via `node:http`) uppercase every method themselves, so the bug surfaces only once the app runs on Node with undici.
+> - **Both fetchers accept either case on input**, `'post'` or `'POST'`. Each calls `method.toUpperCase()` immediately before dispatching to its transport.
+> - **This is not cosmetic.** Node's undici is the `fetch` implementation on Node - not Bun - and it auto-normalizes only some methods:
+>
+>   | Auto-normalized by undici | Sent through verbatim |
+>   |---|---|
+>   | `DELETE`, `GET`, `HEAD`, `OPTIONS`, `POST`, `PUT` | `PATCH`, `QUERY` |
+>
+>   A lowercase `patch` or `query` reaches the server unchanged, and most servers reject it.
+> - **Bun and Axios hide the bug.** Bun's `fetch` and Axios both uppercase every method themselves - Axios via `node:http`. The bug surfaces only once the app runs on Node with undici.
 
 ---
 
@@ -275,7 +297,7 @@ constructor(opts: {
 })
 ```
 
-`opts.logger`, if provided, logs `'Creating new network request worker instance! Name: %s'` once at construction time - unrelated to the per-call `logger` argument on `send()`.
+`opts.logger`, if provided, logs `'Creating new network request worker instance! Name: %s'` once at construction time. This is unrelated to the per-call `logger` argument on `send()`.
 
 #### IAxiosRequestOptions
 
@@ -292,7 +314,7 @@ interface IAxiosRequestOptions extends AxiosRequestConfig, IRequestOptions {
 > [!NOTE]
 > - **`body` maps to Axios's `data`** field internally.
 > - **Query `params` are serialized** using `node:querystring` via Axios's `paramsSerializer`.
-> - **HTTPS gets an `https.Agent` automatically**, with `rejectUnauthorized` defaulting to `false` - override it per request with `rejectUnauthorized: true`.
+> - **HTTPS gets an `https.Agent` automatically.** Certificate verification is ON, and connections are kept alive. Pass `rejectUnauthorized: false` - on the fetcher, for the whole instance, or on a single request - only when you genuinely mean to accept an unverified certificate. A caller-supplied `httpsAgent` always wins, so a custom CA, pinning or mTLS agent is honoured as given.
 
 #### Methods
 
@@ -389,9 +411,9 @@ override async send(opts: INodeFetchRequestOptions, logger?: any): Promise<Respo
 Dispatches the request using the native `fetch` API. Behavior:
 
 - `method` defaults to `HTTP.Methods.GET` and is uppercased before dispatch.
-- Query `params` are serialized with `node:querystring` and appended to `url` - with `?` if the URL carries no query string yet, `&` if it already does (never a double `?`).
+- Query `params` are serialized with `node:querystring` and appended to `url`. The separator adapts: `?` when the URL carries no query string yet, `&` when it already does - never a double `?`.
 - If `timeout` is provided, an internal `AbortController` aborts the request after that many milliseconds.
-  - The internal timeout signal is **composed**, never substituted, with a caller-supplied `signal`: `AbortSignal.any([signal, timeoutController.signal])` when both are present - so a caller aborting its own signal still cancels the request even while a timeout is also armed.
+  - The internal timeout signal is **composed**, never substituted, with a caller-supplied `signal`. When both are present, IGNIS builds `AbortSignal.any([signal, timeoutController.signal])`. That way a caller aborting its own signal still cancels the request, even while a timeout is also armed.
   - The timer is cleared as soon as the request settles.
 - If `logger` is passed, logs `'URL: %s | Props: %s | Timeout: %s'` at `info` level with the request config run through `redactSecrets()`.
 
@@ -429,7 +451,7 @@ interface INodeFetchNetworkRequestOptions {
 If `headers` is a `Headers` instance, it is converted to a plain object via `Object.fromEntries(headers.entries())` before merging with the default.
 
 > [!WARNING] `timeout` is per-call, not per-instance
-> `networkOptions` is `RequestInit`, which has no `timeout` field - passing one there has no effect on request cancellation. `NodeFetcher.send()` only reads `timeout` from the arguments of each individual `send()`/`get()`/... call. Pass it every time you need an abort:
+> `networkOptions` is `RequestInit`, which has no `timeout` field. Passing one there has no effect on request cancellation. `NodeFetcher.send()` only reads `timeout` from the arguments of each individual `send()`/`get()`/... call. Pass it every time you need an abort:
 >
 > ```typescript
 > await this.getNetworkService().send({ url: '/slow-endpoint', method: 'get', timeout: 5000 });
@@ -437,15 +459,15 @@ If `headers` is a `Headers` instance, it is converted to a plain object via `Obj
 
 ---
 
-### Request Logging & Redaction
+### Request Logging and Redaction
 
-Neither fetcher logs anything by default - `send()` and every shortcut accept an **optional** `logger` as the second argument, and the log call is guarded with `logger?.for(...)`. Pass one (typically `this.logger` from a `BaseHelper` subclass, or `this.logger` on a class extending `BaseNetworkRequest`) to get an `info`-level line per request:
+Neither fetcher logs anything by default. `send()` and every shortcut accept an **optional** `logger` as the second argument, guarded internally with `logger?.for(...)`. Pass a logger to get an `info`-level line per request - typically `this.logger`, whether the caller is a `BaseHelper` subclass or extends `BaseNetworkRequest` directly:
 
 ```typescript
 await this.getNetworkService().post({ url, body }, this.logger);
 ```
 
-Whenever a logger is passed, the assembled request config - `url`, `method`, `headers`, `body`/`data`, and any other options - is run through `redactSecrets()` **before** the log line is written. Redaction matches by key name, case-insensitively, at any depth, against `SECRET_KEY_PATTERN`:
+Whenever a logger is passed, IGNIS runs the assembled request config through `redactSecrets()` before the log line is written. That covers `url`, `method`, `headers`, `body`/`data`, and any other option. Redaction matches by key name, case-insensitively, at any depth, against `SECRET_KEY_PATTERN`:
 
 | Key group | Matched spellings |
 |-----------|--------------------|
@@ -455,7 +477,7 @@ Whenever a logger is passed, the assembled request config - `url`, `method`, `he
 
 Source: [`redact.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/common/redact.ts) `SECRET_KEY_PATTERN`.
 
-A matched value is replaced with `'[REDACTED]'`; `Buffer`/typed-array values under a non-matching key are summarized as `'[Binary N bytes]'` rather than serialized. There is nothing to configure beyond passing the logger - you never call `redactSecrets()` yourself at the call site.
+A matched value is replaced with `'[REDACTED]'`. `Buffer`/typed-array values under a non-matching key are summarized as `'[Binary N bytes]'` rather than serialized. There is nothing to configure beyond passing the logger - you never call `redactSecrets()` yourself at the call site.
 
 ---
 
@@ -479,7 +501,7 @@ Abstract TCP server with client tracking, authentication flow, and event delegat
 constructor(opts: ITcpSocketServerOptions<SocketServerOptions, SocketServerType, SocketClientType>)
 ```
 
-**Throws:** `ApplicationError` with message `'TCP Server | Invalid authenticate duration | Required duration for authenticateOptions'` when `authenticateOptions.required` is `true` and `duration` is missing, `0`, or negative.
+**Throws:** `ApplicationError` when `authenticateOptions.required` is `true` and `duration` is missing, `0`, or negative. Message: `'TCP Server | Invalid authenticate duration | Required duration for authenticateOptions'`.
 
 The constructor calls `configure()`, which creates the server via `createServerFn` and starts listening.
 
@@ -495,7 +517,7 @@ The constructor calls `configure()`, which creates the server via `createServerF
 | `extraEvents` | `Record<string, (opts) => ValueOrPromise<void>>` | Additional per-client socket events to register |
 
 - **Hooks never crash the process.** `onClientData`, `onClientConnected`, `onClientClose`, `onClientError`, `onServerReady`, `onServerError`, and each `extraEvents` entry all run through an internal `invokeHook()` wrapper.
-- **Why it exists.** A hook throwing synchronously inside a raw `net`/`tls` event listener would otherwise be an uncaught exception that crashes the process; `invokeHook()` catches it and logs instead.
+- **Why it exists.** A hook throwing synchronously inside a raw `net`/`tls` event listener would otherwise be an uncaught exception. That crashes the process. `invokeHook()` catches the throw and logs it instead.
 
 #### Methods
 
@@ -531,7 +553,7 @@ getServer(): SocketServerType
 
 ##### `doAuthenticate(opts)`
 
-Transitions a client's authentication state. Sets `storage.authenticatedAt` when the state becomes `'authenticated'` and clears the pending kick-timer; clears `authenticatedAt` for the other two states.
+Transitions a client's authentication state.
 
 ```typescript
 doAuthenticate(opts: {
@@ -540,6 +562,11 @@ doAuthenticate(opts: {
 }): void
 ```
 
+| New state | Effect |
+|---|---|
+| `'authenticated'` | Sets `storage.authenticatedAt`; clears the pending kick-timer |
+| `'unauthorized'` / `'authenticating'` | Clears `storage.authenticatedAt` |
+
 ##### `emit(opts)`
 
 Writes data to a specific client's socket. Never throws - each failure case logs and returns instead:
@@ -569,7 +596,7 @@ async shutdown(): Promise<void>
 3. Empties the `clients` registry.
 4. Calls `server.close()` and awaits its callback.
 
-- **Why this order.** `server.close()` alone never resolves while a socket is still attached, so a caller reaching through `getServer().close()` on a busy server hangs forever.
+- **Why this order.** `server.close()` alone never resolves while a socket is still attached. A caller reaching through `getServer().close()` on a busy server would hang forever.
 - **Idempotent.** A second call is a no-op that resolves cleanly.
 - **Safe on a server that never finished `listen()`.** Logs the resulting `ERR_SERVER_NOT_RUNNING` rather than throwing.
 - **After `shutdown()`**, new connection attempts are refused.
@@ -668,7 +695,7 @@ Abstract TCP client with auto-reconnect, encoding support, and lifecycle hooks.
 constructor(opts: INetworkTcpClientProps<SocketClientOptions, SocketClientType>)
 ```
 
-Does **not** call `connect()` automatically - construction only stores options; call `connect({ resetReconnectCounter })` explicitly.
+Does **not** call `connect()` automatically. Construction only stores options - call `connect({ resetReconnectCounter })` explicitly.
 
 #### Protected Properties
 
@@ -686,7 +713,7 @@ Does **not** call `connect()` automatically - construction only stores options;
 protected getLoggableOptions(): unknown
 ```
 
-Returns `redactSecrets(this.options)`. A TLS client's `options` **is** its private key material (`key`/`cert`/`passphrase`), so every internal log call uses this instead of logging `this.options` directly - otherwise the key would be written to every log file and aggregator downstream.
+Returns `redactSecrets(this.options)`. A TLS client's `options` **is** its private key material - `key`/`cert`/`passphrase`. Every internal log call uses this method instead of logging `this.options` directly, or the key would be written to every log file and aggregator downstream.
 
 #### Methods
 
@@ -695,7 +722,11 @@ Returns `redactSecrets(this.options)`. A TLS client's `options` **is** its priva
 Establishes the connection:
 
 - No-op with a log line if already connected (`isConnected()`) or if `options` is empty.
-- Otherwise, destroys any stale `client` first, creates the socket via `createClientFn`, registers `data`/`close`/`error` listeners, and applies `encoding` if set.
+- Otherwise, in order:
+  1. Destroys any stale `client` first.
+  2. Creates the socket via `createClientFn`.
+  3. Registers `data`/`close`/`error` listeners.
+  4. Applies `encoding`, if set.
 
 ```typescript
 connect(opts: { resetReconnectCounter: boolean }): void
@@ -764,11 +795,11 @@ handleError(error: any): void                                             // Log
 | `reconnect` is `true` and `currentReconnect < maxReconnect` (with `maxReconnect >= 0`) | Reconnect scheduled |
 
 > [!IMPORTANT]
-> - **`maxReconnect: -1` does not mean unlimited reconnects - it disables reconnection entirely.** This is the opposite of the common "`-1` = unlimited" convention elsewhere in the framework (e.g. Redis retry).
-> - **A second guard further down the method is dead code.** `if (maxReconnect > -1 && currentReconnect >= maxReconnect)` can never be true: by the time control reaches it, the first guard has already ruled out `currentReconnect >= maxReconnect`.
+> - **`maxReconnect: -1` does not mean unlimited reconnects - it disables reconnection entirely.** That is the opposite of the "`-1` = unlimited" convention used elsewhere in the framework - the Redis retry helper, for example.
+> - **A second guard further down the method is dead code.** `if (maxReconnect > -1 && currentReconnect >= maxReconnect)` can never be true. By the time control reaches it, the first guard has already ruled out `currentReconnect >= maxReconnect`.
 > - Source: [`base-tcp-client.helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/network/tcp-socket/base-tcp-client.helper.ts).
 
-The reconnect delay is a **fixed 5000 ms** - there is no backoff growth on the TCP/TLS client, unlike the Redis helper's exponential strategy.
+The reconnect delay is a **fixed 5000 ms**. There is no backoff growth on the TCP/TLS client, unlike the Redis helper's exponential strategy.
 
 ---
 
@@ -862,15 +893,19 @@ static newInstance(opts: INetworkUdpClientProps): NetworkUdpClient
 
 ##### `connect()`
 
-- Creates a `dgram.Socket` (`type: 'udp4'`, `reuseAddr` from options), registers `close`/`error`/`listening`/`message` listeners, then binds to `port`/`host`.
-- Each listener routes through an internal `invokeHook()` wrapper (same synchronous-throw guard as the TCP server).
-- `onBind` fires after binding completes - the place to join multicast groups via `socket.addMembership(group, iface)`.
+Creates a `dgram.Socket` and binds it, in order:
+
+1. Creates the socket (`type: 'udp4'`, `reuseAddr` from options).
+2. Registers `close`/`error`/`listening`/`message` listeners.
+3. Binds to `port`/`host`.
+
+Each listener routes through an internal `invokeHook()` wrapper - the same synchronous-throw guard as the TCP server. `onBind` fires after binding completes; it's the place to join multicast groups via `socket.addMembership(group, iface)`.
 
 ```typescript
 connect(): void
 ```
 
-No-op with a log line if `client` is already set, or if `port` is not a non-negative integer (`Number.isInteger(port) && port >= 0`) - port `0` is a valid "OS assigns a free port" request and is accepted.
+No-op with a log line in two cases: `client` is already set, or `port` fails `Number.isInteger(port) && port >= 0`. Port `0` itself is valid - it means "let the OS assign a free port" - and is accepted.
 
 ##### `disconnect()`
 
@@ -970,7 +1005,7 @@ interface ITcpSocketServerOptions<
 }
 ```
 
-`onServerError` fires when the underlying `net`/`tls` server emits `'error'` (for example `EADDRINUSE` from a port already in use) - without this listener the event is unhandled and takes the whole process down; with it, the error is routed here and the process keeps running.
+`onServerError` fires when the underlying `net`/`tls` server emits `'error'` - for example `EADDRINUSE` from a port already in use. Without this listener, the event is unhandled and takes the whole process down with it.
 
 ### INetworkTcpClientProps
 

package/content/extensions/helpers/network/index.md

@@ -6,7 +6,7 @@ difficulty: intermediate
 
 # Network
 
-Network helpers give you HTTP request clients (fetch or Axios), symmetric TCP/TLS socket client-server pairs, and a UDP client, all sharing the same options-object construction and scoped logging as the rest of the framework.
+Network helpers give you HTTP request clients (fetch or Axios), symmetric TCP/TLS socket client-server pairs, and a UDP client. All three share the same options-object construction and scoped logging as the rest of the framework.
 
 ## In one example
 
@@ -31,16 +31,30 @@ class GitHubApi extends NodeFetchNetworkRequest {
 }
 ```
 
-`getRequestUrl()` joins the constructor's `baseUrl` with the path segments; `getNetworkService()` returns the underlying fetcher, which exposes `send()` plus `get`/`post`/`put`/`patch`/`delete`/`query` shortcuts.
+`getRequestUrl()` joins the constructor's `baseUrl` with the path segments. `getNetworkService()` returns the underlying fetcher, which exposes `send()` plus `get`/`post`/`put`/`patch`/`delete`/`query` shortcuts.
 
 ## How it works
 
-- **HTTP is two layers.** `BaseNetworkRequest` holds a base URL and delegates every call to an `IFetchable` fetcher. `NodeFetchNetworkRequest` (root barrel, wraps native `fetch`) and `AxiosNetworkRequest` (`@venizia/ignis-helpers/axios` sub-path, wraps Axios) are the two concrete clients - you typically extend one to build a typed API client, as in the example above.
-- **`axios` is optional.** It's an optional peer dependency, so `AxiosNetworkRequest`'s fetcher is never exported from the root barrel - only from the `/axios` sub-path.
-- **TCP and TLS share one hierarchy.** `BaseNetworkTcpServer`/`BaseNetworkTcpClient` are abstract classes that take a `createServerFn`/`createClientFn` (`net.*` for plain TCP, `tls.*` for TLS). `NetworkTcpServer`/`NetworkTcpClient` and `NetworkTlsTcpServer`/`NetworkTlsTcpClient` pre-wire those functions - constructor options and every method are otherwise identical between the plain and encrypted variants.
+- **HTTP is two layers.** `BaseNetworkRequest` holds the base URL and delegates every call to an `IFetchable` fetcher. You extend one of two concrete clients:
+
+  | Client | Wraps | Import from |
+  |---|---|---|
+  | `NodeFetchNetworkRequest` | native `fetch` | root barrel |
+  | `AxiosNetworkRequest` | Axios | `@venizia/ignis-helpers/axios` sub-path |
+
+- **`axios` is optional.** It is an optional peer dependency. `AxiosNetworkRequest` is exported only from the `/axios` sub-path, never from the root barrel.
+- **TCP and TLS share one hierarchy.** `BaseNetworkTcpServer`/`BaseNetworkTcpClient` are abstract classes. Each takes a create-function matching its transport, and each concrete pair only pre-wires that function:
+
+  | Transport | Server class | Client class | Node module |
+  |---|---|---|---|
+  | Plain TCP | `NetworkTcpServer` | `NetworkTcpClient` | `net` |
+  | TLS | `NetworkTlsTcpServer` | `NetworkTlsTcpClient` | `tls` |
+
+  Constructor options and every method are otherwise identical between the plain and encrypted variants.
+
 - **Servers track per-client authentication state.** `unauthorized` → `authenticating` → `authenticated`.
 - **Clients auto-reconnect on a fixed delay.** 5 seconds between attempts, up to `maxRetry` attempts, when `reconnect: true`. See the [Full reference](/extensions/helpers/network/api) for the `maxRetry: -1` edge case.
-- **UDP has no client/server split.** `NetworkUdpClient` is a single class wrapping `node:dgram` (UDP4), with optional multicast group joining via `onBind`.
+- **UDP has no client/server split.** `NetworkUdpClient` is a single class wrapping `node:dgram` in UDP4 mode. It supports optional multicast group joining via `onBind`.
 - **Every class extends `BaseHelper`.** `this.logger.for('methodName')` scoped logging is available throughout.
 
 **HTTP method case**
@@ -48,7 +62,7 @@ class GitHubApi extends NodeFetchNetworkRequest {
 | Layer | Case | Why |
 |-------|------|-----|
 | `HTTP.Methods.GET`/`.POST`/`.QUERY`/... tokens | always lowercase | Required by `@hono/zod-openapi` route definitions |
-| Wire dispatch | uppercased right before send | Node's undici only auto-normalizes `DELETE`/`GET`/`HEAD`/`OPTIONS`/`POST`/`PUT` - a lowercase `patch` or `query` would go out unchanged |
+| Wire dispatch | uppercased right before send | Node's undici only auto-normalizes `DELETE`/`GET`/`HEAD`/`OPTIONS`/`POST`/`PUT`. A lowercase `patch` or `query` would go out unchanged |
 
 ## Common tasks
 
@@ -73,11 +87,18 @@ class PaymentGateway extends AxiosNetworkRequest {
 }
 ```
 
-`AxiosNetworkRequest` applies defaults you can override: `Content-Type: application/json`, `withCredentials: true`, `validateStatus: status < 500`, `timeout: 60000`.
+`AxiosNetworkRequest` applies these defaults - override any of them in `networkOptions`:
+
+| Setting | Default |
+|---|---|
+| `content-type` header | `application/json; charset=utf-8` |
+| `withCredentials` | `true` |
+| `validateStatus` | `status < 500` |
+| `timeout` | `60000` ms |
 
 ### Log a request with secrets redacted
 
-Pass a logger (typically `this.logger` from a `BaseHelper` subclass) as the second argument to `send()` or any shortcut method - the fetcher logs the URL and config at `info` level with the config run through `redactSecrets()` first, so values like `Authorization` or `X-API-Key` reach the log as `'[REDACTED]'`. Without a logger argument, nothing is logged.
+Pass a logger as the second argument to `send()` or any shortcut method - typically `this.logger` from a `BaseHelper` subclass. The fetcher then logs the URL and config at `info` level. It runs the config through `redactSecrets()` first, so values like `Authorization` or `X-API-Key` reach the log as `'[REDACTED]'`. Without a logger argument, nothing is logged.
 
 ```typescript
 async charge(amount: number, currency: string) {
@@ -115,11 +136,11 @@ client.connect({ resetReconnectCounter: true });
 client.emit({ payload: 'Hello, Server!' });
 ```
 
-`NetworkTlsTcpServer`/`NetworkTlsTcpClient` use the identical API - pass certificates in `serverOptions`/`options` (types `TlsOptions`/`ConnectionOptions` from `node:tls`).
+`NetworkTlsTcpServer`/`NetworkTlsTcpClient` use the identical API. Pass certificates in `serverOptions`/`options`, typed `TlsOptions`/`ConnectionOptions` from `node:tls`.
 
 ### Require TCP client authentication
 
-Set `authenticateOptions.required: true` with a positive `duration` (milliseconds); the constructor throws if `duration` is missing or negative. Clients that never call `doAuthenticate()` within that window are disconnected automatically.
+Set `authenticateOptions.required: true` with a positive `duration` in milliseconds. The constructor throws if `duration` is missing or negative. Clients that never call `doAuthenticate()` within that window are disconnected automatically.
 
 ```typescript
 const server = new NetworkTcpServer({

package/content/extensions/helpers/queue/index.md

@@ -6,7 +6,7 @@ difficulty: intermediate
 
 # Queue
 
-The Queue helpers give you background job processing with BullMQ, a dependency-free in-memory queue for single-process sequencing, and MQTT pub/sub for lightweight event fan-out.
+The Queue helpers move work between processes. Pick a backend: BullMQ for durable jobs, an in-memory queue for single-process sequencing, or MQTT for lightweight pub/sub.
 
 ## In one example
 
@@ -51,9 +51,20 @@ const worker = BullMQHelper.newInstance({
 | In-memory | `SequentialQueueHelper` (alias `QueueHelper`) | none | Sequential, single-process work that does not need persistence |
 | MQTT | `MQTTClientHelper` | `mqtt` | Pub/sub for IoT and lightweight real-time events, not job processing |
 
-- **`BullMQHelper` takes one `role` per instance, fixed at construction.** `'queue'` exposes a `.queue` property (BullMQ `Queue`) for producers calling `.add()`; `'worker'` exposes a `.worker` property (BullMQ `Worker`) driven by your `onWorkerData` callback.
-- **One Redis helper backs any number of queues and workers.** The helper always calls `redisConnection.duplicateClient()` to open a dedicated connection for whichever role it owns - it never reuses the caller's client directly.
-- **`SequentialQueueHelper` runs one element at a time.** A `WAITING -> PROCESSING -> WAITING` loop driven by `onMessage`. `lock()` diverts the loop to `LOCKED` (elements still enqueue, nothing processes until `unlock()`); `settle()`/`close()` moves it to the terminal `SETTLED` state once the queue drains.
+- **`BullMQHelper` takes one `role` per instance, fixed at construction.**
+
+| `role` | Property | Use |
+|---|---|---|
+| `'queue'` | `.queue` (BullMQ `Queue`) | Producers call `.add()` |
+| `'worker'` | `.worker` (BullMQ `Worker`) | Driven by your `onWorkerData` callback |
+
+- **One Redis helper backs any number of queues and workers.** The helper always calls `redisConnection.duplicateClient()` to open a dedicated connection for whichever role it owns. It never reuses your client directly.
+- **`SequentialQueueHelper` runs one element at a time**, in a `WAITING -> PROCESSING -> WAITING` loop driven by `onMessage`. Two calls change that loop:
+
+| Call | Effect |
+|---|---|
+| `lock()` | Pauses processing at `LOCKED`. Elements still enqueue; nothing processes until `unlock()`. |
+| `settle()` / `close()` | Drains the queue, then moves to the terminal `SETTLED` state. |
 
 Full option tables, the complete state machine, and `HfQueueHelper` (the low-level FIFO primitive underneath) are in the [Full reference](/extensions/helpers/queue/reference).
 
@@ -69,7 +80,7 @@ Jobs default to `removeOnComplete: true, removeOnFail: true` - BullMQ does not r
 
 ### Process jobs with a worker
 
-`numberOfWorker` sets concurrency; `onWorkerDataFail` receives the job (possibly `undefined`) and the error.
+`numberOfWorker` sets concurrency. `onWorkerDataFail` receives the job (possibly `undefined`) and the error.
 
 ```typescript
 const worker = BullMQHelper.newInstance({
@@ -90,7 +101,7 @@ const worker = BullMQHelper.newInstance({
 
 ### The Redis connection requirement
 
-Pass an `IRedisHelper` instance, not a raw ioredis client - `BullMQHelper` calls `redisConnection.duplicateClient()` internally.
+Pass an `IRedisHelper` instance, not a raw ioredis client. `BullMQHelper` calls `redisConnection.duplicateClient()` internally.
 
 | Redis helper | Sets `maxRetriesPerRequest: null`? |
 |--------------|-------------------------------------|

package/content/extensions/helpers/queue/reference.md

@@ -17,6 +17,21 @@ Exhaustive reference for the Queue helper family. For a readable introduction an
 - [`packages/helpers/src/modules/queue/mqtt/helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/queue/mqtt/helper.ts) - `MQTTClientHelper`
 - [`packages/helpers/src/modules/queue/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/queue/common/types.ts) - `TBullQueueRole`
 
+## Find what you need
+
+| You want to | Go to |
+|---|---|
+| Pick a backend and see import paths | [Class Overview](#class-overview) / [Import Paths](#import-paths) |
+| Construct a producer or worker and see every option | [BullMQHelper](#bullmqhelper) |
+| Understand what a bad `role` or empty `queueName` does | [Configuration lifecycle](#configuration-lifecycle) |
+| Run BullMQ against Redis Cluster | [Redis Cluster setup](#redis-cluster-setup) |
+| Construct an in-memory sequential queue and see every option | [SequentialQueueHelper](#sequentialqueuehelper) |
+| Understand the `WAITING`/`PROCESSING`/`LOCKED`/`SETTLED` state machine | [QueueStatuses and the state machine](#queuestatuses-and-the-state-machine) |
+| Reach for a bare O(1) FIFO instead of a job queue | [HfQueueHelper](#hfqueuehelper) |
+| Construct an MQTT client and see every option | [MQTTClientHelper](#mqttclienthelper) |
+| Fix a thrown or logged error message | [Troubleshooting](#troubleshooting) |
+| Copy the full import list | [Import Reference](#import-reference) |
+
 ## Class Overview
 
 | Class | Extends | Peer dependency | Use case |
@@ -26,11 +41,11 @@ Exhaustive reference for the Queue helper family. For a readable introduction an
 | `HfQueueHelper` | `BaseHelper` | none | Generic O(1) FIFO primitive - single-threaded, no callbacks, no persistence |
 | `MQTTClientHelper` | `BaseHelper` | `mqtt` | MQTT broker pub/sub - IoT and lightweight real-time events |
 
-Kafka (`KafkaProducerHelper`, `KafkaConsumerHelper`, `KafkaAdminHelper`, `KafkaSchemaRegistryHelper`) is a fourth backend under the same `queue/` module tree but is documented on its own page - see [Kafka Helpers](/extensions/helpers/kafka/).
+Kafka (`KafkaProducerHelper`, `KafkaConsumerHelper`, `KafkaAdminHelper`, `KafkaSchemaRegistryHelper`) is a fourth backend under the same `queue/` module tree. It's documented on its own page - see [Kafka Helpers](/extensions/helpers/kafka/).
 
 ## Import Paths
 
-`BullMQHelper` and `MQTTClientHelper` live behind sub-path exports so their peer dependencies (`bullmq`, `mqtt`) never become hard dependencies of the base package. `SequentialQueueHelper`, `QueueHelper`, `QueueStatuses`, `HfQueueHelper`, and `TBullQueueRole` ship from the root package.
+`BullMQHelper` and `MQTTClientHelper` live behind sub-path exports. That keeps their peer dependencies (`bullmq`, `mqtt`) from becoming hard dependencies of the base package. `SequentialQueueHelper`, `QueueHelper`, `QueueStatuses`, `HfQueueHelper`, and `TBullQueueRole` ship from the root package instead.
 
 ```typescript
 // Root package - no peer dependency
@@ -93,7 +108,7 @@ const worker = new BullMQHelper({
 | `onWorkerDataFail` | `(job \| undefined, error: Error) => Promise<void>` | - | Fired on the BullMQ `Worker` `'failed'` event. `job` may be `undefined`. |
 
 > [!IMPORTANT]
-> Pass an `IRedisHelper` instance to `redisConnection`, **not** the raw ioredis client. `BullMQHelper` calls `redisConnection.duplicateClient()` internally to get a dedicated connection per role - one shared Redis helper can back any number of queues and workers.
+> Pass an `IRedisHelper` instance to `redisConnection`, **not** the raw ioredis client. `BullMQHelper` calls `redisConnection.duplicateClient()` internally to get a dedicated connection per role. One shared Redis helper can back any number of queues and workers.
 
 ### Configuration lifecycle
 
@@ -103,14 +118,18 @@ The constructor calls `configure()`, which switches on `role`:
 |--------|---------------|--------|
 | `'queue'` | `configureQueue()` | Builds `this.queue` (BullMQ `Queue`); attaches an `'error'` listener |
 | `'worker'` | `configureWorker()` | Builds `this.worker` (BullMQ `Worker`); attaches `'completed'`, `'failed'`, `'error'` listeners |
-| missing / other | neither | Logs `'Invalid client role to configure'` and returns - **does not throw** |
+| missing (falsy) | neither | Logs `'Invalid client role to configure'` and returns - **does not throw** |
+| any other value | neither | **Silent.** No log, no throw. `this.queue` and `this.worker` both stay `undefined` |
+
+> [!WARNING]
+> A typo'd `role` (for example `'Worker'` instead of `'worker'`) hits the "any other value" row above - not the "missing" row. Nothing gets logged. The helper looks constructed, but `.queue` and `.worker` are both `undefined` until you call one and hit a `TypeError`.
 
-`configureQueue()` and `configureWorker()` each guard on `queueName`: if it is falsy, the method logs `'Invalid queue name'` / `'Invalid worker name'` and returns without constructing anything - `this.queue` / `this.worker` stay `undefined`. Neither path throws; a misconfigured helper fails later, when you call `.queue.add(...)` or `.worker` on the `undefined` property.
+`configureQueue()` and `configureWorker()` each guard on `queueName`. An empty `queueName` logs `'Invalid queue name'` (or `'Invalid worker name'`) and returns - `this.queue` / `this.worker` stay `undefined`. Neither path throws. A misconfigured helper fails later instead, the first time you call `.queue.add(...)` or use `.worker`.
 
 > [!NOTE]
-> An `'error'` event with no listener is re-thrown by Node's `EventEmitter` and crashes the process. `BullMQHelper` always attaches an `'error'` listener to both `queue` and `worker` so a transient Redis error is logged instead of taking the process down.
+> An `'error'` event with no listener is re-thrown by Node's `EventEmitter` and crashes the process. `BullMQHelper` always attaches an `'error'` listener to both `queue` and `worker`. A transient Redis error gets logged instead of taking the process down.
 
-`onWorkerDataCompleted` and `onWorkerDataFail` run through an internal hook wrapper that absorbs both synchronous throws and rejected promises, logging them instead of propagating - a broken callback cannot crash the worker or block the next job.
+`onWorkerDataCompleted` and `onWorkerDataFail` run through an internal hook wrapper. It absorbs both synchronous throws and rejected promises, logging them instead of propagating. A broken callback can't crash the worker or block the next job.
 
 ### Cluster queue name wrapping
 
@@ -175,7 +194,7 @@ await producer.close();
 await consumer.close();
 ```
 
-Calls `worker?.close()` then `queue?.close()` in sequence - both run even if the first fails, so a failing worker close never leaks the queue's Redis connection. If either fails, `close()` throws a single `ApplicationError` aggregating both failure messages after both close attempts have run.
+Calls `worker?.close()` then `queue?.close()` in sequence. Both run even if the first fails, so a failing worker close never leaks the queue's Redis connection. If either fails, `close()` throws one `ApplicationError` aggregating both failure messages - only after both close attempts have run.
 
 ### API summary
 
@@ -233,7 +252,7 @@ const queue = new SequentialQueueHelper<string>({
 | `onDataDequeue` | `(opts: { identifier: string; queueElement: TQueueElement<T> }) => ValueOrPromise<void>` | - | Fired after an element is shifted off `storage`. |
 | `onStateChange` | `(opts: { identifier: string; from: TQueueStatus; to: TQueueStatus }) => ValueOrPromise<void>` | - | Fired on every state transition. |
 
-All four hooks run through an internal wrapper that absorbs synchronous throws and promise rejections, logging them instead - a broken callback cannot break the state machine.
+All four hooks run through an internal wrapper that absorbs synchronous throws and promise rejections, logging them instead. A broken callback can't break the state machine.
 
 ### TQueueElement
 
@@ -241,7 +260,7 @@ All four hooks run through an internal wrapper that absorbs synchronous throws a
 type TQueueElement<T> = { isLocked: boolean; payload: T };
 ```
 
-`isLocked` marks whether the head element is currently being handed to `onMessage`; it is distinct from the queue-level `lock()`/`unlock()` state below.
+`isLocked` marks whether the head element is currently being handed to `onMessage`. It is distinct from the queue-level `lock()`/`unlock()` state below.
 
 ### QueueStatuses and the state machine
 
@@ -262,21 +281,27 @@ WAITING ──enqueue──> PROCESSING ──done──> WAITING
 | `QueueStatuses.LOCKED` | `'200_LOCKED'` | Paused. Elements can still be enqueued; nothing processes until `unlock()`. |
 | `QueueStatuses.SETTLED` | `'300_SETTLED'` | Terminal. No further elements accepted. |
 
-- **Why numeric prefixes.** `'000_...'` .. `'300_...'` make `state >= QueueStatuses.LOCKED` and `state > QueueStatuses.LOCKED` valid string comparisons - `lock()` and `unlock()` use exactly that to guard against re-entering from an invalid state.
+- **Why numeric prefixes.** `'000_...'` through `'300_...'` make `state >= QueueStatuses.LOCKED` and `state > QueueStatuses.LOCKED` valid string comparisons. `lock()` and `unlock()` use exactly that to guard against re-entering from an invalid state.
 - **Validate an arbitrary string** with `QueueStatuses.isValid(value)`.
 
 ### Processing loop
 
-Internally, `_messageListener()` is a generator that loops `while (true) { yield this.handleMessage(); }`. `nextMessage()` calls `generator.next()` only when `state === WAITING`; any other state logs a warning and returns without advancing. `handleMessage()`:
+Internally, `_messageListener()` is a generator that loops `while (true) { yield this.handleMessage(); }`. `nextMessage()` calls `generator.next()` only when `state === WAITING`. Any other state logs a warning and returns without advancing. `handleMessage()`:
 
-1. Reads the head element (`getElementAt(0)`); returns early if empty or already `isLocked`.
+1. Reads the head element (`getElementAt(0)`). Returns early if it's empty or already `isLocked`.
 2. Transitions `WAITING -> PROCESSING` (skipped if already `LOCKED`/`SETTLED`).
 3. Marks the head `isLocked = true`, adds it to `processingEvents`, and awaits `onMessage`.
 4. Dequeues the completed element and removes it from `processingEvents`.
 5. Transitions back to `WAITING` (skipped if `LOCKED`/`SETTLED`).
-6. If `storage` is now empty and `settle()` was requested, transitions to `SETTLED`; otherwise calls `nextMessage()` again to continue the loop.
+6. Checks `storage`:
 
-A failing `onMessage` handler is logged and swallowed by the same hook wrapper described above - the element is still dequeued and the loop continues. `onMessage` owns its own retry policy; the queue itself never retries.
+| `storage` after step 5 | What happens |
+|---|---|
+| Empty, and `settle()` was requested | Transitions to `SETTLED` and stops |
+| Empty, and no `settle()` requested | Stops here. The queue idles until the next `enqueue()` |
+| Not empty | Calls `nextMessage()` to continue the loop immediately |
+
+A failing `onMessage` handler is logged and swallowed by the same hook wrapper described above. The element is still dequeued, and the loop continues. `onMessage` owns its own retry policy - the queue itself never retries.
 
 ### Methods
 
@@ -302,7 +327,7 @@ A failing `onMessage` handler is logged and swallowed by the same hook wrapper d
 
 `Source ->` [`packages/helpers/src/modules/queue/internal/hf/helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/queue/internal/hf/helper.ts)
 
-- **O(1) FIFO, not a job queue.** A generic, high-frequency, single-consumer primitive for enqueue, dequeue, and cancel - backed by an array plus a moving head index (no `Array.shift()`, which is O(n)).
+- **O(1) FIFO, not a job queue.** A generic, high-frequency, single-consumer primitive for enqueue, dequeue, and cancel. It's backed by an array plus a moving head index - never `Array.shift()`, which is O(n).
 - **No callbacks, no state machine, not thread-safe.** It is the low-level queue the pool helper's waiter list is built on, not a job-processing API.
 - **Reach for `SequentialQueueHelper` instead** unless you specifically need a bare FIFO with cancellable entries.
 
@@ -327,7 +352,7 @@ const remaining = queue.drain(); // remove + return every live value, emptying t
 | `cancel(opts)` | `void` | `opts: { node: IHfQueueNode<T> }`. Marks a queued node cancelled; idempotent. |
 | `drain()` | `T[]` | Removes and returns every remaining live value in FIFO order, emptying the queue. |
 
-Consumed entries are compacted out of the backing array once the consumed prefix exceeds 256 entries and covers at least half the array, keeping every operation amortized O(1).
+Consumed entries are compacted out of the backing array once the consumed prefix exceeds 256 entries and covers at least half the array. This keeps every operation amortized O(1).
 
 ## MQTTClientHelper
 
@@ -356,7 +381,7 @@ const client = new MQTTClientHelper({
 });
 ```
 
-The constructor calls `configure()` automatically, which connects via `mqtt.connect(url, options)`. Calling `configure()` again on an already-connected client is a no-op (logs and returns).
+The constructor calls `configure()` automatically, which connects via `mqtt.connect(url, options)`. Calling `configure()` again is a no-op (logs and returns) whenever `this.client` already exists - even if that client later disconnected without you calling `close()`.
 
 ### IMQTTClientOptions
 
@@ -372,13 +397,13 @@ The constructor calls `configure()` automatically, which connects via `mqtt.conn
 | `onClose` | `(error?: Error) => void` | - | Fired on the `'close'` event. |
 
 > [!NOTE]
-> At connect time, `MQTTClientHelper` logs the broker `url` through `redactUrlCredentials()` and `options` through `redactSecrets()`. A password embedded in the URL (`mqtts://user:hunter2@broker:8883`) never reaches the log - only `mqtts://user:[REDACTED]@broker:8883` does.
+> At connect time, `MQTTClientHelper` logs the broker `url` through `redactUrlCredentials()` and `options` through `redactSecrets()`. A password embedded in the URL (`mqtts://user:hunter2@broker:8883`) never reaches the log. Only `mqtts://user:[REDACTED]@broker:8883` does.
 
 ### Methods
 
 | Method | Returns | Description |
 |--------|---------|--------------|
-| `configure()` | `void` | Connects to the broker and wires `connect`/`disconnect`/`message`/`error`/`close` listeners. Called automatically by the constructor; a no-op if already connected. |
+| `configure()` | `void` | Connects to the broker and wires `connect`/`disconnect`/`message`/`error`/`close` listeners. Called automatically by the constructor. A no-op if `this.client` already exists. |
 | `getClient()` | `mqtt.MqttClient \| undefined` | The underlying MQTT.js client. |
 | `subscribe(opts)` | `Promise<string[]>` | `opts: { topics: string[] }`. Rejects with an `ApplicationError` (status 400) if the client is not connected. |
 | `publish(opts)` | `Promise<{ topic, message }>` | `opts: { topic: string; message: string \| Buffer }`. Rejects with an `ApplicationError` (status 400) if the client is not connected. |
@@ -388,7 +413,7 @@ The constructor calls `configure()` automatically, which connects via `mqtt.conn
 
 ### "Invalid queue name" / "Invalid worker name"
 
-**Cause:** `queueName` is empty when `BullMQHelper` configures a queue or worker. This is a **logged error, not a thrown exception** - `this.queue` / `this.worker` are simply never assigned.
+**Cause:** `queueName` is empty when `BullMQHelper` configures a queue or worker. This is a **logged error, not a thrown exception** - `this.queue` / `this.worker` are never assigned.
 
 **Fix:** Provide a non-empty `queueName`:
 
@@ -402,7 +427,9 @@ new BullMQHelper({ queueName: 'my-email-queue', role: 'queue', identifier: 'x',
 
 ### "Invalid client role to configure"
 
-**Cause:** `role` is missing or not one of `'queue'` / `'worker'`. Logged, not thrown.
+**Cause:** `role` is missing or empty (falsy). Logged, not thrown.
+
+**Also watch for:** a `role` that IS a non-empty string but not `'queue'`/`'worker'` (a typo like `'Worker'`) triggers **no log at all**. `configure()` silently does nothing, and `this.queue`/`this.worker` both stay `undefined` - see [Configuration lifecycle](#configuration-lifecycle).
 
 **Fix:**
 
@@ -430,9 +457,9 @@ new MQTTClientHelper({ url: 'mqtt://localhost:1883', identifier: 'x', options: {
 
 **Checklist:**
 - `onMessage` must be provided - without it, the generator never initializes and nothing is ever processed.
-- Check `getState()` - a `LOCKED` queue accepts `enqueue()` but never processes; call `unlock({ shouldProcessNextElement: true })`.
-- Check `autoDispatch` - if `false`, call `nextMessage()` manually after each `enqueue()`.
-- Check `isSettled()` - a settled queue rejects new elements; construct a new instance.
+- Check `getState()`. A `LOCKED` queue accepts `enqueue()` but never processes. Call `unlock({ shouldProcessNextElement: true })` to resume.
+- Check `autoDispatch`. If it's `false`, call `nextMessage()` manually after each `enqueue()`.
+- Check `isSettled()`. A settled queue rejects new elements - construct a new instance instead.
 
 ## Import Reference