@venizia/ignis-docs 0.2.0 → 0.2.1-0

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

@@ -1,6 +1,6 @@
 # Request Tracker
 
-Automatic request logging middleware with unique request IDs, client IP detection, body parsing, and timing -- auto-registered by the framework.
+Automatic request logging middleware that assigns a UUID request ID to every request, then 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.
@@ -20,225 +20,112 @@ Automatic request logging middleware with unique request IDs, client IP detectio
 import { RequestTrackerComponent } from '@venizia/ignis';
 ```
 
-## Setup
+## In one example
 
-### Step 1: Bind Configuration
-
-No configuration binding is required. The component has no user-facing configuration options.
-
-### Step 2: Register Component
-
-This happens automatically inside `BaseApplication.initialize()`:
-
-```typescript
-// Internal to BaseApplication -- shown for reference only
-this.component(RequestTrackerComponent);
-```
-
-The component registers two Hono middlewares on the application server during its `binding()` phase:
-1. `requestId()` from `hono/request-id` -- generates a UUID and stores it on the Hono context under the key `'requestId'`
-2. `RequestSpyMiddleware` -- logs request start/end with IP, method, path, query, body, and timing
-
-### Step 3: Use
-
-No injection or manual usage is needed. Once the application starts, every incoming request is automatically logged with a unique request ID.
-
-A sample log output in **non-production** mode looks like this:
+Nothing to configure - once the application starts, every request is logged automatically.
 
 ```
 [SpyMW] [<request-id>][127.0.0.1][=>] GET      /hello | query: {} | body: null
 [SpyMW] [<request-id>][127.0.0.1][<=] GET      /hello | Took: 1.23 (ms)
 ```
 
-In **production** mode (`NODE_ENV=production`), body is excluded but query is still logged:
+In **production** (`NODE_ENV=production`), the body is omitted; query is still logged:
 
 ```
 [SpyMW] [<request-id>][127.0.0.1][=>] GET      /hello | query: {}
 [SpyMW] [<request-id>][127.0.0.1][<=] GET      /hello | Took: 1.23 (ms)
 ```
 
-The log format follows this structure:
-
 | Direction | Format |
 |-----------|--------|
 | Incoming (`=>`) | `[requestId][clientIp][=>] METHOD   path \| query: {...} \| body: {...}` |
 | Outgoing (`<=`) | `[requestId][clientIp][<=] METHOD   path \| Took: X.XX (ms)` |
 
-The HTTP method is padded to 8 characters for consistent alignment in log output.
-
-> [!TIP]
-> The request ID is also available in the framework's error handlers (`notFoundHandler`, `appErrorHandler`), making it easy to correlate error logs with the original request.
-
-## Configuration
-
-The Request Tracker component has no user-configurable options. Its behavior is fully automatic.
-
-| Behavior | Description |
-|----------|-------------|
-| **Request ID** | Generated automatically via `hono/request-id` middleware (UUID), stored on context as `'requestId'` |
-| **IP Detection** | Priority: (1) connection info via `getIncomingIp()`, (2) `x-real-ip` header, (3) `x-forwarded-for` header |
-| **Body Logging** | Logs request body in non-production environments only. Query is always logged |
-| **Timing** | Measures and logs request duration in milliseconds (2 decimal places) via `performance.now()` |
-| **Scope** | Registered as a singleton provider |
-
-> [!NOTE]
-> In **production** (`NODE_ENV=production`), only the request **body** is excluded from log output to prevent sensitive data exposure. Query parameters are still logged in all environments.
-
-## Internals
-
-### RequestTrackerComponent
-
-The component class extends `BaseComponent`. It receives `BaseApplication` via `@inject({ key: CoreBindings.APPLICATION_INSTANCE })` in its constructor.
+The HTTP method is padded to 8 characters for consistent alignment.
 
-During construction, it creates a singleton binding for the middleware:
+## How it works
 
-```typescript
-Binding.bind({ key: RequestTrackerComponent.REQUEST_TRACKER_MW_BINDING_KEY })
-  .toProvider(RequestSpyMiddleware)
-  .setScope(BindingScopes.SINGLETON)
-```
-
-The binding key is constructed as `BindingNamespaces.MIDDLEWARE + '.' + RequestSpyMiddleware.name`, which resolves to `'middlewares.RequestSpyMiddleware'`.
-
-#### Component Lifecycle
-
-1. **`constructor()`** -- Receives `BaseApplication` via DI. Defines the middleware binding as a singleton provider.
-2. **`binding()`** -- Registers `requestId()` middleware on the server. Resolves the `RequestSpyMiddleware` binding from the DI container. Throws if the middleware cannot be resolved. Registers the resolved middleware on the server.
-
-### RequestSpyMiddleware
-
-The middleware class extends `BaseHelper` with scope `'SpyMW'` and implements `IProvider<MiddlewareHandler>`.
-
-```typescript
-class RequestSpyMiddleware extends BaseHelper implements IProvider<MiddlewareHandler> {
-  static readonly REQUEST_ID_KEY = 'requestId';
-  private isDebugMode: boolean;
-  // ...
-}
-```
-
-#### IProvider Pattern
-
-`RequestSpyMiddleware` implements the `IProvider<T>` interface from `@venizia/ignis-inversion`. This interface requires a single method:
+- **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.
 
-```typescript
-interface IProvider<T> {
-  value(container: Container): T;
-}
-```
-
-When the DI container resolves the binding (via `.toProvider(RequestSpyMiddleware)`), it instantiates the class and calls `value()` to obtain the actual `MiddlewareHandler`. This pattern allows the middleware to hold state (like `isDebugMode`) while producing a clean middleware function.
+> [!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.
 
-#### Debug Mode Detection
+## Common tasks
 
-The constructor checks `process.env.NODE_ENV`:
+### Correlate logs with a request
+Read the `requestId` context value inside your own handlers or middleware - the same ID appears in every `[SpyMW]` log line for that request.
 
 ```typescript
-constructor() {
-  super({ scope: 'SpyMW' });
-  const env = process.env.NODE_ENV?.toLowerCase();
-  this.isDebugMode = env !== Environment.PRODUCTION;
-}
+const requestId = context.get('requestId');
 ```
 
-When `isDebugMode` is `true` (any environment other than `'production'`), the incoming request log includes both `query` and `body`. When `false`, only `query` is logged.
-
-#### value() -- Middleware Handler
-
-The `value()` method returns a Hono middleware created via `createMiddleware()` from `hono/factory`. The middleware performs the following steps:
-
-1. Starts a performance timer via `performance.now()`
-2. Extracts the request ID from the Hono context (set by `requestId()` middleware)
-3. Resolves the client IP using the priority chain (see IP Detection below)
-4. Throws `'Malformed Connection Info'` (400) if both `incomingIp` and `forwardedIp` are `null`
-5. Extracts method, path, and query from the request
-6. Parses the request body via `parseBody()`
-7. Logs the incoming request with `[=>]` direction marker
-8. Calls `await next()` to proceed to the next middleware/handler
-9. Calculates duration and logs the outgoing response with `[<=]` direction marker
-
-#### parseBody()
-
-A public method that parses the request body based on `Content-Type` and `Content-Length` headers.
+### Reuse `parseBody` for your own middleware
+`parseBody` is a public method - reuse it wherever you need the same Content-Type-aware parsing.
 
 ```typescript
 async parseBody(opts: { req: TContext['req'] }): Promise<unknown>
 ```
 
-**Return conditions:**
+### Understand the client IP resolution order
+| Priority | Source | Notes |
+|----------|--------|-------|
+| 1 | `getIncomingIp(context)` | Native connection info - `hono/bun` on Bun, `@hono/node-server/conninfo` on Node.js |
+| 2 | `x-real-ip` header | Set by reverse proxies (e.g., Nginx `proxy_set_header X-Real-IP`) |
+| 3 | `x-forwarded-for` header | Standard proxy header |
+| 4 | `'unknown'` | Logged when none of the above resolve - the request still proceeds |
 
+### Understand body-parsing outcomes
 | Condition | Result |
 |-----------|--------|
-| No `Content-Type` header | Returns `null` |
-| No `Content-Length` header or value is `'0'` | Returns `null` |
-| `Content-Type` includes `application/json` | Calls `req.json()` |
-| `Content-Type` includes `multipart/form-data` | Calls `req.parseBody()` |
-| `Content-Type` includes `application/x-www-form-urlencoded` | Calls `req.parseBody()` |
-| Any other `Content-Type` (text, html, xml, etc.) | Calls `req.text()` |
-| Parsing fails for any content type | Throws `'Malformed Body Payload'` (HTTP 400) |
-
-### getIncomingIp() Utility
-
-A utility function that attempts to extract the client IP address from the Hono context using runtime-specific connection info.
-
-```typescript
-const getIncomingIp = (context: Context): string | null
-```
-
-**Runtime detection:**
-- Uses `RuntimeModules.isBun()` from `@venizia/ignis-helpers` to detect the runtime
-- On **Bun**: imports `getConnInfo` from `hono/bun`
-- On **Node.js**: imports `getConnInfo` from `@hono/node-server/conninfo`
-- Returns `connInfo.remote.address` if available, `null` otherwise
-- Returns `null` if `getConnInfo` is unavailable or throws
-
-#### IP Detection Priority
-
-The middleware resolves the client IP using a three-step fallback chain:
-
-| Priority | Source | Description |
-|----------|--------|-------------|
-| 1 | `getIncomingIp(context)` | Direct connection info from the runtime (Bun or Node.js) |
-| 2 | `x-real-ip` header | Set by reverse proxies (e.g., Nginx `proxy_set_header X-Real-IP`) |
-| 3 | `x-forwarded-for` header | Standard proxy header with original client IP |
+| No `Content-Type` header | `null` |
+| `Content-Length` is `'0'`, or no body stream present | `null` |
+| `Content-Type` includes `application/json` | `req.json()` |
+| `Content-Type` includes `multipart/form-data` or `application/x-www-form-urlencoded` | `req.parseBody()` |
+| `Content-Type` is `application/octet-stream` | Raw body stream |
+| Any other `Content-Type` (text, html, xml, etc.) | `req.text()` |
+| Parsing throws for any content type | `'Malformed Body Payload'` (HTTP 400) |
 
-The `clientIp` used in log output is resolved as `incomingIp ?? forwardedIp` -- meaning connection info takes precedence when available.
+## Reference
 
-If **all three** sources return `null`, the middleware throws a `'Malformed Connection Info'` error with HTTP 400 status.
-
-## Binding Keys
+### Configuration
+No user-configurable options - behavior is fully automatic.
 
+### Binding keys
 | Key | Constant | Type | Required | Default |
 |-----|----------|------|----------|---------|
-| `middlewares.RequestSpyMiddleware` | `RequestTrackerComponent.REQUEST_TRACKER_MW_BINDING_KEY` | `MiddlewareHandler` | Auto | Provided by component |
-
-The key is constructed from `BindingNamespaces.MIDDLEWARE` (`'middlewares'`) + `RequestSpyMiddleware.name` (`'RequestSpyMiddleware'`). The component binds `RequestSpyMiddleware` as a singleton provider at this key during construction.
-
-## Troubleshooting
-
-### "Invalid middleware to init request tracker | Please check again binding value"
+| `middlewares.RequestSpyMiddleware` | `RequestTrackerComponent.REQUEST_TRACKER_MW_BINDING_KEY` | `MiddlewareHandler` | Auto | Singleton provider, registered by the constructor |
 
-**Cause:** The `RequestSpyMiddleware` binding could not be resolved from the DI container during the component's `binding()` phase. This typically means the binding was removed or overwritten before `binding()` executed.
+The key is built as `BindingNamespaces.MIDDLEWARE` (`'middlewares'`) + `.` + `RequestSpyMiddleware.name`.
 
-**Fix:** Ensure no custom code unbinds or replaces the `middlewares.RequestSpyMiddleware` key. If you need to customize request logging, extend the component rather than removing the binding.
-
-### "Malformed Body Payload"
-
-**Cause:** The `RequestSpyMiddleware` attempted to parse the request body based on the `Content-Type` header, but the body content was malformed (e.g., invalid JSON with `application/json` content type, or corrupt form data).
-
-**Fix:** Ensure clients send valid body content that matches the declared `Content-Type` header. This error returns HTTP 400 Bad Request.
+### RequestSpyMiddleware
+```typescript
+class RequestSpyMiddleware extends BaseHelper implements IProvider<MiddlewareHandler> {
+  static readonly REQUEST_ID_KEY = 'requestId';
+  private isDebugMode: boolean;
+  // ...
+}
+```
 
-### "Malformed Connection Info"
+- Extends `BaseHelper` with scope `'SpyMW'`
+- Constructor sets `isDebugMode = process.env.NODE_ENV?.toLowerCase() !== Environment.PRODUCTION`
+- `value()` returns a Hono middleware built via `createMiddleware()` from `hono/factory`
 
-**Cause:** The middleware could not determine the client IP address from any source. All three must have failed: (1) `getIncomingIp()` returned `null` (runtime connection info unavailable), (2) `x-real-ip` header was absent, and (3) `x-forwarded-for` header was absent. This error returns HTTP 400 Bad Request.
+### Component lifecycle
+1. **`constructor()`** - Receives `BaseApplication` via DI. Defines the middleware binding as a singleton provider.
+2. **`binding()`** - Registers `requestId()` on the server. Resolves the `RequestSpyMiddleware` binding, throwing if it cannot be resolved. Registers the resolved middleware on the server.
 
-**Fix:** Ensure your reverse proxy (e.g., Nginx, Caddy) forwards at least one of these headers:
-- `x-real-ip`
-- `x-forwarded-for`
+## Troubleshooting
 
-If running without a proxy, ensure the runtime provides connection info (Bun does this natively; Node.js requires `@hono/node-server`).
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `Invalid middleware to init request tracker \| Please check again binding value` | `RequestSpyMiddleware` binding was unbound or overwritten before `binding()` ran | Don't unbind or replace `middlewares.RequestSpyMiddleware`; extend the component instead of removing its binding |
+| `Malformed Body Payload` (400) | Body content didn't match its declared `Content-Type` (e.g., invalid JSON with `application/json`) | Ensure clients send body content that matches the `Content-Type` header |
 
-## See Also
+## See also
 
 - **Guides:**
   - [Components Overview](/guides/core-concepts/components) - Component system basics
@@ -253,3 +140,9 @@ If running without a proxy, ensure the runtime provides connection info (Bun doe
 - **Best Practices:**
   - [Troubleshooting Tips](/best-practices/troubleshooting-tips) - Debugging with request IDs
   - [Deployment Strategies](/best-practices/deployment-strategies) - Production logging
+
+**Files:**
+
+- [`packages/core/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()`

package/content/extensions/components/socket-io/api.md

@@ -159,6 +159,177 @@ async function createNodeSocketIOHelper(opts: {
 }
 ```
 
+## Configuration Reference
+
+### Default Server Options
+
+The component applies these defaults if `SocketIOBindingKeys.SERVER_OPTIONS` is not bound or partially overridden:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `identifier` | `'SOCKET_IO_SERVER'` | Unique identifier for the helper instance |
+| `path` | `'/io'` | URL path for Socket.IO handshake/polling |
+| `cors.origin` | `'*'` | Allowed origins (restrict in production!) |
+| `cors.methods` | `['GET', 'POST']` | Allowed HTTP methods for CORS preflight |
+| `cors.preflightContinue` | `false` | Pass preflight to next handler |
+| `cors.optionsSuccessStatus` | `204` | Status code for successful OPTIONS requests |
+| `cors.credentials` | `true` | Allow cookies/auth headers |
+| `perMessageDeflate.threshold` | `4096` | Minimum message size to compress (bytes) |
+| `perMessageDeflate.concurrencyLimit` | `20` | Max concurrent compression operations |
+| `perMessageDeflate.clientNoContextTakeover` | `true` | Client releases compression context after each message |
+| `perMessageDeflate.serverNoContextTakeover` | `true` | Server releases compression context after each message |
+| `perMessageDeflate.serverMaxWindowBits` | `10` | Server-side maximum window size (2^10 = 1KB) |
+
+> [!WARNING]
+> The default `cors.origin: '*'` is suitable for development only. In production, restrict this to your specific domains.
+
+#### Full `DEFAULT_SERVER_OPTIONS`
+```typescript
+const DEFAULT_SERVER_OPTIONS: Partial<IServerOptions> = {
+  identifier: 'SOCKET_IO_SERVER',
+  path: '/io',
+  cors: {
+    origin: '*',
+    methods: ['GET', 'POST'],
+    preflightContinue: false,
+    optionsSuccessStatus: 204,
+    credentials: true,
+  },
+  perMessageDeflate: {
+    threshold: 4096,
+    zlibDeflateOptions: { chunkSize: 10 * 1024 },
+    zlibInflateOptions: { windowBits: 12, memLevel: 8 },
+    clientNoContextTakeover: true,
+    serverNoContextTakeover: true,
+    serverMaxWindowBits: 10,
+    concurrencyLimit: 20,
+  },
+};
+```
+
+### Custom Configuration
+
+Bind custom server options before registering the component:
+
+```typescript
+import { SocketIOBindingKeys } from '@venizia/ignis/socket-io';
+import type { ServerOptions } from 'socket.io';
+
+const customOptions: Partial<ServerOptions> = {
+  path: '/socket.io',
+  cors: {
+    origin: ['https://myapp.com', 'https://admin.myapp.com'],
+    methods: ['GET', 'POST'],
+    credentials: true,
+  },
+  pingTimeout: 60000,
+  pingInterval: 25000,
+  maxHttpBufferSize: 1e6, // 1MB
+};
+
+this.bind<Partial<ServerOptions>>({
+  key: SocketIOBindingKeys.SERVER_OPTIONS,
+}).toValue(customOptions);
+
+this.component(SocketIOComponent);
+```
+
+> [!NOTE]
+> `identifier` is part of the component's `IServerOptions` interface (which extends `ServerOptions`), not Socket.IO's native options. Set it by including it in the bound options object.
+
+### Binding Keys
+
+All binding keys are available on `SocketIOBindingKeys`:
+
+| Binding Key | Constant | Type | Required | Default |
+|------------|----------|------|----------|---------|
+| `@app/socket-io/server-options` | `SERVER_OPTIONS` | `Partial<ServerOptions>` | No | See defaults above |
+| `@app/socket-io/redis-connection` | `REDIS_CONNECTION` | `IRedisHelper` (`RedisSingleHelper` / `RedisClusterHelper` / `RedisSentinelHelper`) | **Yes** | `null` |
+| `@app/socket-io/authenticate-handler` | `AUTHENTICATE_HANDLER` | `TSocketIOAuthenticateFn` | **Yes** | `null` |
+| `@app/socket-io/validate-room-handler` | `VALIDATE_ROOM_HANDLER` | `TSocketIOValidateRoomFn` | No | `null` |
+| `@app/socket-io/client-connected-handler` | `CLIENT_CONNECTED_HANDLER` | `TSocketIOClientConnectedFn` | No | `null` |
+| `@app/socket-io/instance` | `SOCKET_IO_INSTANCE` | `SocketIOServerHelper` | -- | *Set by component* |
+
+> [!NOTE]
+> `SOCKET_IO_INSTANCE` is **not** set by you -- the component creates and binds it automatically after the server starts. Inject it in services/controllers via a lazy getter (see [Usage & Examples](./usage#server-side-usage)).
+
+### System Events and Rooms
+
+Constants are exported from `@venizia/ignis-helpers/socket-io` as `SocketIOConstants` and used internally by both the component and the helper.
+
+| Constant | Value | Description |
+|----------|-------|--------------|
+| `EVENT_PING` | `'ping'` | Keep-alive ping emitted at `pingInterval` (default: 30s) |
+| `EVENT_CONNECT` | `'connection'` | New client connected (server-side event) |
+| `EVENT_DISCONNECT` | `'disconnect'` | Client disconnected |
+| `EVENT_JOIN` | `'join'` | Client requests to join room(s) |
+| `EVENT_LEAVE` | `'leave'` | Client requests to leave room(s) |
+| `EVENT_AUTHENTICATE` | `'authenticate'` | Client sends auth credentials |
+| `EVENT_AUTHENTICATED` | `'authenticated'` | Auth success response sent to client |
+| `EVENT_UNAUTHENTICATE` | `'unauthenticated'` | Auth failure response sent to client |
+| `ROOM_DEFAULT` | `'io-default'` | Default room all authenticated clients join |
+| `ROOM_NOTIFICATION` | `'io-notification'` | Notification broadcast room |
+
+> [!TIP]
+> Override the default rooms via the `defaultRooms` option on `SocketIOServerHelper` -- the values above are only the fallback.
+
+#### Internal Constants (Server Helper)
+
+Defined at module scope in the server helper, not exported, but they govern default behavior:
+
+| Constant | Value | Description |
+|----------|-------|--------------|
+| `CLIENT_AUTHENTICATE_TIMEOUT` | `10_000` (10s) | Time allowed for a client to authenticate before forced disconnect |
+| `CLIENT_PING_INTERVAL` | `30_000` (30s) | Interval between server-to-client ping emissions |
+
+Both are overridable via the `authenticateTimeout` and `pingInterval` constructor options on `SocketIOServerHelper`.
+
+### Client States
+
+Each connected client tracks an authentication state that governs what actions are permitted:
+
+| State | Constant | Description |
+|-------|----------|--------------|
+| `unauthorized` | `SocketIOClientStates.UNAUTHORIZED` | Initial state -- client must emit `authenticate` within the timeout (default: 10s) |
+| `authenticating` | `SocketIOClientStates.AUTHENTICATING` | Auth in progress -- `authenticateFn` is executing |
+| `authenticated` | `SocketIOClientStates.AUTHENTICATED` | Auth successful -- client can send/receive events and join rooms |
+
+#### State Machine Diagram
+```
+                    +------------------+
+ connect ---------->|  unauthorized    |
+                    +--------+---------+
+                             | emit('authenticate')
+                    +--------v---------+
+                    |  authenticating   |
+                    +---+----------+---+
+            success |              | failure
+          +---------v--+   +-------v-----------+
+          |authenticated|   |   unauthorized   |--> disconnect
+          +-------------+   +------------------+
+                                  ^
+                            timeout (10s)
+```
+
+#### `SocketIOClientStates` Source
+```typescript
+export class SocketIOClientStates {
+  static readonly UNAUTHORIZED = 'unauthorized';
+  static readonly AUTHENTICATING = 'authenticating';
+  static readonly AUTHENTICATED = 'authenticated';
+
+  static readonly SCHEME_SET = new Set([
+    this.UNAUTHORIZED,
+    this.AUTHENTICATING,
+    this.AUTHENTICATED,
+  ]);
+
+  static isValid(input: string): input is TConstValue<typeof SocketIOClientStates> {
+    return this.SCHEME_SET.has(input);
+  }
+}
+```
+
 ## Server Helper API Reference
 
 ### `SocketIOServerHelper` Constructor
@@ -244,9 +415,7 @@ Returns the `@socket.io/bun-engine` instance. **Throws** if the runtime is Node.
 #### `getClients()`
 
 ```typescript
-// Overloaded:
-getClients(): Map<string, ISocketIOClient>
-getClients(opts: { id: string }): ISocketIOClient | undefined
+getClients(opts?: { id?: string }): ISocketIOClient | Map<string, ISocketIOClient> | undefined
 ```
 
 When called without arguments, returns the full client map. When called with `{ id }`, returns the specific client entry or `undefined` if not found.
@@ -290,7 +459,7 @@ Disconnects a specific client and cleans up resources:
 3. Removes the client from the `clients` map
 4. Calls `socket.disconnect()` on the underlying Socket.IO socket
 
-If the socket is `undefined` or not tracked in the client map, the method still calls `socket.disconnect()` for safety.
+If `socket` is falsy, the method returns immediately -- no cleanup, no `socket.disconnect()` call. If the socket exists but is not tracked in the `clients` map, steps 1-3 are skipped but `socket.disconnect()` is still called.
 
 #### `onClientConnect()`
 
@@ -338,7 +507,7 @@ send(opts: {
     data: any;             // Event payload
   };
   doLog?: boolean;         // Log the emission (default: false)
-  cb?: () => void;         // Callback executed via setImmediate after emit
+  callback?: () => void;   // Executed via setImmediate after emit
 })
 ```
 
@@ -347,7 +516,7 @@ Key behaviors:
 - All messages are **compressed** via `emitter.compress(true)`
 - If `destination` is provided and non-empty, sends via `sender.to(destination).emit(topic, data)`
 - If `destination` is omitted/empty, broadcasts to **all** connected clients via `sender.emit(topic, data)`
-- Callback (`cb`) is executed asynchronously via `setImmediate()`, not after delivery confirmation
+- `callback` is executed asynchronously via `setImmediate()`, not after delivery confirmation
 - Logging is opt-in (`doLog: true`) to avoid noise in high-throughput scenarios
 
 #### `send()` Silent Failure Behavior
@@ -575,8 +744,8 @@ Manually disconnects the socket. No-op with an info log if the client is not ini
 emit<T = unknown>(opts: {
   topic: string;
   data: T;
-  doLog?: boolean;   // default: false
-  cb?: () => void;
+  doLog?: boolean;       // default: false
+  callback?: () => void;
 }): void
 ```
 
@@ -586,7 +755,7 @@ Emits an event to the server.
 - The socket is not connected (`statusCode: 400`, message: `"Invalid socket client state to emit"`)
 - The `topic` is falsy (`statusCode: 400`, message: `"Topic is required to emit"`)
 
-If `cb` is provided, it is executed via `setImmediate()` (asynchronously, not after server acknowledgment). If `doLog` is `true`, logs the topic and data.
+If `callback` is provided, it is executed via `setImmediate()` (asynchronously, not after server acknowledgment). If `doLog` is `true`, logs the topic and data.
 
 ### `joinRooms()`
 
@@ -796,7 +965,7 @@ interface ISocketIOClient {
   socket: IOSocket;
   state: TSocketIOClientState;              // 'unauthorized' | 'authenticating' | 'authenticated'
   interval?: NodeJS.Timeout;                 // Ping interval (set after auth)
-  authenticateTimeout: NodeJS.Timeout;       // Auth deadline (cleared on success)
+  authenticateTimeout?: NodeJS.Timeout;      // Auth deadline (undefined after it's cleared)
 }
 ```
 
@@ -853,7 +1022,7 @@ interface ISocketIOClient {
   socket: IOSocket;
   state: TSocketIOClientState;
   interval?: NodeJS.Timeout;
-  authenticateTimeout: NodeJS.Timeout;
+  authenticateTimeout?: NodeJS.Timeout;
 }
 
 // Redis client type alias
@@ -892,6 +1061,19 @@ type TSocketIOClientState = TConstValue<typeof SocketIOClientStates>;
 ### Callback Types
 
 ```typescript
+// Handshake payload passed to the authenticate handler
+interface IHandshake {
+  headers: IncomingHttpHeaders;
+  time: string;
+  address: string;
+  xdomain: boolean;
+  secure: boolean;
+  issued: number;
+  url: string;
+  query: ParsedUrlQuery;
+  auth: { [key: string]: any };
+}
+
 // Server authentication handler
 type TSocketIOAuthenticateFn = (args: IHandshake) => ValueOrPromise<boolean>;
 
@@ -1046,6 +1228,6 @@ clientHelper.shutdown()
 
 ## See Also
 
-- [Setup & Configuration](./) -- Quick reference, installation, bindings, constants
-- [Usage & Examples](./usage) -- Server-side usage, client helper, advanced patterns
+- [Setup & Configuration](./) -- Quick reference, required bindings, how it works
+- [Usage & Examples](./usage) -- Full setup steps, server-side usage, client helper, advanced patterns
 - [Error Reference](./errors) -- Error conditions and troubleshooting

package/content/extensions/components/socket-io/errors.md

@@ -116,6 +116,6 @@ socket.on('authenticated', (data) => {
 
 ## See Also
 
-- [Setup & Configuration](./) -- Quick reference, installation, bindings, constants
-- [Usage & Examples](./usage) -- Server-side usage, client helper, advanced patterns
-- [API Reference](./api) -- Architecture, method signatures, internals, types
+- [Setup & Configuration](./) -- Quick reference, required bindings, how it works
+- [Usage & Examples](./usage) -- Full setup steps, server-side usage, client helper, advanced patterns
+- [API Reference](./api) -- Architecture, configuration reference, method signatures, internals, types