@venizia/ignis-docs 0.2.0 → 0.2.1-1

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

@@ -1,366 +1,328 @@
-# Socket.IO -- API Reference
+---
+title: Socket.IO Component - Full Reference
+description: Binding keys, configuration options, event payloads, method signatures, lifecycle diagrams, and internals
+difficulty: intermediate
+---
+
+# Socket.IO Component Reference
+
+Every binding key, configuration option, event payload, and internal mechanism of `SocketIOComponent`, `SocketIOServerHelper`, and `SocketIOClientHelper`. For the task-oriented walkthrough, see [Usage & Examples](./usage).
+
+**Files:**
+
+- [`packages/core-server/src/components/socket-io/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/socket-io/component.ts)
+- [`packages/core-server/src/components/socket-io/common/keys.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/socket-io/common/keys.ts)
+- [`packages/core-server/src/components/socket-io/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/socket-io/common/types.ts)
+- [`packages/core-server/src/components/socket-io/handlers/bun.handler.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/socket-io/handlers/bun.handler.ts)
+- [`packages/core-server/src/components/socket-io/handlers/node.handler.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/socket-io/handlers/node.handler.ts)
+- [`packages/helpers/src/modules/socket/socket-io/server/helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/socket/socket-io/server/helper.ts)
+- [`packages/helpers/src/modules/socket/socket-io/client/helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/socket/socket-io/client/helper.ts)
+- [`packages/helpers/src/modules/socket/socket-io/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/socket/socket-io/common/constants.ts)
+
+## Find what you need
+
+| You want to | Go to |
+|---|---|
+| See every default server option | [Default server options](#default-server-options) |
+| Find a binding key, its type, or whether it's required | [Binding keys](#binding-keys) |
+| Look up an event name or default room | [System events and rooms](#system-events-and-rooms) |
+| Understand the client authentication states | [Client states](#client-states) |
+| Compare Node.js vs Bun behavior | [Runtime-specific behavior](#runtime-specific-behavior) |
+| Call a method on the server helper | [Server helper: public methods](#server-helper-public-methods) |
+| Send a message that reaches another server instance | [Messaging via `send()`](#messaging-via-send) |
+| Call a method on the client helper | [Client helper: public methods](#client-helper-public-methods) |
+| Understand the post-start hook / boot lifecycle | [Lifecycle integration](#lifecycle-integration) |
+| See why one Redis connection becomes three | [Redis 3-client architecture](#redis-3-client-architecture) |
+| Read the full TypeScript type definitions | [Types reference](#types-reference) |
+| Look up an exact error message | [Error Reference](./errors) |
+
+## Quick reference
+
+| Item | Value |
+|---|---|
+| Package | `@venizia/ignis` (core component) + `@venizia/ignis-helpers` (helper classes) |
+| Component class | `SocketIOComponent` |
+| Server helper | [`SocketIOServerHelper`](/extensions/helpers/socket-io/) |
+| Client helper | [`SocketIOClientHelper`](/extensions/helpers/socket-io/) |
+| Runtimes | Node.js (`@hono/node-server`) and Bun (native) |
+| Scaling | `@socket.io/redis-adapter` + `@socket.io/redis-emitter` (`ioredis`) |
+
+## Import paths
+
+`SocketIOComponent` and `SocketIOBindingKeys` are exported only from the `@venizia/ignis/socket-io` subpath - never from the `@venizia/ignis` root barrel.
+
+```typescript
+// Core - subpath import only
+import { SocketIOComponent, SocketIOBindingKeys } from '@venizia/ignis/socket-io';
+
+// Helpers - subpath import
+import { SocketIOServerHelper, SocketIOClientHelper, SocketIOConstants } from '@venizia/ignis-helpers/socket-io';
+import type { TSocketIOAuthenticateFn, TSocketIOValidateRoomFn } from '@venizia/ignis-helpers/socket-io';
+```
+
+## Configuration reference
+
+### Default server options
+
+The component applies these defaults whenever `SocketIOBindingKeys.SERVER_OPTIONS` is unbound or only partially overridden.
+
+| Option | Default | Description |
+|---|---|---|
+| `identifier` | `'SOCKET_IO_SERVER'` | Unique identifier for the helper instance |
+| `path` | `'/io'` | URL path for the Socket.IO handshake and polling |
+| `cors.origin` | `'*'` | Allowed origins - restrict this in production |
+| `cors.methods` | `['GET', 'POST']` | Allowed HTTP methods for CORS preflight |
+| `cors.preflightContinue` | `false` | Pass preflight to the next handler |
+| `cors.optionsSuccessStatus` | `204` | Status code for a successful OPTIONS request |
+| `cors.credentials` | `true` | Allow cookies and auth headers |
+| `perMessageDeflate.threshold` | `4096` | Minimum message size to compress, in bytes |
+| `perMessageDeflate.concurrencyLimit` | `20` | Max concurrent compression operations |
+| `perMessageDeflate.clientNoContextTakeover` | `true` | Client releases its compression context after each message |
+| `perMessageDeflate.serverNoContextTakeover` | `true` | Server releases its compression context after each message |
+| `perMessageDeflate.serverMaxWindowBits` | `10` | Server-side max window size (2^10 = 1 KB) |
 
-> Architecture deep dive, method signatures, internals, and type definitions.
-
-## Architecture
-
-The component integrates Socket.IO into the IGNIS application lifecycle with runtime-specific initialization (Node.js vs Bun).
-
-#### Architecture Diagram
-```
-                         SocketIOComponent
-                        +----------------------------------------------+
-                        |                                              |
-                        |  binding()                                   |
-                        |    |-- resolveBindings()                     |
-                        |    |     |-- SERVER_OPTIONS                  |
-                        |    |     |-- REDIS_CONNECTION                |
-                        |    |     |-- AUTHENTICATE_HANDLER            |
-                        |    |     |-- VALIDATE_ROOM_HANDLER           |
-                        |    |     +-- CLIENT_CONNECTED_HANDLER        |
-                        |    |                                         |
-                        |    +-- RuntimeModules.detect()               |
-                        |          |-- BUN  -> registerBunHook()       |
-                        |          +-- NODE -> registerNodeHook()      |
-                        |                                              |
-                        |  (Post-start hooks execute after server)     |
-                        |    |-- Creates SocketIOServerHelper          |
-                        |    |-- await socketIOHelper.configure()      |
-                        |    |-- Binds to SOCKET_IO_INSTANCE           |
-                        |    +-- Wires into server (runtime-specific)  |
-                        +----------------------------------------------+
-```
-
-### Lifecycle Integration
-
-The component uses the **post-start hook** system to solve a fundamental timing problem: Socket.IO needs a running server instance, but components are initialized *before* the server starts.
-
-#### Application Lifecycle Diagram
-```
-Application Lifecycle
-=====================
-
-  +------------------+
-  |  preConfigure()  | <-- Register SocketIOComponent here
-  +--------+---------+
-           |
-  +--------v---------+
-  |  initialize()    | <-- Component.binding() runs here
-  |                  |   Resolves bindings, registers post-start hook
-  +--------+---------+
-           |
-  +--------v---------+
-  | setupMiddlewares  |
-  +--------+---------+
-           |
-  +--------v-----------------------+
-  | startBunModule()  OR          | <-- Server starts, instance created
-  | startNodeModule()             |
-  +--------+-----------------------+
-           |
-  +--------v--------------------------+
-  | executePostStartHooks()           | <-- SocketIOServerHelper created HERE
-  |   +-- socket-io-initialize        |   Server instance is now available
-  +-----------------------------------+
+> [!WARNING]
+> The default `cors.origin: '*'` is for development only. Restrict it to your domains in production.
+
+```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,
+  },
+};
 ```
 
-### Runtime-Specific Behavior
-
-| Aspect | Node.js | Bun |
-|--------|---------|-----|
-| **Server Type** | `node:http.Server` | `Bun.Server` |
-| **IO Server Init** | `new IOServer(httpServer, opts)` | `new IOServer()` + `io.bind(engine)` |
-| **Engine** | Built-in (`socket.io`) | `@socket.io/bun-engine` (optional peer dep) |
-| **Request Routing** | Socket.IO attaches to HTTP server automatically | `server.reload({ fetch, websocket })` wires engine into Bun's request loop |
-| **WebSocket Upgrade** | Handled by `node:http.Server` upgrade event | Handled by Bun's `websocket` handler |
-| **Dynamic Import** | None needed | `await import('@socket.io/bun-engine')` at runtime |
-| **Fetch Handler** | Not needed -- HTTP server handles upgrades | Custom fetch wraps Hono fetch, routes WS upgrades to engine |
-| **CORS** | Handled by `socket.io` CORS options | Handled by Bun engine options (requires explicit field bridging) |
-| **Server Access** | Direct -- Socket.IO attaches to HTTP server | `server.reload({ fetch, websocket })` to hot-swap handlers |
-
-### Runtime Differences -- Deep Dive
+### Custom configuration
 
-#### Bun Runtime
+Bind custom server options before registering the component:
 
-The Bun handler creates a custom fetch function that intercepts WebSocket upgrade requests:
-
-1. Checks if the request path matches the Socket.IO path (`serverOptions.path`, default `'/io'`)
-2. If yes, delegates to `@socket.io/bun-engine` via `engine.handleRequest(req, server)` for WebSocket protocol handling
-3. If no, delegates to Hono's normal `server.fetch(req, server)` handler
-
-#### Bun Fetch Handler Source
 ```typescript
-function createBunFetchHandler(opts: {
-  engine: any;
-  enginePath: string;
-  honoServer: OpenAPIHono;
-}): (req: Request, server: TBunServerInstance) => Response | Promise<Response> {
-  const { engine, enginePath, honoServer } = opts;
-
-  return (req: Request, server: TBunServerInstance): Response | Promise<Response> => {
-    const url = new URL(req.url);
-
-    if (!url.pathname.startsWith(enginePath)) {
-      return honoServer.fetch(req, server);
-    }
-
-    return engine.handleRequest(req, server) ?? new Response(null, { status: 404 });
-  };
-}
-```
-
-**CORS type bridging**: Socket.IO and `@socket.io/bun-engine` have slightly different CORS type definitions. The component extracts individual CORS fields explicitly to avoid type mismatches without using `as any`:
+import { SocketIOBindingKeys } from '@venizia/ignis/socket-io';
+import type { ServerOptions } from 'socket.io';
 
-#### Bun Engine CORS Bridging
-```typescript
-const corsConfig = typeof serverOptions.cors === 'object' ? serverOptions.cors : undefined;
-const engine = new BunEngine({
-  path: serverOptions.path ?? '/socket.io/',
-  ...(corsConfig && {
-    cors: {
-      origin: corsConfig.origin as string | RegExp | (string | RegExp)[] | undefined,
-      methods: corsConfig.methods,
-      credentials: corsConfig.credentials,
-      allowedHeaders: corsConfig.allowedHeaders,
-      exposedHeaders: corsConfig.exposedHeaders,
-      maxAge: corsConfig.maxAge,
-    },
-  }),
-});
-```
-
-#### Node.js Runtime
-
-Node mode is simpler because Socket.IO natively attaches to `node:http.Server`. The handler creates a `SocketIOServerHelper` with `runtime: RuntimeModules.NODE` and passes the HTTP server instance directly:
-
-#### Node.js Handler Source
-```typescript
-async function createNodeSocketIOHelper(opts: {
-  serverOptions: Partial<IServerOptions>;
-  httpServer: TNodeServerInstance;
-  resolvedBindings: IResolvedBindings;
-}): Promise<SocketIOServerHelper> {
-  const { serverOptions, httpServer, resolvedBindings } = opts;
-  const { redisConnection, authenticateFn, validateRoomFn, clientConnectedFn } = resolvedBindings;
-
-  const socketIOHelper = new SocketIOServerHelper({
-    runtime: RuntimeModules.NODE,
-    identifier: serverOptions.identifier!,
-    server: httpServer,
-    serverOptions,
-    redisConnection,
-    authenticateFn,
-    validateRoomFn,
-    clientConnectedFn,
-  });
-  await socketIOHelper.configure();
+const customOptions: Partial<ServerOptions> = {
+  path: '/socket.io',
+  cors: { origin: ['https://myapp.com'], methods: ['GET', 'POST'], credentials: true },
+  pingTimeout: 60000,
+  pingInterval: 25000,
+  maxHttpBufferSize: 1e6, // 1MB
+};
 
-  return socketIOHelper;
-}
+this.bind<Partial<ServerOptions>>({ key: SocketIOBindingKeys.SERVER_OPTIONS }).toValue(customOptions);
+this.component(SocketIOComponent);
 ```
 
-## Server Helper API Reference
+> [!NOTE]
+> `identifier` belongs to the component's `IServerOptions` interface, which extends Socket.IO's native `ServerOptions` - it's not a Socket.IO option itself. Set it by including it in the bound options object.
 
-### `SocketIOServerHelper` Constructor
+### Binding keys
 
-The helper uses a **discriminated union** for its constructor options, keyed on `runtime`:
+| Binding key | Constant | Type | Required | Default |
+|---|---|---|---|---|
+| `@app/socket-io/server-options` | `SERVER_OPTIONS` | `Partial<ServerOptions>` | No | [Default server options](#default-server-options) |
+| `@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 the component |
 
-#### `TSocketIOServerOptions` Type
-```typescript
-interface ISocketIOServerBaseOptions {
-  identifier: string;
-  serverOptions: Partial<ServerOptions>;
-  redisConnection: IRedisHelper;
-  defaultRooms?: string[];               // Default: ['io-default', 'io-notification']
-  authenticateTimeout?: number;           // Default: 10_000 (10 seconds)
-  pingInterval?: number;                  // Default: 30_000 (30 seconds)
+> [!NOTE]
+> `SOCKET_IO_INSTANCE` is never bound by application code. The component binds it automatically after the server starts. Inject it lazily - see [Inject the helper in a service or controller](./usage#inject-the-helper-in-a-service-or-controller).
 
-  authenticateFn: TSocketIOAuthenticateFn;
-  validateRoomFn?: TSocketIOValidateRoomFn;
-  clientConnectedFn?: TSocketIOClientConnectedFn;
-}
+### System events and rooms
 
-interface ISocketIOServerNodeOptions extends ISocketIOServerBaseOptions {
-  runtime: typeof RuntimeModules.NODE;
-  server: HTTPServer;                     // node:http.Server instance
-}
+Exported from `@venizia/ignis-helpers/socket-io` as `SocketIOConstants`. Used internally by both the component and the helper.
 
-interface ISocketIOServerBunOptions extends ISocketIOServerBaseOptions {
-  runtime: typeof RuntimeModules.BUN;
-  engine: any;                            // @socket.io/bun-engine Server instance
-}
+| Constant | Value | Description |
+|---|---|---|
+| `EVENT_PING` | `'ping'` | Keep-alive ping, emitted at `pingInterval` (default: 30s) |
+| `EVENT_CONNECT` | `'connection'` | New client connected (server-side event name) |
+| `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 the client |
+| `EVENT_UNAUTHENTICATE` | `'unauthenticated'` | Auth failure response sent to the client |
+| `ROOM_DEFAULT` | `'io-default'` | Default room every authenticated client joins |
+| `ROOM_NOTIFICATION` | `'io-notification'` | Notification broadcast room |
 
-type TSocketIOServerOptions = ISocketIOServerNodeOptions | ISocketIOServerBunOptions;
-```
+> [!TIP]
+> Override the default rooms with the `defaultRooms` option on `SocketIOServerHelper` - the values above are only the fallback.
 
-During construction:
+Two more constants govern default behavior. They're defined at module scope in the server helper, not exported, but overridable through constructor options:
 
-1. Sets `identifier`, `runtime`, `serverOptions`, callback functions
-2. Sets defaults: `authenticateTimeout` = 10s, `pingInterval` = 30s, `defaultRooms` = `['io-default', 'io-notification']`
-3. Calls `setRuntime()` -- validates and stores the server or engine
-4. Calls `initRedisClients()` -- creates 3 duplicated Redis clients from the connection
+| Constant | Value | Overridable via |
+|---|---|---|
+| `CLIENT_AUTHENTICATE_TIMEOUT` | `10_000` (10s) | `authenticateTimeout` |
+| `CLIENT_PING_INTERVAL` | `30_000` (30s) | `pingInterval` |
 
-> [!IMPORTANT]
-> Redis clients are **duplicated** from the parent connection (`client.duplicate()`). This means the helper uses 3 independent connections (pub, sub, emitter) that inherit config from the parent but maintain separate state. The parent `RedisSingleHelper` connection is not consumed.
+### Client states
 
-### `configure()` -- Server Initialization
+Each connected client tracks an authentication state that governs what it can do.
 
-The `configure()` method is the main initialization entry point, called after construction:
+| State | Constant | Description |
+|---|---|---|
+| `unauthorized` | `SocketIOClientStates.UNAUTHORIZED` | Initial state - the client must emit `authenticate` within the timeout (default: 10s) |
+| `authenticating` | `SocketIOClientStates.AUTHENTICATING` | Auth in progress - `authenticateFn` is running |
+| `authenticated` | `SocketIOClientStates.AUTHENTICATED` | Auth succeeded - the client can send/receive events and join rooms |
 
 ```
-configure()
-  |-- Register error handlers on all 3 Redis clients
-  |-- Connect any clients in 'wait' status (lazyConnect mode)
-  |-- await Promise.all([redisPub.ready, redisSub.ready, redisEmitter.ready])
-  |-- initIOServer()
-  |     |-- NODE: new IOServer(httpServer, serverOptions)
-  |     +-- BUN:  new IOServer() -> io.bind(bunEngine)
-  |-- io.adapter(createAdapter(redisPub, redisSub))
-  |-- emitter = new Emitter(redisEmitter)
-  +-- io.on('connection', onClientConnect)
+connect ----------> unauthorized --(emit 'authenticate')--> authenticating
+                        ^                                        |
+                        |                              success    failure
+                     timeout (10s)                       |          |
+                        |                                v          v
+                    disconnect  <---------------- authenticated  unauthorized -> disconnect
 ```
 
-> [!NOTE]
-> The `configure()` method is **async** because it waits for all 3 Redis connections to be ready before proceeding. If any Redis client fails to connect, the error propagates and the server will not start.
+## Architecture
 
-### Public Methods
+### Lifecycle integration
 
-#### `getIOServer()`
+Socket.IO needs a running server, but components initialize before the server starts. The application's **post-start hook** system bridges that gap.
 
-```typescript
-getIOServer(): IOServer
 ```
-
-Returns the underlying `socket.io` `Server` instance. Use this for direct access to Socket.IO APIs not exposed by the helper (e.g., `io.of('/namespace')`, `io.fetchSockets()`).
-
-#### `getEngine()`
-
-```typescript
-getEngine(): any
+preConfigure()          <- register SocketIOComponent here
+      |
+initialize()             <- component.binding() runs: resolve bindings, register post-start hook
+      |
+setupMiddlewares()
+      |
+startBunModule() / startNodeModule()   <- server starts, instance created
+      |
+executePostStartHooks()  <- 'socket-io-initialize' hook runs:
+      |                      new SocketIOServerHelper(...)
+      |                      await socketIOHelper.configure()
+      |                      bind SOCKET_IO_INSTANCE
+      |                      (Bun only) server.reload({ fetch, websocket })
 ```
 
-Returns the `@socket.io/bun-engine` instance. **Throws** if the runtime is Node.js (`"Engine is only available for Bun runtime!"`).
-
-#### `getClients()`
+- Hooks run **sequentially**, in registration order, each timed with `performance.now()` for diagnostics.
+- If a hook throws, the error propagates to `start()` and the server fails to start.
+- The hook identifier is `'socket-io-initialize'` for both runtimes - only one runtime path executes per application.
 
 ```typescript
-// Overloaded:
-getClients(): Map<string, ISocketIOClient>
-getClients(opts: { id: 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.
-
-#### `on()`
+// Register a hook, during the binding phase
+application.registerPostStartHook({
+  identifier: string,
+  hook: () => ValueOrPromise<void>,
+});
 
-```typescript
-on<HandlerArgsType extends unknown[] = unknown[], HandlerReturnType = void>(opts: {
-  topic: string;
-  handler: (...args: HandlerArgsType) => ValueOrPromise<HandlerReturnType>;
-}): void
+// Get the server instance, available only after start
+application.getServerInstance<T>(): T | undefined;
 ```
 
-Registers a server-level event handler on the IO server. **Throws** if `topic` is empty, `handler` is falsy, or the IO server is not initialized.
+### Runtime-specific behavior
 
-#### `ping()`
+| Aspect | Node.js | Bun |
+|---|---|---|
+| Server type | `node:http.Server` | `Bun.Server` |
+| IO server init | `new IOServer(httpServer, opts)` | `new IOServer()` then `io.bind(engine)` |
+| Engine | Built in (`socket.io`) | `@socket.io/bun-engine` (optional peer dependency) |
+| Request routing | Socket.IO attaches to the HTTP server automatically | `server.reload({ fetch, websocket })` wires the engine into Bun's request loop |
+| WebSocket upgrade | Handled by `node:http.Server`'s upgrade event | Handled by Bun's `websocket` handler |
+| Dynamic import | None needed | `await import('@socket.io/bun-engine')` at runtime |
+| Fetch handler | Not needed - the HTTP server handles upgrades | A custom fetch wraps Hono's fetch and routes WS upgrades to the engine |
+| CORS | Handled by Socket.IO's own CORS options | Handled by Bun engine options, via explicit field bridging |
 
-```typescript
-ping(opts: { socket: IOSocket; doIgnoreAuth: boolean }): void
-```
+### Bun runtime details
 
-Sends a `ping` event to a specific client with `{ time: <ISO string> }`. Behavior:
+A custom fetch function intercepts WebSocket upgrade requests before they reach Hono:
 
-- If `socket` is undefined, logs and returns
-- If client is not found in the client map, logs and returns
-- If `doIgnoreAuth` is `false` and the client is not `authenticated`, disconnects the client
-- If `doIgnoreAuth` is `true`, sends the ping regardless of auth state
+1. Checks whether the request path starts with the Socket.IO path (`serverOptions.path`, default `'/io'`).
+2. If it matches, delegates to `@socket.io/bun-engine` via `engine.handleRequest(req, server)`.
+3. If it doesn't, delegates to Hono's normal `server.fetch(req, server)` handler.
 
-Used internally for the keep-alive interval after authentication. The `doIgnoreAuth: true` flag is used for the initial post-auth ping and the recurring interval.
+Socket.IO and `@socket.io/bun-engine` define CORS slightly differently, so the component extracts each field explicitly instead of casting with `as any`. See [`createBunEngine()`](#post-start-hooks) in Internals for the full CORS bridging code.
 
-#### `disconnect()`
+### Node.js runtime details
 
-```typescript
-disconnect(opts: { socket: IOSocket }): void
-```
+Node mode is simpler - Socket.IO attaches to `node:http.Server` natively. The handler builds `SocketIOServerHelper` with `runtime: RuntimeModules.NODE` and passes the HTTP server instance directly. See [`createNodeSocketIOHelper()`](#post-start-hooks) in Internals.
 
-Disconnects a specific client and cleans up resources:
+## Server helper API reference
 
-1. Clears the ping interval (if set)
-2. Clears the authentication timeout
-3. Removes the client from the `clients` map
-4. Calls `socket.disconnect()` on the underlying Socket.IO socket
+### Constructor
 
-If the socket is `undefined` or not tracked in the client map, the method still calls `socket.disconnect()` for safety.
+`new SocketIOServerHelper(opts: TSocketIOServerOptions)` - see [server types](#server-types) for the full discriminated union.
 
-#### `onClientConnect()`
+| Step | What happens |
+|---|---|
+| 1 | Sets `identifier`, `runtime`, `serverOptions`, and the callback functions |
+| 2 | Applies defaults: `authenticateTimeout` = 10s, `pingInterval` = 30s, `defaultRooms` = `['io-default', 'io-notification']` |
+| 3 | `setRuntime()` validates and stores the server or engine - see [runtime validation](#setruntime-runtime-validation) |
+| 4 | `initRedisClients()` creates 3 duplicated Redis clients - see [Redis 3-client architecture](#redis-3-client-architecture) |
 
-```typescript
-onClientConnect(opts: { socket: IOSocket }): void
-```
+> [!IMPORTANT]
+> Redis clients are duplicated from the parent connection via `redisConnection.duplicateClient()`. The helper owns 3 independent connections (pub, sub, emitter) that inherit config from the parent but keep separate state. The parent connection is never consumed.
 
-Handles a new socket connection. Called by the `connection` event handler on the IO server. This method is public so it can be invoked externally for testing or custom connection routing.
+### `configure()`
 
-Behavior:
-1. Validates the socket exists (returns if `null`/`undefined`)
-2. Checks for duplicate connections by socket ID (returns if already tracked)
-3. Creates an `ISocketIOClient` entry with state `UNAUTHORIZED`
-4. Starts the authentication timeout (`authenticateTimeout` ms)
-5. Registers `disconnect` handler on the socket
-6. Registers `authenticate` handler via `registerAuthHandler()`
+The only async method on the helper. It waits for all 3 Redis clients to reach `ready` before building the IO server.
 
-#### `onClientAuthenticated()`
+1. Registers an `error` handler on each of the 3 Redis clients.
+2. Connects any client still in `wait` status (lazy-connect mode).
+3. Awaits all 3 clients reaching `ready`.
+4. Builds the IO server - `new IOServer(httpServer, serverOptions)` on Node.js, or `new IOServer()` + `io.bind(bunEngine)` on Bun.
+5. Wires the Redis adapter: `io.adapter(createAdapter(redisPub, redisSub))`.
+6. Creates the Redis emitter: `emitter = new Emitter(redisEmitter)`.
+7. Registers the `connection` handler, which calls `onClientConnect()` for every new socket.
 
-```typescript
-onClientAuthenticated(opts: { socket: IOSocket }): void
-```
+> [!NOTE]
+> If any Redis client fails to connect, the error propagates and the server does not start.
 
-Called after successful authentication. This method is public so it can be invoked externally for testing or custom auth flows.
+### Server helper: public methods
 
-Behavior:
-1. Validates the socket and client entry exist
-2. Sets client state to `AUTHENTICATED`
-3. Sends an initial ping
-4. Joins default rooms (`io-default`, `io-notification`)
-5. Registers room handlers (`join`, `leave`)
-6. Starts the ping interval
-7. Emits `authenticated` event to the client with `{ id, time }`
-8. Invokes the `clientConnectedFn` callback (if configured)
+| Method | Signature | Behavior |
+|---|---|---|
+| `getIOServer()` | `(): IOServer` | Returns the underlying `socket.io` `Server` - for APIs the helper doesn't expose, like `io.of()` or `io.fetchSockets()` |
+| `getEngine()` | `(): any` | Returns the `@socket.io/bun-engine` instance. Throws on Node.js runtime |
+| `getClients()` | `(opts?: { id? }): ISocketIOClient \| Map<string, ISocketIOClient> \| undefined` | Without `id`, returns the full client map. With `id`, returns that client or `undefined` |
+| `on()` | `(opts: { topic; handler }): void` | Registers a server-level event handler. Throws if `topic` is empty, `handler` is falsy, or the IO server isn't initialized |
+| `ping()` | `(opts: { socket; doIgnoreAuth }): void` | Sends `{ time }` to one client. No-op if `socket` or the client entry is missing. Disconnects the client if `doIgnoreAuth` is `false` and it isn't authenticated |
+| `disconnect()` | `(opts: { socket }): void` | Clears the client's ping interval and auth timeout, removes it from the client map, then calls `socket.disconnect()`. No-op if `socket` is falsy |
+| `onClientConnect()` | `(opts: { socket }): void` | Runs on every new connection: skips duplicates, creates the client entry (state `UNAUTHORIZED`), starts the auth timeout, and registers the `disconnect` and `authenticate` handlers |
+| `onClientAuthenticated()` | `(opts: { socket }): void` | Runs after successful auth: sets state `AUTHENTICATED`, sends the initial ping, joins default rooms, registers room handlers, starts the ping interval, and emits `authenticated` |
 
-### Messaging via `send()`
+- **`ping()` powers the keep-alive interval.** `doIgnoreAuth: true` covers both the initial post-auth ping and the recurring interval.
+- **`onClientConnect()` and `onClientAuthenticated()` are public** so tests and custom connection routing can call them directly.
+- **`clientConnectedFn` runs through a safety wrapper.** A synchronous throw inside your callback is caught and logged - it never crashes the process.
 
-The `send()` method uses the Redis emitter for message delivery, enabling cross-instance broadcasting:
+### Messaging via `send()`
 
 ```typescript
 send(opts: {
   destination?: string;    // Socket ID, room name, or omit for broadcast
-  payload: {
-    topic: string;         // Event name
-    data: any;             // Event payload
-  };
+  payload: { topic: string; data: any };
   doLog?: boolean;         // Log the emission (default: false)
-  cb?: () => void;         // Callback executed via setImmediate after emit
+  callback?: () => void;   // Executed via setImmediate after emit
 })
 ```
 
-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
-- Logging is opt-in (`doLog: true`) to avoid noise in high-throughput scenarios
-
-#### `send()` Silent Failure Behavior
+`send()` delivers through the Redis emitter, so it works even when the destination client is connected to a different server instance.
 
-The `send()` method silently returns (no error, no log) in these cases:
-- `payload` is falsy
-- `payload.topic` is falsy
-- `payload.data` is falsy
+| `destination` | Behavior |
+|---|---|
+| A socket ID or room name | `sender.to(destination).emit(topic, data)` |
+| Omitted or empty | Broadcasts to all connected clients: `sender.emit(topic, data)` |
 
-This is a deliberate design choice for fire-and-forget messaging patterns where callers do not need to know if a message was dropped due to missing fields.
+Every message is compressed via `emitter.compress(true)`. `callback` runs through `setImmediate()` - it confirms the emit call ran, not that a client received the message. Logging is opt-in (`doLog: true`) to avoid noise at high throughput.
 
-> [!TIP]
-> The emitter uses the Redis emitter client, so messages are delivered across all server instances in a horizontally-scaled deployment. This works even if the recipient is connected to a different server instance.
+`send()` returns silently, with no error and no log, when `payload`, `payload.topic`, or `payload.data` is falsy. That's deliberate: a fire-and-forget caller doesn't need to know a message was dropped for a missing field.
 
 ### Shutdown
 
@@ -368,17 +330,14 @@ This is a deliberate design choice for fire-and-forget messaging patterns where
 shutdown(): Promise<void>
 ```
 
-Gracefully shuts down the server:
-
-1. Iterates all tracked clients and clears their intervals/timeouts
-2. Disconnects each client socket
-3. Clears the client map
-4. Closes the IO server (async, wrapped in a Promise)
-5. Quits all 3 Redis connections (`redisPub`, `redisSub`, `redisEmitter`)
+1. Clears every tracked client's ping interval and auth timeout, then disconnects each socket.
+2. Clears the client map.
+3. Closes the IO server (`io.close()`, wrapped in a promise).
+4. Quits all 3 Redis connections (`redisPub`, `redisSub`, `redisEmitter`).
 
-## Client Helper API Reference
+## Client helper API reference
 
-`SocketIOClientHelper` extends `BaseHelper` and provides a managed Socket.IO client. It wraps the `socket.io-client` library with lifecycle callbacks, error-safe event subscription, and authentication state tracking.
+`SocketIOClientHelper` extends `BaseHelper` and wraps `socket.io-client` with lifecycle callbacks, error-safe event subscription, and authentication state tracking.
 
 ### Constructor
 
@@ -386,121 +345,59 @@ Gracefully shuts down the server:
 constructor(opts: ISocketIOClientOptions)
 ```
 
-#### `ISocketIOClientOptions` Interface
+See [client types](#client-types) for the full interface. `IOptions` extends `socket.io-client`'s `SocketOptions` with two required fields:
 
-```typescript
-interface ISocketIOClientOptions {
-  identifier: string;
-  host: string;
-  options: IOptions;
+| Field | Purpose |
+|---|---|
+| `path` | Must match the server's `path` |
+| `extraHeaders` | Commonly used for the `authorization` token |
 
-  // Lifecycle callbacks (all optional)
-  onConnected?: () => ValueOrPromise<void>;
-  onDisconnected?: (reason: string) => ValueOrPromise<void>;
-  onError?: (error: Error) => ValueOrPromise<void>;
-  onAuthenticated?: () => ValueOrPromise<void>;
-  onUnauthenticated?: (message: string) => ValueOrPromise<void>;
-}
-```
+Construction, in order:
 
-#### `IOptions` Interface
+1. Calls `super({ scope: opts.identifier })` to set up `BaseHelper` with scoped logging.
+2. Stores `identifier`, `host`, `options`, and every lifecycle callback.
+3. Calls `configure()` immediately to create the socket and register handlers.
 
-```typescript
-interface IOptions extends SocketOptions {
-  path: string;
-  extraHeaders: Record<string | symbol | number, any>;
-}
-```
-
-`IOptions` extends `SocketOptions` from `socket.io-client` with two required fields:
-- `path` -- the Socket.IO endpoint path (must match the server's `path` option, e.g., `'/io'`)
-- `extraHeaders` -- headers sent with every request, commonly used for `authorization` tokens
-
-#### Constructor Behavior
-
-1. Calls `super({ scope: opts.identifier })` to initialize `BaseHelper` with scoped logging
-2. Stores the `identifier`, `host`, `options`, and all lifecycle callbacks
-3. Immediately calls `configure()` to create the socket and register internal handlers
-
-### `configure()`
+### Client `configure()` event handlers
 
 ```typescript
 configure(): void
 ```
 
-Creates the `socket.io-client` `Socket` instance and registers all internal event handlers. If the client is already established (i.e., `configure()` was already called), logs a message and returns early.
-
-Registered handlers:
-
-| Event | Internal Behavior |
-|-------|-------------------|
-| `connect` | Logs connection, invokes `onConnected` callback |
-| `disconnect` | Logs disconnection with reason, resets state to `unauthorized`, invokes `onDisconnected` callback |
-| `connect_error` | Logs the error, invokes `onError` callback |
-| `authenticated` | Logs auth data, sets state to `authenticated`, invokes `onAuthenticated` callback |
-| `unauthenticated` | Logs warning with auth data, resets state to `unauthorized`, invokes `onUnauthenticated` callback with the message |
-| `ping` | Logs debug-level ping received |
-
-All lifecycle callbacks are wrapped in `Promise.resolve(...).catch(...)` to prevent callback errors from crashing the client.
-
-### `getState()`
-
-```typescript
-getState(): TSocketIOClientState
-```
-
-Returns the current authentication state: `'unauthorized'`, `'authenticating'`, or `'authenticated'`.
-
-#### `TSocketIOClientState` Type
-
-```typescript
-type TSocketIOClientState = TConstValue<typeof SocketIOClientStates>;
-// Resolves to: 'unauthorized' | 'authenticating' | 'authenticated'
-```
-
-### `getSocketClient()`
-
-```typescript
-getSocketClient(): Socket
-```
-
-Returns the raw `socket.io-client` `Socket` instance. Use this for direct access to Socket.IO client APIs not exposed by the helper (e.g., `socket.io`, `socket.connected`, `socket.id`).
+Creates the `socket.io-client` `Socket` instance and registers every internal handler. If `configure()` already ran, it logs a message and returns early.
 
-### `authenticate()`
+| Event | Internal behavior |
+|---|---|
+| `connect` | Logs the connection, invokes `onConnected` |
+| `disconnect` | Logs the disconnection with a reason, resets state to `unauthorized`, invokes `onDisconnected` |
+| `connect_error` | Logs the error, invokes `onError` |
+| `authenticated` | Logs the auth data, sets state to `authenticated`, invokes `onAuthenticated` |
+| `unauthenticated` | Logs a warning with the auth data, resets state to `unauthorized`, invokes `onUnauthenticated` with the message |
+| `ping` | Logs a debug-level "ping received" |
 
-```typescript
-authenticate(): void
-```
+Every lifecycle callback runs inside `Promise.resolve(...).catch(...)`, so a callback error never crashes the client.
 
-Initiates the authentication handshake by emitting the `authenticate` event to the server. The server will validate credentials from the socket handshake (headers, query, `auth` object) and respond with `authenticated` or `unauthenticated`.
+### Client helper: public methods
 
-Guard conditions (no-op with warning log):
-- Socket is not connected (`!this.client?.connected`)
-- Current state is not `unauthorized` (prevents double-auth or re-auth while authenticating)
+| Method | Signature | Behavior |
+|---|---|---|
+| `getState()` | `(): TSocketIOClientState` | Returns `'unauthorized'`, `'authenticating'`, or `'authenticated'` |
+| `getSocketClient()` | `(): Socket` | Returns the raw `socket.io-client` `Socket` - for APIs the helper doesn't expose, like `socket.id` |
+| `authenticate()` | `(): void` | Emits `authenticate`. No-op with a warning log unless connected and in state `unauthorized` |
+| `subscribe()` | `<T>(opts: { event; handler; ignoreDuplicate? }): void` | Subscribes with error-safe wrapping - see [below](#subscribe-error-safe-wrapping) |
+| `subscribeMany()` | `(opts: { events; ignoreDuplicate? }): void` | Calls `subscribe()` for every entry in `events` |
+| `unsubscribe()` | `(opts: { event; handler? }): void` | Removes one handler, or all handlers for the event if `handler` is omitted |
+| `unsubscribeMany()` | `(opts: { events: string[] }): void` | Calls `unsubscribe()` for every event in the array |
+| `connect()` | `(): void` | Manually connects. No-op with an info log if the client isn't initialized |
+| `disconnect()` | `(): void` | Manually disconnects. No-op with an info log if the client isn't initialized |
+| `emit()` | `<T>(opts: { topic; data; doLog?; callback? }): void` | Emits an event. Throws if not connected or `topic` is falsy - see [throw conditions](#emit-throw-conditions) |
+| `joinRooms()` | `(opts: { rooms: string[] }): void` | Emits `join` with `{ rooms }`. No-op with a warning log if not connected |
+| `leaveRooms()` | `(opts: { rooms: string[] }): void` | Emits `leave` with `{ rooms }`. No-op with a warning log if not connected |
+| `shutdown()` | `(): void` | Removes all listeners, disconnects if connected, resets state to `unauthorized` |
 
-On call:
-1. Sets state to `authenticating`
-2. Emits `SocketIOConstants.EVENT_AUTHENTICATE` (value: `'authenticate'`)
+#### `subscribe()` error-safe wrapping
 
-### `subscribe()`
-
-```typescript
-subscribe<T = unknown>(opts: {
-  event: string;
-  handler: TSocketIOEventHandler<T>;
-  ignoreDuplicate?: boolean;  // default: true
-}): void
-```
-
-Subscribes to a Socket.IO event with automatic error safety.
-
-Guard conditions (no-op with warning log):
-- `handler` is falsy
-- `ignoreDuplicate` is `true` (default) and the event already has listeners
-
-#### Handler Wrapping Pattern
-
-Handlers are wrapped in a **dual try-catch** that catches both synchronous throws and asynchronous rejections:
+Every handler is wrapped in a dual try-catch, so a broken handler never crashes the client:
 
 ```typescript
 const wrappedHandler = (data: T) => {
@@ -514,337 +411,234 @@ const wrappedHandler = (data: T) => {
 };
 ```
 
-The outer `try-catch` handles synchronous throws from the handler. The `.catch()` on `Promise.resolve()` handles async rejections. This ensures handler errors never crash the client.
-
-#### `TSocketIOEventHandler<T>` Type
-
-```typescript
-type TSocketIOEventHandler<T = unknown> = (data: T) => ValueOrPromise<void>;
-```
+The outer `try-catch` handles synchronous throws. The `.catch()` on `Promise.resolve()` handles async rejections.
 
-Handlers can be synchronous (`void`) or asynchronous (`Promise<void>`). Both are handled correctly by the wrapping pattern.
-
-### `subscribeMany()`
-
-```typescript
-subscribeMany(opts: {
-  events: Record<string, TSocketIOEventHandler>;
-  ignoreDuplicate?: boolean;
-}): void
-```
-
-Batch subscribes to multiple events. Iterates over the `events` record and calls `subscribe()` for each entry.
-
-### `unsubscribe()`
-
-```typescript
-unsubscribe(opts: { event: string; handler?: TSocketIOEventHandler }): void
-```
+#### `emit()` throw conditions
 
-Removes event listeners. If `handler` is provided, removes only that specific handler via `socket.off(event, handler)`. If `handler` is omitted, removes **all** handlers for the event via `socket.off(event)`.
-
-No-op if the socket has no listeners for the event.
-
-### `unsubscribeMany()`
-
-```typescript
-unsubscribeMany(opts: { events: string[] }): void
-```
-
-Removes all handlers for each event in the array. Calls `unsubscribe({ event })` for each entry.
-
-### `connect()`
-
-```typescript
-connect(): void
-```
-
-Manually connects the socket. No-op with an info log if the client is not initialized. Useful when `autoConnect: false` is set in the options.
-
-### `disconnect()`
-
-```typescript
-disconnect(): void
-```
-
-Manually disconnects the socket. No-op with an info log if the client is not initialized.
-
-### `emit()`
-
-```typescript
-emit<T = unknown>(opts: {
-  topic: string;
-  data: T;
-  doLog?: boolean;   // default: false
-  cb?: () => void;
-}): void
-```
-
-Emits an event to the server.
-
-**Throws** (via `getError()`) if:
-- 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.
-
-### `joinRooms()`
-
-```typescript
-joinRooms(opts: { rooms: string[] }): void
-```
-
-Emits a `join` event to the server with `{ rooms }`. The server will validate via `validateRoomFn` and perform the actual join.
-
-No-op with warning log if the socket is not connected.
-
-### `leaveRooms()`
-
-```typescript
-leaveRooms(opts: { rooms: string[] }): void
-```
-
-Emits a `leave` event to the server with `{ rooms }`. The server performs the actual leave without validation.
-
-No-op with warning log if the socket is not connected.
-
-### `shutdown()`
-
-```typescript
-shutdown(): void
-```
-
-Clean shutdown of the client:
-
-1. Calls `removeAllListeners()` on the underlying socket to prevent memory leaks
-2. Disconnects if still connected
-3. Resets state to `unauthorized`
+| Condition | statusCode | Message |
+|---|---|---|
+| Socket not connected | `400` | `"Invalid socket client state to emit"` |
+| `topic` is falsy | `400` | `"Topic is required to emit"` |
 
 ## Internals
 
 ### `resolveBindings()`
 
-Reads all binding keys from the DI container and validates required ones:
+Reads every binding key from the DI container and validates the required ones.
 
-| Binding | Validation | Error on Failure |
-|---------|-----------|------------------|
-| `SERVER_OPTIONS` | Optional, merged with defaults via `Object.assign()` | -- |
-| `REDIS_CONNECTION` | Must be `instanceof AbstractRedisHelper` | `"Invalid instance of redisConnection | Please init connection with RedisSingleHelper (single), RedisClusterHelper (cluster), or RedisSentinelHelper (sentinel)"` |
-| `AUTHENTICATE_HANDLER` | Must be a function (non-null) | `"[DANGER][SocketIOComponent] Invalid authenticateFn to setup io socket server!"` |
-| `VALIDATE_ROOM_HANDLER` | Optional, resolved from container, `null` coerced to `undefined` | -- |
-| `CLIENT_CONNECTED_HANDLER` | Optional, resolved from container, `null` coerced to `undefined` | -- |
+| Binding | Validation | Error on failure |
+|---|---|---|
+| `SERVER_OPTIONS` | Optional, merged with defaults via `Object.assign()` | - |
+| `REDIS_CONNECTION` | Must pass `isRedisHelper()` | `"Invalid instance of redisConnection..."` |
+| `AUTHENTICATE_HANDLER` | Must be a truthy function | `"[DANGER][SocketIOComponent] Invalid authenticateFn to setup io socket server!"` |
+| `VALIDATE_ROOM_HANDLER` | Optional, resolved from the container, `null` coerced to `undefined` | - |
+| `CLIENT_CONNECTED_HANDLER` | Optional, resolved from the container, `null` coerced to `undefined` | - |
 
-### `registerBunHook()`
+### Post-start hooks
 
-Registers a post-start hook that:
+Both runtimes register the same hook identifier, `'socket-io-initialize'`, but wire the helper differently.
 
-1. Calls `createBunEngine({ serverOptions })` which dynamically imports `@socket.io/bun-engine` and creates a `BunEngine` instance with CORS config bridging
-2. Creates `SocketIOServerHelper` with `runtime: RuntimeModules.BUN`
-3. Awaits `socketIOHelper.configure()` which waits for all Redis connections to be ready before initializing the adapter and emitter
-4. Binds the helper to `SOCKET_IO_INSTANCE`
-5. Gets the Bun server instance and Hono server, then calls `serverInstance.reload()` to wire the engine's `fetch` and `websocket` handlers into the running Bun server
+**Bun** (`registerBunHook()`):
 
-### `createBunEngine()` Function
+1. Calls `createBunEngine({ serverOptions })`, which dynamically imports `@socket.io/bun-engine` and builds a `BunEngine` instance with CORS bridging.
+2. Constructs `SocketIOServerHelper` with `runtime: RuntimeModules.BUN`.
+3. Awaits `socketIOHelper.configure()`.
+4. Binds the helper to `SOCKET_IO_INSTANCE`.
+5. Calls `serverInstance.reload({ fetch, websocket })` to wire the engine into the running Bun server.
 
 ```typescript
 async function createBunEngine(opts: {
   serverOptions: Partial<ServerOptions>;
-}): Promise<{ engine: any; engineHandler: any }>
-```
-
-Dynamically imports `@socket.io/bun-engine`, creates a `BunEngine` with CORS bridging, and returns both the `engine` and the `engineHandler` (from `engine.handler()`). The `engineHandler` provides the `websocket` handler that Bun's server needs.
-
-### `createBunFetchHandler()` Function
+}): Promise<{ engine: any; engineHandler: any }> {
+  const { serverOptions } = opts;
+  const { Server: BunEngine } = await import('@socket.io/bun-engine');
+
+  const corsConfig = typeof serverOptions.cors === 'object' ? serverOptions.cors : undefined;
+  const engine = new BunEngine({
+    path: serverOptions.path ?? '/socket.io/',
+    ...(corsConfig && {
+      cors: {
+        origin: corsConfig.origin as string | RegExp | (string | RegExp)[] | undefined,
+        methods: corsConfig.methods,
+        credentials: corsConfig.credentials,
+        allowedHeaders: corsConfig.allowedHeaders,
+        exposedHeaders: corsConfig.exposedHeaders,
+        maxAge: corsConfig.maxAge,
+      },
+    }),
+  });
 
-```typescript
-function createBunFetchHandler(opts: {
-  engine: any;
-  enginePath: string;
-  honoServer: OpenAPIHono;
-}): (req: Request, server: TBunServerInstance) => Response | Promise<Response>
+  return { engine, engineHandler: engine.handler() };
+}
 ```
 
-Returns a fetch handler function that routes requests:
-- If `url.pathname` starts with `enginePath`, delegates to `engine.handleRequest(req, server)` (returns 404 Response if `handleRequest` returns nullish)
-- Otherwise, delegates to `honoServer.fetch(req, server)` for normal Hono routing
-
-### `registerNodeHook()`
-
-Registers a post-start hook that:
+**Node.js** (`registerNodeHook()`):
 
-1. Gets the HTTP server instance via `getServerInstance()`
-2. Validates the server instance exists (throws `"[SocketIOComponent] HTTP server not available for Node.js runtime!"` if not)
-3. Calls `createNodeSocketIOHelper()` which creates `SocketIOServerHelper` with `runtime: RuntimeModules.NODE` and the HTTP server, then awaits `configure()`
-4. Binds the helper to `SOCKET_IO_INSTANCE`
+1. Gets the HTTP server via `getServerInstance()`. Throws `"[SocketIOComponent] HTTP server not available for Node.js runtime!"` if it's missing.
+2. Calls `createNodeSocketIOHelper()`, which constructs `SocketIOServerHelper` with `runtime: RuntimeModules.NODE` and the HTTP server, then awaits `configure()`.
+3. Binds the helper to `SOCKET_IO_INSTANCE`.
 
-Node mode is simpler because Socket.IO natively attaches to `node:http.Server`.
-
-### Redis 3-Client Architecture
-
-The server helper creates 3 independent Redis connections from a single `AbstractRedisHelper` instance:
+### Redis 3-client architecture
 
 ```
-RedisSingleHelper (parent -- NOT consumed)
+RedisSingleHelper (parent - NOT consumed)
   |
-  +-- client.duplicate() --> redisPub    (for Redis adapter -- publishes)
+  +-- duplicateClient() --> redisPub     (Redis adapter - publishes)
   |
-  +-- client.duplicate() --> redisSub    (for Redis adapter -- subscribes)
+  +-- duplicateClient() --> redisSub     (Redis adapter - subscribes)
   |
-  +-- client.duplicate() --> redisEmitter (for @socket.io/redis-emitter -- message delivery)
+  +-- duplicateClient() --> redisEmitter (Redis emitter - message delivery)
 ```
 
-**Why 3 clients?**
-- `@socket.io/redis-adapter` requires separate pub and sub clients because a Redis connection in subscribe mode cannot execute other commands
-- `@socket.io/redis-emitter` uses its own client to emit messages independently of the adapter, enabling cross-instance broadcasting even from contexts without a direct Socket.IO reference
-- The parent `RedisSingleHelper` connection remains independent and is not consumed -- it can be used for other purposes (e.g., caching, sessions)
+Three clients, not one, for two reasons:
+
+- **`@socket.io/redis-adapter` needs separate pub and sub clients.** A Redis connection in subscribe mode can't run other commands.
+- **`@socket.io/redis-emitter` needs its own client.** It emits messages independently of the adapter, so a process with no local Socket.IO server can still broadcast.
+
+The parent connection stays independent and unconsumed - reuse it for caching, sessions, or anything else.
 
-**`TRedisClient` type:**
 ```typescript
 type TRedisClient = Redis | Cluster;
 ```
 
-This supports both single-instance `Redis` and `Cluster` connections from ioredis, making the helper transparent to the Redis deployment topology.
-
-### `setRuntime()` -- Runtime Validation
+This alias covers both single-instance and `Cluster` connections from `ioredis`, so the helper is transparent to the Redis deployment topology.
 
-The private `setRuntime()` method validates the constructor options based on the `runtime` discriminant:
+### `setRuntime()` runtime validation
 
-| Runtime | Required Field | Error on Missing |
-|---------|---------------|------------------|
-| `RuntimeModules.NODE` | `opts.server` (HTTPServer) | `"Invalid HTTP server for Node.js runtime!"` |
-| `RuntimeModules.BUN` | `opts.engine` (BunEngine) | `"Invalid @socket.io/bun-engine instance for Bun runtime!"` |
-| Other | -- | `"Unsupported runtime!"` |
+| Runtime | Required field | Error on missing |
+|---|---|---|
+| `RuntimeModules.NODE` | `opts.server` (`HTTPServer`) | `"[SocketIOServerHelper] Invalid HTTP server for Node.js runtime!"` |
+| `RuntimeModules.BUN` | `opts.engine` (`BunEngine`) | `"[SocketIOServerHelper] Invalid @socket.io/bun-engine instance for Bun runtime!"` |
+| Other | - | `"[SocketIOServerHelper] Unsupported runtime!"` |
 
-### `initRedisClients()` -- Redis Initialization
+### `initRedisClients()`
 
-```typescript
-private initRedisClients(redisConnection: TSocketIOServerOptions['redisConnection']): void
-```
-
-**Throws** if `redisConnection` is falsy: `"Invalid redis connection to config socket.io adapter!"`
+Creates the 3 duplicated clients from the parent connection. Throws `"Invalid redis connection to config socket.io adapter!"` if `redisConnection` is falsy.
 
-Creates 3 duplicated clients from the parent connection's underlying ioredis client.
+### `initIOServer()`
 
-### `initIOServer()` -- IO Server Initialization
-
-Called during `configure()` after Redis connections are ready:
+Called during `configure()`, after the Redis connections are ready.
 
 | Runtime | Initialization |
-|---------|---------------|
+|---|---|
 | `RuntimeModules.NODE` | `this.io = new IOServer(this.server, this.serverOptions)` |
 | `RuntimeModules.BUN` | `this.io = new IOServer()` then `this.io.bind(this.bunEngine)` |
 | Other | Throws `"Unsupported runtime: <runtime>"` |
 
-Additional validation errors:
-- Node.js without `this.server`: `"[DANGER] Invalid HTTP server instance to init Socket.io server!"`
-- Bun without `this.bunEngine`: `"[DANGER] Invalid @socket.io/bun-engine instance to init Socket.io server!"`
+Two more guards run inside each branch:
 
-### Connection Lifecycle
+| Runtime | Missing field | Error |
+|---|---|---|
+| Node.js | `this.server` | `"[DANGER] Invalid HTTP server instance to init Socket.io server!"` |
+| Bun | `this.bunEngine` | `"[DANGER] Invalid @socket.io/bun-engine instance to init Socket.io server!"` |
 
-When a client connects, the server manages a strict authentication flow:
+### Connection lifecycle
 
 ```
 Client connects
-  |
-  +-- onClientConnect({ socket })
-  |     +-- Validate socket exists and not duplicate
-  |     +-- Create ISocketIOClient entry (state: UNAUTHORIZED)
-  |     +-- Start authenticateTimeout (10s default)
-  |     +-- Register 'disconnect' handler
-  |     +-- Register 'authenticate' handler
-  |
-  +-- Client emits 'authenticate'
-  |     +-- Validate client exists and state is UNAUTHORIZED
-  |     +-- Set state to AUTHENTICATING
-  |     +-- Call authenticateFn(handshake)
-  |           +-- Success -> onClientAuthenticated()
-  |           |     +-- Set state to AUTHENTICATED
-  |           |     +-- Send initial ping
-  |           |     +-- Join default rooms (io-default, io-notification)
-  |           |     +-- Register 'join' and 'leave' room handlers
-  |           |     +-- Start ping interval (30s default)
-  |           |     +-- Emit 'authenticated' with { id, time }
-  |           |     +-- Call clientConnectedFn({ socket }) if provided
-  |           +-- Failure -> emit 'unauthenticated' -> disconnect
-  |
-  +-- Timeout (10s) -> disconnect if not AUTHENTICATED
-```
+  -> onClientConnect(): validate socket, create client (state UNAUTHORIZED),
+     start authenticateTimeout (10s default), register 'disconnect' + 'authenticate' handlers
 
-#### Authentication Failure -- Two Code Paths
+Client emits 'authenticate'
+  -> validate client exists and state is UNAUTHORIZED, set state AUTHENTICATING
+  -> call authenticateFn(handshake)
+       success -> onClientAuthenticated(): state AUTHENTICATED, send initial ping,
+                  join default rooms, register 'join'/'leave' handlers,
+                  start ping interval, emit 'authenticated', call clientConnectedFn()
+       failure -> emit 'unauthenticated', disconnect
 
-The `registerAuthHandler()` method handles authentication results through two distinct code paths:
+Timeout (10s) -> disconnect if not yet AUTHENTICATED
+```
 
-**Path 1: `authenticateFn` returns `false`** (`.then()` handler):
-- Sets client state back to `UNAUTHORIZED`
-- Sends `unauthenticated` event with message: `"Invalid token to authenticate! Please login again!"`
-- Disconnects after send via `setImmediate` callback
-- No error logging (this is an expected outcome)
+#### Authentication failure paths
 
-**Path 2: `authenticateFn` throws an error** (`.catch()` handler):
-- Sets client state back to `UNAUTHORIZED`
-- Logs the error at error level
-- Sends `unauthenticated` event with message: `"Failed to authenticate connection! Please login again!"`
-- Sets `doLog: true` on the send call (unlike Path 1)
-- Disconnects after send via `setImmediate` callback
+`registerAuthHandler()` resolves an auth failure through one of two paths. Both check `this.clients.has(id)` first, in case the client disconnected mid-authentication.
 
-Both paths also handle the edge case where the client disconnected *during* authentication -- they check `this.clients.has(id)` before proceeding.
+| Path | Trigger | Actions |
+|---|---|---|
+| Rejected | `authenticateFn` resolves `false` | Reset state to `UNAUTHORIZED`. Send `unauthenticated` with `"Invalid token to authenticate! Please login again!"`. Disconnect after send (`setImmediate`). No error logged - this is an expected outcome. |
+| Threw | `authenticateFn` throws | Reset state to `UNAUTHORIZED`. Log the error. Send `unauthenticated` with `"Failed to authenticate connection! Please login again!"`. Disconnect after send (`setImmediate`). |
 
-#### `ISocketIOClient` Interface
 ```typescript
 interface ISocketIOClient {
   id: string;
   socket: IOSocket;
   state: TSocketIOClientState;              // 'unauthorized' | 'authenticating' | 'authenticated'
-  interval?: NodeJS.Timeout;                 // Ping interval (set after auth)
-  authenticateTimeout: NodeJS.Timeout;       // Auth deadline (cleared on success)
+  interval?: NodeJS.Timeout;                 // Ping interval, set after auth
+  authenticateTimeout?: NodeJS.Timeout;      // Auth deadline, undefined once cleared
 }
 ```
 
-### Room Handlers
-
-Room join/leave handlers are registered after successful authentication:
+### Room handlers
 
-- **`join`**: Client emits `{ rooms: string[] }`. If `validateRoomFn` is configured, only the rooms it returns are joined. If `validateRoomFn` is **not** configured, join is silently rejected with a warning log.
-- **`leave`**: Client emits `{ rooms: string[] }`. Leave is always allowed -- no validation function needed.
+Registered after successful authentication.
 
-Both handlers parse the payload defensively: `const { rooms = [] } = payload || { rooms: [] }`. Empty `rooms` arrays are silently ignored.
+| Handler | Behavior |
+|---|---|
+| `join` | Client sends `{ rooms }`. If `validateRoomFn` is bound, only the rooms it returns get joined. If it isn't bound, the join is rejected with a warning log. |
+| `leave` | Client sends `{ rooms }`. Always allowed - no validation function needed. |
 
-Join handler validation errors are caught and logged but do not disconnect the client.
+Both handlers parse the payload defensively: `const { rooms = [] } = payload || { rooms: [] }`. An empty array is silently ignored. A join error is caught and logged - it never disconnects the client.
 
 > [!WARNING]
-> Without a `validateRoomFn` bound, clients **cannot** join any custom rooms. They will only be in the default rooms (`io-default`, `io-notification`). This is a security-by-default design.
+> Without a `validateRoomFn` bound, clients **cannot** join any custom room - they stay in the default rooms only. This is security-by-default.
 
-## Types Reference
+### Graceful shutdown
 
-### Server Types
+Shut down Socket.IO before stopping the application:
 
 ```typescript
-// Server constructor options -- discriminated union on 'runtime'
+override async stop(): Promise<void> {
+  // 1. Shut down Socket.IO (disconnects all clients, closes the IO server, quits Redis)
+  const socketIOHelper = this.get<SocketIOServerHelper>({
+    key: SocketIOBindingKeys.SOCKET_IO_INSTANCE,
+    isOptional: true,
+  });
+  if (socketIOHelper) {
+    await socketIOHelper.shutdown();
+  }
+
+  // 2. Disconnect the Redis helper
+  if (this.redisHelper) {
+    await this.redisHelper.disconnect();
+  }
+
+  // 3. Stop the HTTP/Bun server
+  await super.stop();
+}
+```
+
+`socketIOHelper.shutdown()` runs the 4 steps under [Shutdown](#shutdown) above. `clientHelper.shutdown()` does the client-side equivalent: remove listeners, disconnect if connected, reset state.
+
+## Types reference
+
+### Server types
+
+```typescript
+// Server constructor options - discriminated union on 'runtime'
 type TSocketIOServerOptions = ISocketIOServerNodeOptions | ISocketIOServerBunOptions;
 
-// Base options shared by both runtimes
 interface ISocketIOServerBaseOptions {
   identifier: string;
   serverOptions: Partial<ServerOptions>;
   redisConnection: IRedisHelper;
-  defaultRooms?: string[];
-  authenticateTimeout?: number;
-  pingInterval?: number;
+  defaultRooms?: string[];               // Default: ['io-default', 'io-notification']
+  authenticateTimeout?: number;           // Default: 10_000 (10 seconds)
+  pingInterval?: number;                  // Default: 30_000 (30 seconds)
+
   authenticateFn: TSocketIOAuthenticateFn;
   validateRoomFn?: TSocketIOValidateRoomFn;
   clientConnectedFn?: TSocketIOClientConnectedFn;
 }
 
-// Node.js runtime variant
 interface ISocketIOServerNodeOptions extends ISocketIOServerBaseOptions {
   runtime: typeof RuntimeModules.NODE;
-  server: HTTPServer;
+  server: HTTPServer;                     // node:http.Server instance
 }
 
-// Bun runtime variant
 interface ISocketIOServerBunOptions extends ISocketIOServerBaseOptions {
   runtime: typeof RuntimeModules.BUN;
-  engine: any;
+  engine: any;                            // @socket.io/bun-engine Server instance
 }
 
 // Tracked client entry (server-side)
@@ -853,14 +647,13 @@ interface ISocketIOClient {
   socket: IOSocket;
   state: TSocketIOClientState;
   interval?: NodeJS.Timeout;
-  authenticateTimeout: NodeJS.Timeout;
+  authenticateTimeout?: NodeJS.Timeout;
 }
 
-// Redis client type alias
 type TRedisClient = Redis | Cluster;
 ```
 
-### Client Types
+### Client types
 
 ```typescript
 // Client constructor options
@@ -868,6 +661,8 @@ interface ISocketIOClientOptions {
   identifier: string;
   host: string;
   options: IOptions;
+
+  // Lifecycle callbacks (all optional)
   onConnected?: () => ValueOrPromise<void>;
   onDisconnected?: (reason: string) => ValueOrPromise<void>;
   onError?: (error: Error) => ValueOrPromise<void>;
@@ -881,39 +676,43 @@ interface IOptions extends SocketOptions {
   extraHeaders: Record<string | symbol | number, any>;
 }
 
-// Event handler type (supports sync and async)
 type TSocketIOEventHandler<T = unknown> = (data: T) => ValueOrPromise<void>;
 
-// Client state type
 type TSocketIOClientState = TConstValue<typeof SocketIOClientStates>;
 // Resolves to: 'unauthorized' | 'authenticating' | 'authenticated'
 ```
 
-### Callback Types
+### Callback types
 
 ```typescript
-// Server authentication handler
+// 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 };
+}
+
 type TSocketIOAuthenticateFn = (args: IHandshake) => ValueOrPromise<boolean>;
 
-// Server room validation handler
 type TSocketIOValidateRoomFn = (opts: {
   socket: IOSocket;
   rooms: string[];
 }) => ValueOrPromise<string[]>;
 
-// Server client connected handler
 type TSocketIOClientConnectedFn = (opts: { socket: IOSocket }) => ValueOrPromise<void>;
-```
-
-### Component Types
 
-```typescript
 // Extended ServerOptions with identifier
 interface IServerOptions extends ServerOptions {
   identifier: string;
 }
 
-// Resolved binding values from DI container
+// Resolved binding values from the DI container
 interface IResolvedBindings {
   redisConnection: IRedisHelper;
   authenticateFn: TSocketIOAuthenticateFn;
@@ -922,130 +721,8 @@ interface IResolvedBindings {
 }
 ```
 
-## Post-Start Hook System
-
-The Socket.IO component uses post-start hooks to solve a timing problem: Socket.IO needs a running server, but components initialize before the server starts.
-
-The component relies on `AbstractApplication`'s post-start hook system:
-
-#### API
-
-```typescript
-// Register a hook (during binding phase)
-application.registerPostStartHook({
-  identifier: string,                        // Unique name for logging
-  hook: () => ValueOrPromise<void>,          // Async function to execute
-});
-
-// Get the server instance (available after start)
-application.getServerInstance<T>(): T | undefined;
-```
-
-#### Hook Execution Flow
-
-```
-Application.start()
-  |
-  +-- Bun.serve() / serve()   <-- Server created
-  |
-  +-- executePostStartHooks()  <-- Hooks run here
-        |
-        +-- SocketIOComponent hook:
-              1. Get server instance via getServerInstance()
-              2. Create SocketIOServerHelper with runtime-specific options
-              3. Call helper.configure() to initialize Socket.IO server
-              4. Bind the helper instance for injection
-```
-
-#### Detailed Hook Timing
-```
-executePostStartHooks()
-  |-- Hook 1: "socket-io-initialize"
-  |     |-- performance.now() -> start
-  |     |-- await hook()
-  |     +-- log: "Executed hook | identifier: socket-io-initialize | took: 12.5 (ms)"
-  |-- Hook 2: "another-hook"
-  |     +-- ...
-  +-- (hooks run sequentially in registration order)
-```
-
-- Hooks run **sequentially** (not parallel) to guarantee ordering
-- Each hook is timed with `performance.now()` for diagnostics
-- If a hook throws, it propagates to `start()` and the server fails to start
-
-#### What Happens Inside the Hook
-
-For **Bun runtime**, the hook:
-
-1. Calls `createBunEngine({ serverOptions })` which dynamically imports `@socket.io/bun-engine` and creates a `BunEngine` instance with CORS config bridging
-2. Creates `SocketIOServerHelper` with `runtime: RuntimeModules.BUN` and the engine
-3. Awaits `socketIOHelper.configure()` which connects Redis pub/sub/emitter clients, initializes the `IOServer`, and sets up the Redis adapter
-4. Binds the helper to `SOCKET_IO_INSTANCE`
-5. Gets the Bun server instance and Hono server
-6. Calls `serverInstance.reload({ fetch, websocket })` to wire the engine's fetch and websocket handlers into the running Bun server, where `fetch` is the result of `createBunFetchHandler()` and `websocket` is from `engineHandler.websocket`
-
-For **Node.js runtime**, the hook:
-
-1. Gets the HTTP server instance via `getServerInstance()`
-2. Validates the server instance exists (throws if not)
-3. Calls `createNodeSocketIOHelper()` which creates `SocketIOServerHelper` with `runtime: RuntimeModules.NODE` and the HTTP server, then awaits `configure()`
-4. Binds the helper to `SOCKET_IO_INSTANCE`
-
-> [!NOTE]
-> The hook identifier is `'socket-io-initialize'` for both runtimes. Only one runtime path executes per application.
-
-### Graceful Shutdown
-
-Always shut down the Socket.IO server before stopping the application:
-
-#### Shutdown Implementation
-```typescript
-override async stop(): Promise<void> {
-  // 1. Shut down Socket.IO (disconnects all clients, closes IO server, quits Redis)
-  const socketIOHelper = this.get<SocketIOServerHelper>({
-    key: SocketIOBindingKeys.SOCKET_IO_INSTANCE,
-    isOptional: true,
-  });
-
-  if (socketIOHelper) {
-    await socketIOHelper.shutdown();
-  }
-
-  // 2. Disconnect Redis helper
-  if (this.redisHelper) {
-    await this.redisHelper.disconnect();
-  }
-
-  // 3. Stop the HTTP/Bun server
-  await super.stop();
-}
-```
-
-#### Shutdown Flow
-```
-socketIOHelper.shutdown()
-  |-- Disconnect all tracked clients
-  |     |-- clearInterval(ping)
-  |     |-- clearTimeout(authenticateTimeout)
-  |     +-- socket.disconnect()
-  |-- clients.clear()
-  |-- io.close() -- closes the Socket.IO server (async)
-  +-- Redis cleanup
-        |-- redisPub.quit()
-        |-- redisSub.quit()
-        +-- redisEmitter.quit()
-```
-
-Client helper shutdown:
-```
-clientHelper.shutdown()
-  |-- removeAllListeners() -- prevents memory leaks
-  |-- disconnect() -- if still connected
-  +-- state = UNAUTHORIZED
-```
-
-## See Also
+## See also
 
-- [Setup & Configuration](./) -- Quick reference, installation, bindings, constants
-- [Usage & Examples](./usage) -- Server-side usage, client helper, advanced patterns
-- [Error Reference](./errors) -- Error conditions and troubleshooting
+- [Overview](./) - quick start, imports, common configuration tasks
+- [Usage & Examples](./usage) - full setup steps, server-side usage, client helper, advanced patterns
+- [Error Reference](./errors) - error conditions and troubleshooting