@venizia/ignis-docs 0.2.0 → 0.2.1-1

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

@@ -1,64 +1,103 @@
-# Socket.IO -- API Reference
+---
+title: Socket.IO - Full Reference
+description: Complete reference for SocketIOServerHelper and SocketIOClientHelper - every option, method signature, type, constant, and error case
+difficulty: intermediate
+---
 
-> Full method signatures, type definitions, and constants for `SocketIOServerHelper` and `SocketIOClientHelper`.
+# Socket.IO - Full Reference
+
+Exhaustive reference for `SocketIOServerHelper` and `SocketIOClientHelper`. For a readable introduction and the common tasks, start with the [Socket.IO overview](/extensions/helpers/socket-io/).
+
+**Files:**
+
+- [`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) - `SocketIOServerHelper`
+- [`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) - `SocketIOClientHelper`
+- [`packages/helpers/src/modules/socket/socket-io/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/socket/socket-io/common/types.ts) - option and callback types
+- [`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) - `SocketIOConstants`, `SocketIOClientStates`
+- [`packages/helpers/src/modules/socket/socket-io/index.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/socket/socket-io/index.ts) - barrel export (`@venizia/ignis-helpers/socket-io`)
+
+## Find what you need
+
+| You want to | Go to |
+|---|---|
+| See the full server and client call sequence | [Architecture](#architecture) |
+| Look up a server method (`send()`, `on()`, `getClients()`, ...) | [Server API](#server-api) |
+| Look up a client method (`emit()`, `subscribe()`, `joinRooms()`, ...) | [Client API](#client-api) |
+| Follow the auth handshake step by step | [Authentication Protocol](#authentication-protocol) |
+| Understand the three Redis connections | [Redis Adapter](#redis-adapter) |
+| Look up a type, option, or callback signature | [Types Reference](#types-reference) |
+| Look up an event name, room default, or client state | [Constants](#constants) |
+| Match an error message to its cause | [Common Errors](#common-errors) |
 
 ## Architecture
 
 ```
 SocketIOServerHelper (extends BaseHelper)
   |
-  |-- configure()
-  |     |-- waitForRedisReady() x3 (pub, sub, emitter)
-  |     |-- initIOServer() (Node.js HTTPServer or Bun engine)
+  |-- constructor(opts)
+  |     |-- setRuntime(opts)                  # validates `server` (Node) or `engine` (Bun)
+  |     +-- initRedisClients(opts.redisConnection)
+  |           |-- redisPub = duplicateClient()
+  |           |-- redisSub = duplicateClient()
+  |           +-- redisEmitter = duplicateClient()
+  |
+  |-- configure()  [async]
+  |     |-- ensureRedisClientsConnecting([redisPub, redisSub, redisEmitter])
+  |     |-- await Promise.all(waitForRedisReady x3)   # 30s timeout per client
+  |     |-- initIOServer()                     # new IOServer(server, serverOptions) | new IOServer() + io.bind(engine)
   |     |-- io.adapter(createAdapter(redisPub, redisSub))
-  |     |-- new Emitter(redisEmitter)
-  |     +-- io.on('connection', onClientConnect)
+  |     |-- emitter = new Emitter(redisEmitter)
+  |     +-- io.on('connection', socket => onClientConnect({ socket }))
   |
   |-- onClientConnect({ socket })
-  |     |-- Create ISocketIOClient (state: UNAUTHORIZED)
+  |     |-- Create ISocketIOClient entry (state: UNAUTHORIZED)
   |     |-- Start authenticateTimeout timer
   |     |-- Register 'disconnect' handler
-  |     +-- Register 'authenticate' handler
-  |           |-- authenticateFn(handshake)
-  |           +-- onClientAuthenticated({ socket })
-  |                 |-- State -> AUTHENTICATED
-  |                 |-- Join defaultRooms
-  |                 |-- Register room handlers (join/leave)
-  |                 |-- Start ping interval
-  |                 |-- Emit 'authenticated' to client
-  |                 +-- Invoke clientConnectedFn
+  |     +-- registerAuthHandler({ socket, handshake, clientId })
+  |           +-- socket.on('authenticate', ...)
+  |                 |-- state -> AUTHENTICATING
+  |                 |-- authenticateFn(handshake)
+  |                 |-- true  -> onClientAuthenticated({ socket })
+  |                 +-- false or throw -> emit 'unauthenticated', disconnect
   |
-  |-- send({ destination?, payload, doLog?, cb? })
-  |     +-- emitter.compress(true).to(destination).emit(topic, data)
+  |-- onClientAuthenticated({ socket })
+  |     |-- state -> AUTHENTICATED, clear authenticateTimeout
+  |     |-- ping({ socket, doIgnoreAuth: true })       # immediate first ping
+  |     |-- Join all defaultRooms
+  |     |-- registerRoomHandlers({ socket, clientId })  # 'join' / 'leave'
+  |     |-- interval = setInterval(ping, pingInterval)
+  |     |-- send 'authenticated' to socket.id
+  |     +-- invokeHook(clientConnectedFn)
   |
-  +-- shutdown()
-        |-- Disconnect all clients
-        |-- io.close()
-        +-- Quit Redis clients (pub, sub, emitter)
+  |-- send({ destination?, payload, doLog?, callback? })
+  |     +-- emitter.compress(true).to(destination)?.emit(topic, data)
+  |
+  +-- shutdown()  [async]
+        |-- Disconnect all tracked clients (clears their timers)
+        |-- close()                            # io.close()
+        +-- Promise.all([redisPub.quit(), redisSub.quit(), redisEmitter.quit()])
 
 
 SocketIOClientHelper (extends BaseHelper)
   |
   |-- constructor -> configure()
-  |     |-- io(host, options)
-  |     |-- Register 'connect' handler
-  |     |-- Register 'disconnect' handler
-  |     |-- Register 'connect_error' handler
-  |     |-- Register 'authenticated' handler
-  |     |-- Register 'unauthenticated' handler
-  |     +-- Register 'ping' handler
+  |     |-- client = io(host, options)
+  |     |-- Register 'connect'          -> onConnected
+  |     |-- Register 'disconnect'       -> state UNAUTHORIZED, onDisconnected
+  |     |-- Register 'connect_error'    -> onError
+  |     |-- Register 'authenticated'    -> state AUTHENTICATED, onAuthenticated
+  |     |-- Register 'unauthenticated'  -> state UNAUTHORIZED, onUnauthenticated
+  |     +-- Register 'ping'             -> debug log
   |
-  |-- authenticate()
-  |     +-- client.emit('authenticate')
-  |
-  |-- subscribe({ event, handler, ignoreDuplicate? })
-  |-- emit({ topic, data, doLog?, cb? })
-  |-- joinRooms({ rooms }) -> client.emit('join', { rooms })
+  |-- authenticate()  -> state AUTHENTICATING, client.emit('authenticate')
+  |-- subscribe({ event, handler, ignoreDuplicate? })   # wraps handler, tracked in wrappedHandlers
+  |-- emit({ topic, data, doLog?, callback? })
+  |-- joinRooms({ rooms })  -> client.emit('join', { rooms })
   |-- leaveRooms({ rooms }) -> client.emit('leave', { rooms })
   |
   +-- shutdown()
         |-- client.removeAllListeners()
-        |-- client.disconnect()
+        |-- disconnect() if connected
         +-- state -> UNAUTHORIZED
 ```
 
@@ -66,25 +105,35 @@ SocketIOClientHelper (extends BaseHelper)
 
 ### `SocketIOServerHelper`
 
-Extends `BaseHelper`. Manages a Socket.IO server with Redis adapter, authentication, room management, and heartbeat pings.
+Extends `BaseHelper`. Manages a `socket.io` server with a Redis adapter, authentication, room management, and heartbeat pings.
 
 #### `constructor(opts: TSocketIOServerOptions)`
 
-Creates the server helper. Validates the runtime-specific server/engine and initializes three Redis client connections by duplicating the provided `redisConnection`.
+Validates the runtime-specific `server` (Node) or `engine` (Bun) field. Duplicates the provided `redisConnection` into three independent clients (`redisPub`, `redisSub`, `redisEmitter`). Does **not** start the IO server - call `configure()` to complete initialization.
+
+**Throws:**
 
-Does **not** start the IO server -- call `configure()` to complete initialization.
+| Message | Condition |
+|---------|-----------|
+| `[SocketIOServerHelper] Invalid HTTP server for Node.js runtime!` | `runtime: 'node'` and `server` is falsy |
+| `[SocketIOServerHelper] Invalid @socket.io/bun-engine instance for Bun runtime!` | `runtime: 'bun'` and `engine` is falsy |
+| `[SocketIOServerHelper] Unsupported runtime!` | `runtime` is neither `'node'` nor `'bun'` |
+| `Invalid redis connection to config socket.io adapter!` | `redisConnection` is falsy |
 
 #### `configure(): Promise<void>`
 
-Initializes the Socket.IO server and sets up Redis infrastructure:
+1. Registers `error` listeners on all three duplicated Redis clients (logged, not thrown)
+2. Kicks off `connect()` on any client still in `'wait'` status
+3. `await Promise.all([waitForRedisReady(redisPub), waitForRedisReady(redisSub), waitForRedisReady(redisEmitter)])`
+4. Creates the `IOServer` - `new IOServer(server, serverOptions)` for Node.js, or `new IOServer()` followed by `io.bind(engine)` for Bun
+5. Attaches the Redis adapter via `@socket.io/redis-adapter`
+6. Creates the Redis emitter via `@socket.io/redis-emitter`
+7. Registers the `'connection'` handler
 
-1. Ensures all three Redis clients (pub, sub, emitter) are connected and ready
-2. Creates the `IOServer` based on runtime (`new IOServer(httpServer, serverOptions)` for Node.js, or `new IOServer()` with `io.bind(engine)` for Bun)
-3. Attaches the Redis adapter via `@socket.io/redis-adapter`
-4. Creates a Redis emitter via `@socket.io/redis-emitter`
-5. Registers the `'connection'` event handler
+Must be called before `on()`, `send()`, or any server operation.
 
-Must be called before `on()`, `send()`, or any server operations.
+> [!NOTE]
+> `waitForRedisReady` rejects after **30 seconds** if a client never reaches `ready` (or immediately on that client's `error` event). A broken Redis connection fails `configure()` instead of hanging boot indefinitely.
 
 #### `getIOServer(): IOServer`
 
@@ -92,144 +141,153 @@ Returns the underlying `socket.io` `Server` instance for direct access.
 
 ```typescript
 const io = socketServer.getIOServer();
-io.of('/admin').on('connection', (socket) => { /* ... */ });
+io.of('/admin').on('connection', socket => {
+  /* ... */
+});
 ```
 
 #### `getEngine(): any`
 
-Returns the Bun engine instance. Throws if the runtime is not `'bun'`.
+Returns the Bun engine instance.
 
-```typescript
-// Error: '[getEngine] Engine is only available for Bun runtime!'
-```
+**Throws:** `'[getEngine] Engine is only available for Bun runtime!'` - `runtime` is not `'bun'`
 
 #### `getClients(opts?: { id?: string }): ISocketIOClient | Map<string, ISocketIOClient> | undefined`
 
-Returns client information.
+Without `id`, returns the full `Map<string, ISocketIOClient>`. With `{ id }`, returns that client's entry or `undefined`.
 
 ```typescript
-// Get all clients
 const allClients = socketServer.getClients() as Map<string, ISocketIOClient>;
-
-// Get a specific client by socket ID
 const client = socketServer.getClients({ id: 'socket-id' }) as ISocketIOClient | undefined;
 ```
 
-#### `on<HandlerArgsType, HandlerReturnType>(opts: { topic: string; handler: (...args: HandlerArgsType) => ValueOrPromise<HandlerReturnType> }): void`
+#### `on<HandlerArgsType extends unknown[] = unknown[], HandlerReturnType = void>(opts: { topic: string; handler: (...args: HandlerArgsType) => ValueOrPromise<HandlerReturnType> }): void`
 
-Registers an event handler on the IO server instance.
+Registers an event handler directly on the IO server instance (`io.on(topic, handler)`).
 
 ```typescript
 socketServer.on({
   topic: 'custom-event',
-  handler: (data: { userId: string }) => {
-    console.log('Received:', data);
-  },
+  handler: (data: { userId: string }) => console.log('received:', data),
 });
 ```
 
 **Throws:**
-- `'[on] Invalid topic to start binding handler'` -- if `topic` is empty/falsy
-- `'[on] Invalid event handler | topic: {topic}'` -- if `handler` is missing
-- `'[on] IOServer is not initialized yet!'` -- if called before `configure()`
+
+| Message | Condition |
+|---------|-----------|
+| `[on] Invalid topic to start binding handler` | `topic` is empty/falsy |
+| `[on] Invalid event handler \| topic: {topic}` | `handler` is missing |
+| `[on] IOServer is not initialized yet!` | called before `configure()` completes |
 
 #### `onClientConnect(opts: { socket: IOSocket }): void`
 
-Handles a new socket connection. Called automatically by the `'connection'` event. Can also be called manually.
+Handles a new socket connection. Invoked automatically by the `'connection'` event, but can also be called manually.
 
 1. Creates an `ISocketIOClient` entry with state `UNAUTHORIZED`
 2. Starts the `authenticateTimeout` timer
 3. Registers `'disconnect'` and `'authenticate'` handlers on the socket
 
-Returns early (no-op) if `socket` is falsy or the client ID already exists.
+No-op if `socket` is falsy or the client ID already exists in the registry.
 
 #### `onClientAuthenticated(opts: { socket: IOSocket }): void`
 
-Called after successful authentication. Can also be called manually to programmatically authenticate a client.
+Runs after successful authentication. Can also be called manually to authenticate a client programmatically.
 
-1. Sets client state to `AUTHENTICATED`
-2. Sends an initial ping
-3. Joins all `defaultRooms`
-4. Registers room handlers (`join`, `leave`)
-5. Starts the periodic ping interval
-6. Emits `'authenticated'` event to the client with `{ id, time }`
-7. Invokes `clientConnectedFn` callback (errors caught and logged)
+1. Sets state to `AUTHENTICATED`
+2. Clears and unsets the `authenticateTimeout` timer
+3. Sends an immediate ping (`doIgnoreAuth: true`)
+4. Joins all `defaultRooms`
+5. Registers room handlers (`'join'`, `'leave'`)
+6. Starts the periodic ping `interval`
+7. Emits `'authenticated'` to the client with `{ id, time }`
+8. Invokes `clientConnectedFn` - errors are caught and logged, never surfaced to the caller
+
+If the client entry no longer exists (disconnected mid-flow), logs and calls `disconnect({ socket })` instead.
 
 #### `ping(opts: { socket: IOSocket; doIgnoreAuth: boolean }): void`
 
-Sends a `'ping'` event to the client with `{ time: ISO string }`.
+Emits `'ping'` to the client with `{ time: ISO string }`.
 
-- If `doIgnoreAuth` is `false` and the client is not in `AUTHENTICATED` state, the client is disconnected
-- If the socket or client is not found, returns silently
+- If `doIgnoreAuth` is `false` and the client is not `AUTHENTICATED`, the client is disconnected instead of pinged
+- No-op if the socket or the tracked client is not found
 
 #### `disconnect(opts: { socket: IOSocket }): void`
 
-Disconnects a client and cleans up internal state:
-
 1. Clears the ping `interval` timer
 2. Clears the `authenticateTimeout` timer
-3. Removes the client from the `clients` map
+3. Removes the client from the registry
 4. Calls `socket.disconnect()`
 
-#### `send(opts: { destination?: string; payload: { topic: string; data: any }; doLog?: boolean; cb?: () => void }): void`
+No-op if `socket` is falsy.
+
+#### `send(opts: { destination?: string; payload: { topic: string; data: any }; doLog?: boolean; callback?: () => void }): void`
 
-Emits a message via the Redis emitter with compression enabled.
+Emits through the Redis emitter with compression enabled (`emitter.compress(true)`), reaching clients on **any** server instance.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `destination` | `string \| undefined` | Socket ID or room name. If omitted, broadcasts to all |
+| `destination` | `string \| undefined` | Socket ID or room name. Omit to broadcast to all clients |
 | `payload.topic` | `string` | Event name |
 | `payload.data` | `any` | Event payload |
-| `doLog` | `boolean` | If `true`, logs the message details. Default: `false` |
-| `cb` | `() => void` | Callback invoked asynchronously via `setImmediate` after emission |
+| `doLog` | `boolean` | Logs the message details. Default: `false` |
+| `callback` | `() => void` | Invoked via `setImmediate` after the emit call returns |
 
-Returns early (no-op) if `payload`, `topic`, or `data` is falsy.
+No-op if `payload`, `payload.topic`, or `payload.data` is falsy. Logs an error and returns if called before `configure()` (the Redis emitter does not exist yet).
 
-#### `shutdown(): Promise<void>`
+```typescript
+socketServer.send({
+  destination: 'some-room',
+  payload: { topic: 'update', data: { value: 42 } },
+  callback: () => console.log('queued'),
+});
+```
 
-Gracefully shuts down the server:
+#### `shutdown(): Promise<void>`
 
-1. Disconnects all tracked clients (clears their intervals and timeouts)
+1. Disconnects every tracked client, clearing its `interval` and `authenticateTimeout`
 2. Clears the `clients` map
-3. Closes the IO server
-4. Quits all three Redis connections (pub, sub, emitter)
+3. Closes the IO server (no-op if `configure()` never ran)
+4. `await Promise.all([redisPub.quit(), redisSub.quit(), redisEmitter.quit()])` - runs even if closing the IO server rejects, so the three Redis sockets never leak
 
 ## Client API
 
 ### `SocketIOClientHelper`
 
-Extends `BaseHelper`. Manages a Socket.IO client connection with authentication, event subscriptions, and room operations.
+Extends `BaseHelper`. Manages a `socket.io-client` connection with authentication, event subscriptions, and room operations.
 
 #### `constructor(opts: ISocketIOClientOptions)`
 
-Creates and immediately configures the client. The constructor calls `configure()` internally, which establishes the connection and registers lifecycle event handlers.
+Stores the callbacks and calls `configure()` internally. The client starts connecting immediately.
 
 #### `configure(): void`
 
-Initializes the `socket.io-client` connection and registers internal event handlers. Called automatically by the constructor. If called again when a client already exists, returns early (no-op).
+Creates the `socket.io-client` connection (`io(host, options)`) and registers the internal lifecycle handlers below. Called automatically by the constructor. A second call is a no-op if a client instance already exists.
+
+| Event | Behavior |
+|-------|----------|
+| `'connect'` | Invokes `onConnected` |
+| `'disconnect'` | State -> `UNAUTHORIZED`, invokes `onDisconnected(reason)` |
+| `'connect_error'` | Invokes `onError(error)` |
+| `'authenticated'` | State -> `AUTHENTICATED`, invokes `onAuthenticated` |
+| `'unauthenticated'` | State -> `UNAUTHORIZED`, invokes `onUnauthenticated(message)` |
+| `'ping'` | Logs a debug message only |
 
-Registered handlers:
-- `'connect'` -- invokes `onConnected` callback
-- `'disconnect'` -- resets state to `UNAUTHORIZED`, invokes `onDisconnected` callback
-- `'connect_error'` -- invokes `onError` callback
-- `'authenticated'` -- sets state to `AUTHENTICATED`, invokes `onAuthenticated` callback
-- `'unauthenticated'` -- resets state to `UNAUTHORIZED`, invokes `onUnauthenticated` callback
-- `'ping'` -- logs debug message
+Every callback invocation is wrapped so a rejected promise is caught and logged, never thrown.
 
 #### `getState(): TSocketIOClientState`
 
-Returns the current authentication state: `'unauthorized'`, `'authenticating'`, or `'authenticated'`.
+Returns `'unauthorized'`, `'authenticating'`, or `'authenticated'`.
 
 ```typescript
-const state = client.getState();
-if (state === 'authenticated') {
+if (client.getState() === 'authenticated') {
   client.emit({ topic: 'message', data: { text: 'hello' } });
 }
 ```
 
 #### `getSocketClient(): Socket`
 
-Returns the underlying `socket.io-client` `Socket` instance for direct access.
+Returns the underlying `socket.io-client` `Socket` instance.
 
 ```typescript
 const rawSocket = client.getSocketClient();
@@ -238,143 +296,177 @@ rawSocket.io.opts.reconnection = false;
 
 #### `authenticate(): void`
 
-Initiates the authentication handshake by emitting the `'authenticate'` event to the server.
+Emits `'authenticate'` to the server to start the handshake.
 
-- Does nothing if the client is not connected
-- Does nothing if the current state is not `'unauthorized'`
+- No-op if the client is not connected
+- No-op if the current state is not `'unauthorized'`
 - Sets state to `AUTHENTICATING` before emitting
 
 ```typescript
-// Typically called inside the onConnected callback
 const client = new SocketIOClientHelper({
   // ...
-  onConnected: () => {
-    client.authenticate();
-  },
+  onConnected: () => client.authenticate(),
 });
 ```
 
 #### `subscribe<T>(opts: { event: string; handler: TSocketIOEventHandler<T>; ignoreDuplicate?: boolean }): void`
 
-Registers an event handler on the client socket. The handler is automatically wrapped with error handling (catches both sync throws and async rejections).
+Registers a handler on the client socket. The handler is wrapped with error handling that catches both sync throws and async rejections. That wrapper is tracked in an internal `wrappedHandlers` map, so `unsubscribe()` can find and remove it.
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `event` | `string` | -- | Event name to listen for |
-| `handler` | `TSocketIOEventHandler<T>` | -- | Callback receiving the event data |
-| `ignoreDuplicate` | `boolean` | `true` | If `true` and a handler already exists for this event, skips registration |
+| `event` | `string` | - | Event name to listen for |
+| `handler` | `TSocketIOEventHandler<T>` | - | Callback receiving the event data |
+| `ignoreDuplicate` | `boolean` | `true` | Skip registration if a handler already exists for this event |
 
 #### `subscribeMany(opts: { events: Record<string, TSocketIOEventHandler>; ignoreDuplicate?: boolean }): void`
 
-Batch-registers multiple event handlers. Calls `subscribe()` for each entry.
+Calls `subscribe()` for each entry in `events`.
 
 ```typescript
 client.subscribeMany({
   events: {
-    'event-a': (data) => { /* ... */ },
-    'event-b': (data) => { /* ... */ },
+    'user-joined': data => console.log('joined:', data),
+    'user-left': data => console.log('left:', data),
   },
-  ignoreDuplicate: false,
 });
 ```
 
 #### `unsubscribe(opts: { event: string; handler?: TSocketIOEventHandler }): void`
 
-Removes event handlers from the client socket.
-
-- If `handler` is provided, removes only that specific handler
-- If `handler` is omitted, removes **all** handlers for the event
-- If no listeners exist for the event, returns early (no-op)
+- With `handler`, removes only that specific handler (looked up in `wrappedHandlers`). No-op if that handler was not registered through this helper
+- Without `handler`, removes **all** handlers for the event
+- No-op if the event has no listeners
 
 #### `unsubscribeMany(opts: { events: string[] }): void`
 
-Batch-unsubscribes from multiple events. Removes all handlers for each event.
-
-```typescript
-client.unsubscribeMany({ events: ['event-a', 'event-b'] });
-```
+Calls `unsubscribe()` for each event, removing all handlers for each.
 
 #### `connect(): void`
 
-Manually connects the client socket. Useful after a manual `disconnect()`.
-
-Returns early if the client instance does not exist.
+Manually reconnects the client socket. No-op if the client instance does not exist (i.e. `configure()` never ran).
 
 #### `disconnect(): void`
 
-Manually disconnects the client socket without cleaning up listeners or resetting state.
-
-Returns early if the client instance does not exist.
+Manually disconnects the client socket without removing listeners or resetting state. No-op if the client instance does not exist.
 
 > [!TIP]
-> Use `shutdown()` instead of `disconnect()` for a full cleanup that also removes listeners and resets the authentication state.
+> Use `shutdown()` for a full cleanup that also removes listeners and resets the authentication state.
 
-#### `emit<T>(opts: { topic: string; data: T; doLog?: boolean; cb?: () => void }): void`
+#### `emit<T>(opts: { topic: string; data: T; doLog?: boolean; callback?: () => void }): void`
 
 Emits an event to the server.
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `topic` | `string` | -- | Event name |
-| `data` | `T` | -- | Event payload |
-| `doLog` | `boolean` | `false` | If `true`, logs the emission details |
-| `cb` | `() => void` | `undefined` | Callback invoked asynchronously via `setImmediate` |
+| `topic` | `string` | - | Event name |
+| `data` | `T` | - | Event payload |
+| `doLog` | `boolean` | `false` | Logs the emission details |
+| `callback` | `() => void` | `undefined` | Invoked via `setImmediate` after the emit call |
 
-**Throws:**
-- `'Invalid socket client state to emit'` (status 400) -- if the client is not connected
-- `'Topic is required to emit'` (status 400) -- if `topic` is empty/falsy
+**Throws** (both status `400`):
 
-#### `joinRooms(opts: { rooms: string[] }): void`
+| Message | Condition |
+|---------|-----------|
+| `Invalid socket client state to emit` | the client is not connected |
+| `Topic is required to emit` | `topic` is empty/falsy |
 
-Requests to join rooms by emitting a `'join'` event to the server with `{ rooms }`. The server validates the request through its `validateRoomFn`.
+#### `joinRooms(opts: { rooms: string[] }): void`
 
-Logs a warning and returns early if the client is not connected.
+Emits `'join'` with `{ rooms }`. The server validates the request through its `validateRoomFn`. Logs a warning and no-ops if the client is not connected.
 
 #### `leaveRooms(opts: { rooms: string[] }): void`
 
-Requests to leave rooms by emitting a `'leave'` event to the server with `{ rooms }`.
+Emits `'leave'` with `{ rooms }`. Logs a warning and no-ops if the client is not connected.
 
-Logs a warning and returns early if the client is not connected.
+> [!NOTE]
+> Unlike `joinRooms()`, leave requests are **not** validated server-side. The client can request to leave any room name, including ones it never joined. `socket.leave()` on a room the socket isn't in is a no-op.
 
 #### `shutdown(): void`
 
-Fully shuts down the client:
-
 1. Removes all event listeners (`removeAllListeners()`)
 2. Disconnects if currently connected
 3. Resets state to `UNAUTHORIZED`
 
+## Authentication Protocol
+
+```
+Client connects (transport only)
+  |
+  v
+Server creates client entry (state: UNAUTHORIZED)
+  |-- Starts authenticateTimeout timer (default: 10s)
+  |-- Registers 'disconnect' handler
+  |
+Client emits 'authenticate'
+  |
+  v
+State -> AUTHENTICATING
+Server calls authenticateFn(handshake)
+  |
+  +-- Resolves true:
+  |     |-- State -> AUTHENTICATED, authenticateTimeout cleared
+  |     |-- Immediate ping, join defaultRooms, start ping interval
+  |     |-- Emit 'authenticated' { id, time } to client
+  |     +-- Invoke clientConnectedFn (errors caught and logged)
+  |
+  +-- Resolves false:
+  |     |-- State -> UNAUTHORIZED
+  |     |-- Emit 'unauthenticated' { message: 'Invalid token to authenticate! Please login again!', time }
+  |     +-- Disconnect (via the emit callback)
+  |
+  +-- Throws / rejects:
+  |     |-- State -> UNAUTHORIZED
+  |     |-- Emit 'unauthenticated' { message: 'Failed to authenticate connection! Please login again!', time }
+  |     +-- Disconnect (via the emit callback), logged with doLog: true
+  |
+  +-- authenticateTimeout elapses first:
+        +-- Disconnect - including a client whose authenticateFn is still pending;
+            its eventual resolution finds the client already removed and is a no-op
+```
+
+A client that re-emits `'authenticate'` while already `AUTHENTICATING` or `AUTHENTICATED` is ignored (logged as a warning, `authenticateFn` is not called again).
+
+## Redis Adapter
+
+The server uses `@socket.io/redis-adapter` and `@socket.io/redis-emitter` for horizontal scaling. Three Redis connections are created by duplicating the provided `redisConnection`:
+
+| Client | Purpose |
+|--------|---------|
+| `redisPub` | Publishes adapter messages (room membership, cross-instance socket.io internals) |
+| `redisSub` | Subscribes to adapter messages |
+| `redisEmitter` | Powers `send()` for cross-instance message delivery |
+
+- **Initialized during `configure()`.** All three clients are created and awaited before the IO server starts.
+- **Lazy connect handled explicitly.** Duplicated clients inherit `lazyConnect` but never dial on their own. If the parent `redisConnection` uses `lazyConnect` (`autoConnect: false`), `configure()` kicks each duplicated client into `connect()` explicitly.
+
 ## Types Reference
 
 ### `IHandshake`
 
-Represents the client handshake data available during authentication.
-
 ```typescript
 interface IHandshake {
-  headers: IncomingHttpHeaders;   // HTTP headers from the initial request
-  time: string;                   // Connection time as ISO string
-  address: string;                // Client IP address
-  xdomain: boolean;              // Whether the connection is cross-domain
-  secure: boolean;                // Whether the connection uses TLS
-  issued: number;                 // Timestamp when the handshake was issued
-  url: string;                    // Request URL
-  query: ParsedUrlQuery;          // Parsed query string parameters
-  auth: { [key: string]: any };  // Authentication payload sent by the client
+  headers: IncomingHttpHeaders;
+  time: string;
+  address: string;
+  xdomain: boolean;
+  secure: boolean;
+  issued: number;
+  url: string;
+  query: ParsedUrlQuery;
+  auth: { [key: string]: any };
 }
 ```
 
 ### `ISocketIOClient`
 
-Internal representation of a connected client tracked by the server.
-
 ```typescript
 interface ISocketIOClient {
-  id: string;                          // Socket ID
-  socket: IOSocket;                    // The socket.io Socket instance
-  state: TSocketIOClientState;         // 'unauthorized' | 'authenticating' | 'authenticated'
-  interval?: NodeJS.Timeout;          // Ping interval timer (set after authentication)
-  authenticateTimeout: NodeJS.Timeout; // Auth timeout timer (cleared after authentication)
+  id: string;
+  socket: IOSocket;
+  state: TSocketIOClientState;
+  interval?: NodeJS.Timeout;           // Ping interval timer, set after authentication
+  authenticateTimeout?: NodeJS.Timeout; // Cleared (set to undefined) after authentication
 }
 ```
 
@@ -386,44 +478,31 @@ type TSocketIOClientState = 'unauthorized' | 'authenticating' | 'authenticated';
 
 ### `TSocketIOAuthenticateFn`
 
-Server-side authentication callback. Receives the handshake data and returns a boolean indicating whether to accept or reject the connection.
-
 ```typescript
 type TSocketIOAuthenticateFn = (args: IHandshake) => ValueOrPromise<boolean>;
 ```
 
 ### `TSocketIOValidateRoomFn`
 
-Server-side room validation callback. Receives the socket and requested rooms, returns the subset of rooms the client is allowed to join.
-
 ```typescript
-type TSocketIOValidateRoomFn = (opts: {
-  socket: IOSocket;
-  rooms: string[];
-}) => ValueOrPromise<string[]>;
+type TSocketIOValidateRoomFn = (opts: { socket: IOSocket; rooms: string[] }) => ValueOrPromise<string[]>;
 ```
 
 ### `TSocketIOClientConnectedFn`
 
-Server-side callback invoked after a client is fully authenticated and has joined default rooms.
-
 ```typescript
-type TSocketIOClientConnectedFn = (opts: {
-  socket: IOSocket;
-}) => ValueOrPromise<void>;
+type TSocketIOClientConnectedFn = (opts: { socket: IOSocket }) => ValueOrPromise<void>;
 ```
 
 ### `TSocketIOEventHandler<T>`
 
-Client-side event handler type.
-
 ```typescript
 type TSocketIOEventHandler<T = unknown> = (data: T) => ValueOrPromise<void>;
 ```
 
 ### `IOptions`
 
-Client connection options. Extends `SocketOptions` from `socket.io-client`.
+Client connection options. Extends `SocketOptions` from `socket.io-client`; `path` and `extraHeaders` are required by the type.
 
 ```typescript
 interface IOptions extends SocketOptions {
@@ -432,24 +511,53 @@ interface IOptions extends SocketOptions {
 }
 ```
 
+### `ISocketIOClientOptions`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `identifier` | `string` | - | Unique identifier for this client (used as logger scope) |
+| `host` | `string` | - | Server URL to connect to (e.g. `'http://localhost:3000'`) |
+| `options` | `IOptions` | - | Socket.IO client options |
+| `onConnected` | `() => ValueOrPromise<void>` | `undefined` | Called when the transport connection is established |
+| `onDisconnected` | `(reason: string) => ValueOrPromise<void>` | `undefined` | Called on disconnect; state resets to `'unauthorized'` first |
+| `onError` | `(error: Error) => ValueOrPromise<void>` | `undefined` | Called on `'connect_error'` |
+| `onAuthenticated` | `() => ValueOrPromise<void>` | `undefined` | Called when the server confirms authentication |
+| `onUnauthenticated` | `(message: string) => ValueOrPromise<void>` | `undefined` | Called when the server rejects authentication |
+
 ### `TSocketIOServerOptions`
 
-Discriminated union for server constructor options:
+Discriminated union on `runtime`.
 
 ```typescript
 type TSocketIOServerOptions = ISocketIOServerNodeOptions | ISocketIOServerBunOptions;
 
+interface ISocketIOServerBaseOptions {
+  identifier: string;
+  serverOptions: Partial<ServerOptions>;   // socket.io ServerOptions - required by the type, pass {} if unused
+  redisConnection: IRedisHelper;
+  defaultRooms?: string[];                 // Default: ['io-default', 'io-notification']
+  authenticateTimeout?: number;            // Default: 10000 (10s)
+  pingInterval?: number;                   // Default: 30000 (30s)
+
+  authenticateFn: TSocketIOAuthenticateFn;
+  validateRoomFn?: TSocketIOValidateRoomFn;
+  clientConnectedFn?: TSocketIOClientConnectedFn;
+}
+
 interface ISocketIOServerNodeOptions extends ISocketIOServerBaseOptions {
   runtime: 'node';
-  server: HTTPServer;
+  server: HTTPServer; // node:http Server
 }
 
 interface ISocketIOServerBunOptions extends ISocketIOServerBaseOptions {
   runtime: 'bun';
-  engine: any;
+  engine: any; // @socket.io/bun-engine Server instance - typed `any` since it's an optional peer dep
 }
 ```
 
+> [!WARNING]
+> If no `validateRoomFn` is provided, **all** custom room join requests are rejected with a warning log. Clients still get `defaultRooms` automatically.
+
 ## Constants
 
 ### `SocketIOConstants`
@@ -458,12 +566,12 @@ interface ISocketIOServerBunOptions extends ISocketIOServerBaseOptions {
 |----------|-------|-------------|
 | `EVENT_PING` | `'ping'` | Heartbeat event emitted by the server at `pingInterval` |
 | `EVENT_CONNECT` | `'connection'` | Server-side connection event |
-| `EVENT_DISCONNECT` | `'disconnect'` | Disconnect event (both server and client) |
+| `EVENT_DISCONNECT` | `'disconnect'` | Disconnect event (server and client) |
 | `EVENT_JOIN` | `'join'` | Room join request event |
 | `EVENT_LEAVE` | `'leave'` | Room leave request event |
-| `EVENT_AUTHENTICATE` | `'authenticate'` | Client-to-server authentication request |
-| `EVENT_AUTHENTICATED` | `'authenticated'` | Server-to-client authentication success |
-| `EVENT_UNAUTHENTICATE` | `'unauthenticated'` | Server-to-client authentication failure |
+| `EVENT_AUTHENTICATE` | `'authenticate'` | Client -> server authentication request |
+| `EVENT_AUTHENTICATED` | `'authenticated'` | Server -> client authentication success |
+| `EVENT_UNAUTHENTICATE` | `'unauthenticated'` | Server -> client authentication failure |
 | `ROOM_DEFAULT` | `'io-default'` | Default room name |
 | `ROOM_NOTIFICATION` | `'io-notification'` | Default notification room name |
 
@@ -475,23 +583,36 @@ interface ISocketIOServerBunOptions extends ISocketIOServerBaseOptions {
 | `AUTHENTICATING` | `'authenticating'` | Authentication in progress |
 | `AUTHENTICATED` | `'authenticated'` | Successfully authenticated |
 
-#### `SocketIOClientStates.isValid(input: string): boolean`
-
-Static method that checks whether a string is a valid client state value.
+`SocketIOClientStates.isValid(input: string): input is TConstValue<typeof SocketIOClientStates>` - checks membership against the backing `SCHEME_SET`.
 
 ```typescript
 SocketIOClientStates.isValid('authenticated'); // true
 SocketIOClientStates.isValid('invalid');       // false
 ```
 
-### Internal Defaults
+### Internal defaults
 
 | Constant | Value | Description |
 |----------|-------|-------------|
-| `CLIENT_AUTHENTICATE_TIMEOUT` | `10000` (10 s) | Default timeout before disconnecting unauthenticated clients |
-| `CLIENT_PING_INTERVAL` | `30000` (30 s) | Default interval between heartbeat pings |
-
-## See Also
-
-- [Setup & Usage](./) -- Getting started, constructor options, and examples
-- [WebSocket Helper](../websocket/) -- Bun-native WebSocket alternative
+| `CLIENT_AUTHENTICATE_TIMEOUT` | `10_000` (10s) | Default `authenticateTimeout` |
+| `CLIENT_PING_INTERVAL` | `30_000` (30s) | Default `pingInterval` |
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `[SocketIOServerHelper] Invalid HTTP server for Node.js runtime!` | `server` missing/falsy with `runtime: 'node'` | Pass a valid `http.Server` instance |
+| `[SocketIOServerHelper] Invalid @socket.io/bun-engine instance for Bun runtime!` | `engine` missing/falsy with `runtime: 'bun'` | Pass a valid `@socket.io/bun-engine` `Server` instance |
+| `[SocketIOServerHelper] Unsupported runtime!` | `runtime` is neither `'node'` nor `'bun'` | Use `RuntimeModules.NODE`, `RuntimeModules.BUN`, or `RuntimeModules.detect()` |
+| `Invalid redis connection to config socket.io adapter!` | `redisConnection` missing, `null`, or `undefined` | Pass a valid `IRedisHelper` (e.g. `RedisSingleHelper`, `RedisClusterHelper`) |
+| `[on] Invalid topic to start binding handler` | Empty/falsy `topic` passed to `on()` | Provide a non-empty string topic |
+| `[on] IOServer is not initialized yet!` | `on()` called before `configure()` completed | `await configure()` before registering handlers |
+| `Invalid socket client state to emit` (client) | `emit()` called while not connected | Check `getState()` / connection status, or emit inside `onConnected` |
+| `Topic is required to emit` (client) | `emit()` called with an empty/falsy `topic` | Provide a non-empty string topic |
+
+## See also
+
+- [Socket.IO overview](/extensions/helpers/socket-io/) - getting started, constructor options, and common tasks
+- [Socket.IO Component](/extensions/components/socket-io/) - DI-managed lifecycle wrapper around this helper
+- [WebSocket Helper](../websocket/) - Bun-native alternative with no `socket.io` dependency
+- [Redis Helper](/extensions/helpers/redis/reference) - `duplicateClient()` and the topology classes used as `redisConnection`