@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/extensions/helpers/socket-io/index.md

@@ -17,7 +17,7 @@ import {
   SocketIOClientHelper,
   SocketIOConstants,
   SocketIOClientStates,
-} from '@venizia/ignis-helpers';
+} from '@venizia/ignis-helpers/socket-io';
 
 import type {
   TSocketIOServerOptions,
@@ -33,7 +33,7 @@ import type {
   TSocketIOClientConnectedFn,
   TSocketIOEventHandler,
   TSocketIOClientState,
-} from '@venizia/ignis-helpers';
+} from '@venizia/ignis-helpers/socket-io';
 ```
 
 ## Creating an Instance
@@ -43,16 +43,17 @@ import type {
 `SocketIOServerHelper` requires a Redis connection for the pub/sub adapter, an HTTP server (Node.js) or Bun engine instance, and an authentication function.
 
 ```typescript
-import { SocketIOServerHelper } from '@venizia/ignis-helpers';
-import { DefaultRedisHelper } from '@venizia/ignis-helpers';
+import { SocketIOServerHelper } from '@venizia/ignis-helpers/socket-io';
+import { RedisSingleHelper } from '@venizia/ignis-helpers';
 import { createServer } from 'node:http';
 
 const httpServer = createServer();
 
-const redisHelper = new DefaultRedisHelper({
+const redisHelper = new RedisSingleHelper({
   name: 'socket-redis',
   host: 'localhost',
   port: 6379,
+  password: '',
 });
 
 const socketServer = new SocketIOServerHelper({
@@ -91,8 +92,8 @@ A discriminated union based on the `runtime` field:
 | `runtime` | `'node' \| 'bun'` | -- | Runtime environment. Determines which server field is required |
 | `server` | `HTTPServer` | -- | Node.js HTTP server instance. **Required when `runtime` is `'node'`** |
 | `engine` | `any` | -- | `@socket.io/bun-engine` Server instance. **Required when `runtime` is `'bun'`** |
-| `serverOptions` | `Partial<ServerOptions>` | `{}` | Socket.IO `ServerOptions` (cors, path, transports, etc.) |
-| `redisConnection` | `DefaultRedisHelper` | -- | **Required.** Redis helper used to create pub, sub, and emitter clients |
+| `serverOptions` | `Partial<ServerOptions>` | -- | **Required by the type.** Socket.IO `ServerOptions` (cors, path, transports, etc.). Pass `{}` when no options are needed; nullish values fall back to `{}` at runtime |
+| `redisConnection` | `IRedisHelper` | -- | **Required.** Redis helper used to create pub, sub, and emitter clients |
 | `authenticateFn` | `TSocketIOAuthenticateFn` | -- | **Required.** Called with the client's handshake data. Return `true` to accept, `false` to reject |
 | `validateRoomFn` | `TSocketIOValidateRoomFn` | `undefined` | Called when a client requests to join rooms. Return the allowed subset |
 | `clientConnectedFn` | `TSocketIOClientConnectedFn` | `undefined` | Called after a client is fully authenticated and has joined default rooms |
@@ -108,7 +109,7 @@ A discriminated union based on the `runtime` field:
 `SocketIOClientHelper` connects to a Socket.IO server. Configuration is done entirely via the constructor -- `configure()` is called automatically.
 
 ```typescript
-import { SocketIOClientHelper } from '@venizia/ignis-helpers';
+import { SocketIOClientHelper } from '@venizia/ignis-helpers/socket-io';
 
 const socketClient = new SocketIOClientHelper({
   identifier: 'my-client',
@@ -191,7 +192,7 @@ httpServer.listen(3000, () => {
 For Bun, pass the `@socket.io/bun-engine` instance instead of an HTTP server:
 
 ```typescript
-import { SocketIOServerHelper } from '@venizia/ignis-helpers';
+import { SocketIOServerHelper } from '@venizia/ignis-helpers/socket-io';
 
 const socketServer = new SocketIOServerHelper({
   identifier: 'my-bun-server',
@@ -425,6 +426,9 @@ The server uses `@socket.io/redis-adapter` and `@socket.io/redis-emitter` for ho
 
 All three connections are initialized and awaited during `configure()`. If the parent client uses `lazyConnect`, the duplicated clients will connect automatically.
 
+> [!NOTE]
+> `configure()` fails fast: if any of the three Redis clients never reaches the `ready` state, it rejects after **30 seconds** rather than hanging boot indefinitely.
+
 ```typescript
 // Messages sent via send() use the Redis emitter,
 // so they reach clients on ANY server instance
@@ -481,7 +485,7 @@ client.shutdown();
 
 **Cause:** The `redisConnection` option is missing, `null`, or `undefined`.
 
-**Fix:** Pass a valid `DefaultRedisHelper` instance.
+**Fix:** Pass a valid `IRedisHelper` instance (e.g., `RedisSingleHelper` or `RedisClusterHelper`).
 
 ### `[on] Invalid topic to start binding handler`
 

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

@@ -2,7 +2,7 @@
 
 ## Architecture
 
-The storage system uses a class hierarchy with an abstract base class providing shared logic and two concrete implementations for different backends. `MemoryStorageHelper` is a separate, standalone class that does not participate in the `IStorageHelper` hierarchy.
+The storage system uses a class hierarchy with an abstract base class providing shared logic and three concrete implementations for different backends. `MemoryStorageHelper` is a separate, standalone class that does not participate in the `IStorageHelper` hierarchy.
 
 ```
 BaseHelper
@@ -83,11 +83,11 @@ Returns the MIME type for a filename based on its extension. Extracts the extens
 isValidName(name: string): boolean
 ```
 
-Validates a bucket or file name against security rules. Logs specific error messages for each validation failure.
+Validates a **single path segment** (bucket name or bare file name - no slashes) against security rules. Used internally by `isValidPath` to validate each segment. Logs specific error messages for each validation failure.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `name` | `string` | Name to validate. |
+| `name` | `string` | Single-segment name to validate (must not contain `/`). |
 
 **Returns:** `true` if the name passes all checks, `false` otherwise.
 
@@ -102,6 +102,30 @@ Validates a bucket or file name against security rules. Logs specific error mess
 7. Must not exceed 255 characters (DoS prevention)
 8. Must not be whitespace-only
 
+#### isValidPath
+
+```typescript
+isValidPath(pathStr: string, opts?: { maxDepth?: number }): boolean
+```
+
+Validates a **full object path** that may include folder segments (e.g., `2025/uploads/report.pdf`). Splits the path on `/`, validates each segment with `isValidName`, and enforces a maximum folder depth. Used for object name validation where paths with folder structure are allowed.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pathStr` | `string` | Path string to validate (may contain `/` separators). |
+| `opts.maxDepth` | `number` | Maximum folder depth. Default: `2`. |
+
+**Returns:** `true` if the path and all its segments are valid, `false` otherwise.
+
+**Validation rules (checked in order):**
+
+1. Must be a non-empty string
+2. After stripping leading/trailing slashes, must not be empty
+3. Must not contain empty segments (double slashes, e.g., `a//b`)
+4. Folder depth must not exceed `maxDepth` (depth = number of `/` separators)
+5. Every segment must pass `isValidName()`
+6. Total path length must not exceed 1024 characters
+
 #### getFileType
 
 ```typescript
@@ -132,6 +156,7 @@ abstract upload(opts: {
   files: IUploadFile[];
   normalizeNameFn?: (opts: { originalName: string; folderPath?: string }) => string;
   normalizeLinkFn?: (opts: { bucketName: string; normalizeName: string }) => string;
+  maxFolderDepth?: number;
 }): Promise<IUploadResult[]>;
 
 abstract getFile(opts: { bucket: string; name: string; options?: any }): Promise<Readable>;
@@ -228,14 +253,19 @@ async upload(opts: {
   files: IUploadFile[];
   normalizeNameFn?: (opts: { originalName: string; folderPath?: string }) => string;
   normalizeLinkFn?: (opts: { bucketName: string; normalizeName: string }) => string;
+  maxFolderDepth?: number;
 }): Promise<IUploadResult[]>
 ```
 
 Uploads files to a MinIO bucket. Returns `[]` if `files` is empty. Validates the bucket exists and all file names/sizes before uploading. Uploads run in parallel via `Promise.all()`.
 
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `opts.maxFolderDepth` | `number` | `BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH` (`2`) | Folder nesting the caller allows, for both `folderPath` and the normalized object name. |
+
 **Default name normalization:** Lowercased with spaces replaced by `_`. If `folderPath` is set, prepends `{folderPath}/`.
 
-**Default link format:** `/static-assets/{bucket}/{encodeURIComponent(normalizeName)}`
+**Default link format:** `/static-assets/{bucket}/{normalizeName}`, with each `/`-separated segment of `normalizeName` URI-encoded via `encodeURIComponent()`.
 
 **Metadata stored:** `originalName`, `normalizeName`, `size`, `encoding`, `mimeType`.
 
@@ -244,6 +274,7 @@ Uploads files to a MinIO bucket. Returns `[]` if `files` is empty. Validates the
 - `'[upload] Invalid original file name'`
 - `'[upload] Invalid folder path'`
 - `'[upload] Invalid file size'`
+- `'[upload] Invalid normalized object name | name: {name}'` -- the value returned by a custom `normalizeNameFn` is path-validated before use; a traversal payload is rejected here even if the original name passed validation.
 
 #### getFile
 
@@ -401,12 +432,13 @@ async upload(opts: {
   files: IUploadFile[];
   normalizeNameFn?: (opts: { originalName: string; folderPath?: string }) => string;
   normalizeLinkFn?: (opts: { bucketName: string; normalizeName: string }) => string;
+  maxFolderDepth?: number;
 }): Promise<IUploadResult[]>
 ```
 
-Uploads files using `client.write(name, buffer, { bucket, type })`. Same validation and normalization behavior as MinioHelper.
+Uploads files using `client.write(name, buffer, { bucket, type })`. Same validation and normalization behavior as MinioHelper, including `maxFolderDepth` and the normalized-name path validation.
 
-**Default link format:** `/static-assets/{bucket}/{encodeURIComponent(normalizeName)}`
+**Default link format:** `/static-assets/{bucket}/{normalizeName}`, with each `/`-separated segment of `normalizeName` URI-encoded via `encodeURIComponent()`.
 
 #### getFile
 
@@ -553,6 +585,7 @@ async upload(opts: {
   files: IUploadFile[];
   normalizeNameFn?: (opts: { originalName: string; folderPath?: string }) => string;
   normalizeLinkFn?: (opts: { bucketName: string; normalizeName: string }) => string;
+  maxFolderDepth?: number;
 }): Promise<IUploadResult[]>
 ```
 
@@ -560,13 +593,14 @@ Writes files to the bucket directory. Returns `[]` if `files` is empty. Validate
 
 **Default name normalization:** Same as MinioHelper -- lowercased with spaces replaced by `_`.
 
-**Default link format:** `/static-resources/{bucket}/{encodeURIComponent(normalizeName)}`
+**Default link format:** `/static-resources/{bucket}/{normalizeName}`, with each `/`-separated segment of `normalizeName` URI-encoded via `encodeURIComponent()`.
 
 **Throws:**
 - `'[upload] Bucket does not exist | name: {bucket}'`
 - `'[upload] Invalid original file name'`
 - `'[upload] Invalid folder path'`
 - `'[upload] Invalid file size'`
+- `'[upload] Invalid normalized object name | name: {name}'` -- the value returned by a custom `normalizeNameFn` is path-validated before it is written to disk; an unvalidated `../../../etc/cron.d/pwn` would otherwise write outside `basePath`.
 
 #### getFile
 
@@ -727,6 +761,7 @@ The unified interface implemented by `MinioHelper`, `BunS3Helper`, and `DiskHelp
 ```typescript
 interface IStorageHelper {
   isValidName(name: string): boolean;
+  isValidPath(pathStr: string, opts?: { maxDepth?: number }): boolean;
 
   isBucketExists(opts: { name: string }): Promise<boolean>;
   getBuckets(): Promise<IBucketInfo[]>;
@@ -739,6 +774,7 @@ interface IStorageHelper {
     files: IUploadFile[];
     normalizeNameFn?: (opts: { originalName: string; folderPath?: string }) => string;
     normalizeLinkFn?: (opts: { bucketName: string; normalizeName: string }) => string;
+    maxFolderDepth?: number;
   }): Promise<IUploadResult[]>;
 
   getFile(opts: { bucket: string; name: string; options?: any }): Promise<Readable>;
@@ -793,7 +829,7 @@ interface IFileStat {
   size: number;                     // File size in bytes
   metadata: Record<string, any>;    // Storage-specific metadata
   lastModified?: Date;              // Last modification date
-  etag?: string;                    // Entity tag (MinioHelper only)
+  etag?: string;                    // Entity tag (MinioHelper and BunS3Helper only)
   versionId?: string;               // Version ID (MinioHelper only)
 }
 ```

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

@@ -209,6 +209,23 @@ const results = await storage.upload({
 });
 ```
 
+> [!NOTE]
+> The output of `normalizeNameFn` is validated with `isValidPath()` before it reaches the filesystem or object store - a traversal payload returned from a custom function (e.g. `../../../etc/cron.d/pwn`) is rejected with `'[upload] Invalid normalized object name | name: {name}'`, not trusted just because it came from application code.
+
+#### Controlling Folder Depth
+
+`upload()` accepts an optional `maxFolderDepth` that overrides `BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH` (`2`) for that call. It bounds both the incoming `folderPath` on each file and the folder depth of the resulting normalized object name:
+
+```typescript
+const results = await storage.upload({
+  bucket: 'my-bucket',
+  files: files,
+  maxFolderDepth: 4, // allow up to 4 folder segments instead of the default 2
+});
+```
+
+Omit it to keep the default of `2`.
+
 #### Upload with Folder Path
 
 When `folderPath` is provided in an `IUploadFile`, the default normalization creates subdirectory-based paths:
@@ -281,7 +298,7 @@ console.log(stat);
 //   size: 204800,
 //   lastModified: 2025-01-15T10:30:00.000Z,
 //   metadata: { mimetype: 'application/pdf' },
-//   etag: 'abc123',       // MinioHelper only
+//   etag: 'abc123',       // MinioHelper and BunS3Helper only
 //   versionId: 'v1',      // MinioHelper only (if versioning enabled)
 // }
 ```
@@ -389,7 +406,14 @@ cache.clear();
 
 ### Name Validation
 
-All bucket and file operations validate names using `isValidName()` before execution. The following are rejected:
+Storage helpers use two validation methods depending on context:
+
+- **`isValidName(name)`** - validates a single path segment (bucket names, raw file names). Rejects names that contain `/`, `\`, or `..`.
+- **`isValidPath(pathStr)`** - validates a full object path that may include folder segments (e.g., `folder/file.pdf`). Splits on `/` and validates each segment with `isValidName`. Also enforces a max folder depth (default: 2).
+
+Bucket operations (create, remove) validate the bucket name with `isValidName()`. `upload()` validates each file's `originalName` with `isValidName()` and, when provided, the file's `folderPath` with `isValidPath()` so that folder structures like `2025/uploads` are accepted. Read and delete operations (`getFile`, `getStat`, `removeObject`, `listObjects`) do not re-validate names.
+
+The following single-segment inputs are rejected by `isValidName()`:
 
 | Rule | Example | Reason |
 |------|---------|--------|
@@ -401,9 +425,15 @@ All bucket and file operations validate names using `isValidName()` before execu
 | Empty or whitespace-only | `""`, `"   "` | Invalid input |
 
 ```typescript
+// Single-segment name validation (buckets, raw file names)
 storage.isValidName('my-file.pdf');    // true
-storage.isValidName('../etc/passwd');  // false
-storage.isValidName('.hidden');        // false
+storage.isValidName('../etc/passwd');  // false - contains path separators
+storage.isValidName('.hidden');        // false - starts with dot
+
+// Multi-segment path validation (object names with folder structure)
+storage.isValidPath('folder/file.pdf');       // true
+storage.isValidPath('../etc/passwd');         // false - path traversal
+storage.isValidPath('a/b/c/d/file.pdf');     // false - exceeds max depth (2)
 ```
 
 ### MIME Type Detection
@@ -536,7 +566,7 @@ await storage.removeBucket({ name: 'my-bucket' });
 
 ### "[upload] Bucket does not exist | name: {bucket}"
 
-**Cause:** The target bucket does not exist. Both DiskHelper and MinioHelper validate bucket existence before uploading.
+**Cause:** The target bucket does not exist. DiskHelper, MinioHelper, and BunS3Helper all validate bucket existence before uploading.
 
 **Fix:** Create the bucket before uploading:
 
@@ -566,7 +596,7 @@ await storage.upload({
 
 ### "[upload] Invalid file size"
 
-**Cause:** A file's `size` property is `0`, `undefined`, or falsy.
+**Cause:** A file's `size` property is `undefined`, `null`, or negative. A zero-byte file is a legal upload - it is not what triggers this error.
 
 **Fix:** Ensure every file in the upload array has a valid `size` value:
 
@@ -575,10 +605,16 @@ const file: IUploadFile = {
   originalName: 'doc.pdf',
   mimetype: 'application/pdf',
   buffer: fileBuffer,
-  size: fileBuffer.length, // Must be > 0
+  size: fileBuffer.length, // Must be a number >= 0
 };
 ```
 
+### "[upload] Invalid normalized object name | name: {name}"
+
+**Cause:** A custom `normalizeNameFn` returned a value that fails `isValidPath()` - typically a path-traversal payload (e.g. `../../../etc/cron.d/pwn`) or a name exceeding `maxFolderDepth`.
+
+**Fix:** Ensure `normalizeNameFn` returns a plain relative name/path with no `..` segments, no leading `/`, and no more folder segments than `maxFolderDepth` (default `2`) allows.
+
 ### "[getFile] File not found | bucket: {bucket} | name: {name}"
 
 **Cause:** DiskHelper throws when the requested file does not exist on the filesystem.

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

@@ -1,6 +1,6 @@
 # Helper Documentation Template
 
-Guide for writing consistent, professional helper reference docs for Ignis.
+Guide for writing consistent, professional helper reference docs for IGNIS.
 
 ## Tiers
 
@@ -21,6 +21,9 @@ Guide for writing consistent, professional helper reference docs for Ignis.
 | Socket.IO | 2 | Server + Client helpers, Redis integration |
 | WebSocket | 2 | Largest helper, Server + Emitter, complex internals |
 
+> [!NOTE]
+> Kafka uses an extended multi-page structure (`index.md` + `producer.md`, `consumer.md`, `admin.md`, `schema-registry.md`, `examples.md`) that goes beyond the Tier 2 two-page pattern.
+
 ## Principles
 
 - **Usage-first** -- Show working code early, not abstract API tables
@@ -54,13 +57,13 @@ Use **GitHub-style only**:
 |----------|---------|
 | [Single Page](./single-page) | Tier 1 template -- one file per helper |
 
-Tier 2 follows the same two-page pattern as [Component Tier 2](../../components/template/).
+Tier 2 helpers use two pages (`index.md` + `api.md`) -- see the existing Tier 2 helper docs (Network, Storage, Socket.IO, WebSocket) for the pattern. Note this differs from [Component Tier 2](../../components/template/), which is a four-page set.
 
 ## Source Paths
 
 | Package | Path |
 |---------|------|
-| Helpers | `packages/helpers/src/helpers/{name}/` |
+| Helpers | `packages/helpers/src/modules/{name}/` |
 | Inversion | `packages/inversion/src/` |
 | Common types | `packages/helpers/src/common/types.ts` |
 | Utilities | `packages/helpers/src/utilities/` |

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

@@ -8,6 +8,7 @@ Shared utility types, resolver functions, and constants exported from `@venizia/
 |------|-------|
 | **Package** | `@venizia/ignis-helpers` |
 | **Module** | Common types and constants |
+| **Source** | `packages/helpers/src/common/types.ts` (types + resolvers), `packages/helpers/src/common/constants/` (constants) |
 | **Runtimes** | Both |
 
 #### Import Paths
@@ -195,7 +196,7 @@ Synchronously resolves a lazy value:
 - **Class constructors** -- returned as-is (not invoked)
 - **Resolver functions** -- invoked and result returned
 
-Class constructors are detected via `isClassConstructor()` from `@venizia/ignis-inversion` and are never called as resolver functions.
+Class constructors are detected via `isClass()` (a source-level class-syntax check), which lives in `@venizia/ignis-inversion` and is re-exported by `helpers`; they are never called as resolver functions. `isClassConstructor` does not exist.
 
 #### resolveValueAsync
 
@@ -369,7 +370,7 @@ Schema data type constants with validation. `SCHEME_SET` contains all valid type
 
 The `HTTP` class groups all HTTP-related constants into nested objects.
 
-**Headers:**
+**Headers** (commonly used subset -- the full list in `packages/helpers/src/common/constants/http.ts` also covers content negotiation, CORS, security, proxy/forwarding, and rate-limit headers):
 
 | Constant | Value |
 |----------|-------|
@@ -389,7 +390,7 @@ The `HTTP` class groups all HTTP-related constants into nested objects.
 | `HTTP.Headers.RESPONSE_COUNT_DATA` | `'x-response-count'` |
 | `HTTP.Headers.RESPONSE_FORMAT` | `'x-response-format'` |
 
-**Header Values:**
+**Header Values** (commonly used subset -- the full list also covers XML, PDF, zip, image, CSS/CSV/HTML, and event-stream types):
 
 | Constant | Value |
 |----------|-------|
@@ -413,11 +414,13 @@ The `HTTP` class groups all HTTP-related constants into nested objects.
 
 **Result Codes:**
 
+Status codes are grouped by class under `HTTP.ResultCodes.RS_1` through `HTTP.ResultCodes.RS_5` (e.g. `HTTP.ResultCodes.RS_4.NotFound`).
+
 | Group | Constant | Value |
 |-------|----------|-------|
-| Top-level | `RS_FAIL` | `0` |
-| | `RS_SUCCESS` | `1` |
-| | `RS_UNKNOWN_ERROR` | `-199` |
+| **RS_1** (1xx) | `Continue` | `100` |
+| | `SwitchingProtocols` | `101` |
+| | `EarlyHints` | `103` |
 | **RS_2** (2xx) | `Ok` | `200` |
 | | `Created` | `201` |
 | | `Accepted` | `202` |
@@ -470,8 +473,8 @@ The `HTTP` class groups all HTTP-related constants into nested objects.
 **Derived Types:**
 
 ```typescript
-type THttpMethod = ValueOf<typeof HTTP.Methods>;       // 'get' | 'post' | 'put' | ...
-type THttpResultCode = ValueOf<typeof HTTP.ResultCodes>; // 0 | 1 | -199 | { Ok: 200, ... } | ...
+type THttpMethod = ValueOf<typeof HTTP.Methods>;         // 'get' | 'post' | 'put' | ...
+type THttpResultCode = ValueOf<typeof HTTP.ResultCodes>; // union of the RS_1..RS_5 group objects
 ```
 
 #### GRPC

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

@@ -17,8 +17,8 @@ The WebSocket helper provides two classes: `WebSocketServerHelper` for managing
                     |    |-- Store callbacks (auth, rooms, messages)   |
                     |    |-- Apply defaults (rooms, timeouts)          |
                     |    +-- initRedisClients(redisConnection)         |
-                    |          +-- redisPub = client.duplicate()       |
-                    |          +-- redisSub = client.duplicate()       |
+                    |          +-- redisPub = duplicateClient()        |
+                    |          +-- redisSub = duplicateClient()        |
                     |                                                   |
                     |  configure()  [async]                             |
                     |    |-- Connect Redis clients (if lazyConnect)    |
@@ -39,7 +39,7 @@ The WebSocket helper provides two classes: `WebSocketServerHelper` for managing
                      WebSocketEmitter
                     +---------------------------------------------------+
                     |  constructor(opts)                                |
-                    |    +-- redisPub = client.duplicate()              |
+                    |    +-- redisPub = duplicateClient()               |
                     |                                                   |
                     |  configure()  [async]                             |
                     |    +-- await Redis ready                          |
@@ -95,14 +95,14 @@ Client connects via WebSocket upgrade
 #### Redis 2-Client Architecture
 
 ```
-RedisHelper (parent -- NOT consumed)
+RedisSingleHelper (parent -- NOT consumed)
   |
-  +-- client.duplicate() --> redisPub    (publishes cross-instance messages)
+  +-- duplicateClient() --> redisPub    (publishes cross-instance messages)
   |
-  +-- client.duplicate() --> redisSub    (subscribes to cross-instance messages)
+  +-- duplicateClient() --> redisSub    (subscribes to cross-instance messages)
 ```
 
-Both single-instance `Redis` and `Cluster` connections from ioredis are supported. The parent `RedisHelper` connection remains independent.
+Both single-instance `Redis` and `Cluster` connections from ioredis are supported. The parent `RedisSingleHelper` connection remains independent.
 
 ## Server API
 
@@ -549,7 +549,7 @@ interface IWebSocketServerOptions<
 > {
   identifier: string;
   path?: string;                    // Default: '/ws'
-  redisConnection: DefaultRedisHelper;
+  redisConnection: IRedisHelper;
   server: IBunServer;
   defaultRooms?: string[];          // Default: ['ws-default', 'ws-notification']
   serverOptions?: IBunWebSocketConfig;
@@ -570,7 +570,7 @@ interface IWebSocketServerOptions<
 
 interface IWebSocketEmitterOptions {
   identifier?: string;              // Default: 'WebSocketEmitter'
-  redisConnection: DefaultRedisHelper;
+  redisConnection: IRedisHelper;
 }
 ```
 

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

@@ -58,7 +58,7 @@ const helper = new WebSocketServerHelper({
   identifier: 'my-ws-server',
   path: '/ws',
   server: bunServerInstance,           // Bun.Server
-  redisConnection: myRedisHelper,      // DefaultRedisHelper
+  redisConnection: myRedisHelper,      // IRedisHelper
   authenticateFn: async (data) => {
     const { token } = data as { token: string };
     const user = await verifyJWT(token);
@@ -89,7 +89,7 @@ await helper.configure();
 | `identifier` | `string` | Yes | -- | Unique name for this WebSocket server instance |
 | `path` | `string` | No | `'/ws'` | URL path for WebSocket upgrade requests |
 | `server` | `IBunServer` | Yes | -- | Bun server instance (provides `publish()` for native pub/sub) |
-| `redisConnection` | `DefaultRedisHelper` | Yes | -- | Redis helper for cross-instance messaging. Creates 2 duplicate connections internally |
+| `redisConnection` | `IRedisHelper` | Yes | -- | Redis helper for cross-instance messaging. Creates 2 duplicate connections internally |
 | `defaultRooms` | `string[]` | No | `['ws-default', 'ws-notification']` | Rooms clients auto-join after authentication |
 | `serverOptions` | `IBunWebSocketConfig` | No | See defaults below | Bun native WebSocket configuration |
 | `authTimeout` | `number` | No | `5000` (5s) | Milliseconds before unauthenticated clients are disconnected (close code `4001`) |
@@ -155,7 +155,7 @@ await emitter.configure();
 | Option | Type | Required | Default | Description |
 |--------|------|----------|---------|-------------|
 | `identifier` | `string` | No | `'WebSocketEmitter'` | Unique name for logging |
-| `redisConnection` | `DefaultRedisHelper` | Yes | -- | Redis helper. Creates 1 duplicate connection internally |
+| `redisConnection` | `IRedisHelper` | Yes | -- | Redis helper. Creates 1 duplicate connection internally |
 
 ## Usage
 
@@ -555,20 +555,20 @@ Authentication succeeds but the client is immediately closed with code `4004`.
 
 ### "[WebSocketServerHelper] Invalid redis connection!"
 
-Thrown during construction when `redisConnection` is `null`/`undefined`. Ensure you pass a valid `DefaultRedisHelper` instance.
+Thrown during construction when `redisConnection` is `null`/`undefined`. Ensure you pass a valid `IRedisHelper` instance (e.g., `RedisSingleHelper`).
 
 ### "[WebSocketEmitter] Invalid redis connection!"
 
-Thrown during `WebSocketEmitter` construction when `redisConnection` is `null`/`undefined`. Ensure you pass a valid `DefaultRedisHelper` instance.
+Thrown during `WebSocketEmitter` construction when `redisConnection` is `null`/`undefined`. Ensure you pass a valid `IRedisHelper` instance (e.g., `RedisSingleHelper`).
 
 ### "Redis client did not become ready within 30000ms"
 
-Thrown during `configure()` when a Redis client fails to reach `ready` status. Check that the Redis server is reachable and the parent `DefaultRedisHelper` connection is properly configured.
+Thrown during `configure()` when a Redis client fails to reach `ready` status. Check that the Redis server is reachable and the `IRedisHelper` instance is properly configured.
 
 ## See Also
 
 - [API Reference](./api) -- Full method signatures, types, and constants
 - [Socket.IO Helper](../socket-io/) -- Socket.IO-based alternative with Node.js support
-- [Redis Helper](../redis/) -- `RedisHelper` used for cross-instance messaging
+- [Redis Helper](../redis/) -- `RedisSingleHelper` or `RedisClusterHelper` used for cross-instance messaging
 - [Crypto Helper](../crypto/) -- ECDH key exchange for WebSocket encryption
 - [WebSocket Component](/extensions/components/websocket/) -- Component-level lifecycle integration

package/content/extensions/helpers/worker-thread/index.md

@@ -94,7 +94,7 @@ const worker = new BaseWorkerHelper<MyMessageType>({
 | `identifier` | `string` | -- | A unique name for this worker instance, used in log output. Required. |
 | `path` | `string \| URL` | -- | Path to the worker script file. Required. |
 | `options` | `WorkerOptions` | -- | Node.js `WorkerOptions` passed directly to `new Worker()`. Required. Supports `workerData`, `transferList`, `env`, etc. |
-| `scope` | `string` | `'BaseWorkerHelper'` | Logger scope prefix. |
+| `scope` | `string` | `'BaseWorkerHelper'` | Accepted but currently ignored -- the constructor always sets the logger scope to `'BaseWorkerHelper'`. |
 | `eventHandlers` | `Partial<Pick<IWorker<MessageType>, ...>>` | `undefined` | Optional overrides for lifecycle event callbacks. Any handler not provided falls back to default logging behavior. |
 
 #### Event Handler Overrides
@@ -425,7 +425,7 @@ const bus = thread.getWorkerBus({ key: 'my-bus' });
 
 ### "Failed to post message to main | Invalid parentPort!"
 
-**Cause:** `BaseWorkerBusHelper.postMessage()` was called but the `port` property is null or undefined. This typically means the bus was constructed with an invalid `MessagePort`.
+**Cause:** `BaseWorkerBusHelper.postMessage()` was called but the `port` property is null or undefined. This typically means the bus was constructed with an invalid `MessagePort`. Note this is logged at error level, not thrown -- the message is silently dropped.
 
 **Fix:** Ensure a valid `MessagePort` (e.g., `parentPort` from `node:worker_threads` or a port from `new MessageChannel()`) is passed to the constructor:
 

package/content/extensions/index.md

@@ -1,6 +1,6 @@
 # Extensions
 
-Extensions are optional packages and built-in modules that add functionality on top of the Ignis core framework. They are organized into two categories:
+Extensions are optional packages and built-in modules that add functionality on top of the IGNIS core framework. They are organized into two categories:
 
 ## Components
 
@@ -10,12 +10,12 @@ Components are self-contained feature modules that plug into your application vi
 | :--- | :--- | :--- |
 | [Authentication](./components/authentication/) | Identity verification | JWT, Basic, JWKS strategies |
 | [Authorization](./components/authorization/) | Access control | Casbin-based RBAC, per-route policies |
-| [Health Check](./components/health-check) | Liveness & readiness | `/health`, `/health/live`, `/health/ready` |
+| [Health Check](./components/health-check) | Liveness check | `GET /health`, `POST /health/ping` |
 | [Mail](./components/mail/) | Email delivery | Nodemailer, Mailgun, queue support |
 | [Request Tracker](./components/request-tracker) | Request tracing | `x-request-id` header, body parsing |
 | [Socket.IO](./components/socket-io/) | Real-time (Socket.IO) | Redis adapter, room-based messaging |
 | [Static Asset](./components/static-asset/) | File management | Upload/download, MinIO, Disk, BunS3 |
-| [Swagger](./components/swagger) | API docs | OpenAPI UI, Swagger UI, Scalar UI |
+| [Swagger](./components/api-reference) | API docs | OpenAPI UI, Swagger UI, Scalar UI |
 | [WebSocket](./components/websocket/) | Real-time (native) | Bun native WebSocket, encryption |
 
 ## Helpers
@@ -36,7 +36,6 @@ Helpers are standalone utility classes for infrastructure concerns. They extend
 | [Redis](./helpers/redis/) | Redis client | `ioredis` |
 | [Socket.IO](./helpers/socket-io/) | Socket.IO server | `socket.io` |
 | [Storage](./helpers/storage/) | File storage | `minio` (optional) |
-| [Testing](./helpers/testing/) | Test utilities | Built-in |
 | [Types](./helpers/types/) | Shared types | Built-in |
 | [UID](./helpers/uid/) | Snowflake IDs | Built-in |
 | [WebSocket](./helpers/websocket/) | WebSocket server | Built-in |