# Socket.IO -- API Reference

> 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
  +-----------------------------------+
```

### 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

#### Bun Runtime

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`:

#### 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();

  return socketIOHelper;
}
```

## Server Helper API Reference

### `SocketIOServerHelper` Constructor

The helper uses a **discriminated union** for its constructor options, keyed on `runtime`:

#### `TSocketIOServerOptions` Type
```typescript
interface ISocketIOServerBaseOptions {
  identifier: string;
  serverOptions: Partial<ServerOptions>;
  redisConnection: DefaultRedisHelper;
  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;
}

interface ISocketIOServerNodeOptions extends ISocketIOServerBaseOptions {
  runtime: typeof RuntimeModules.NODE;
  server: HTTPServer;                     // node:http.Server instance
}

interface ISocketIOServerBunOptions extends ISocketIOServerBaseOptions {
  runtime: typeof RuntimeModules.BUN;
  engine: any;                            // @socket.io/bun-engine Server instance
}

type TSocketIOServerOptions = ISocketIOServerNodeOptions | ISocketIOServerBunOptions;
```

During construction:

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

> [!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 `RedisHelper` connection is not consumed.

### `configure()` -- Server Initialization

The `configure()` method is the main initialization entry point, called after construction:

```
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)
```

> [!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.

### Public Methods

#### `getIOServer()`

```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
```

Returns the `@socket.io/bun-engine` instance. **Throws** if the runtime is Node.js (`"Engine is only available for Bun runtime!"`).

#### `getClients()`

```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()`

```typescript
on<HandlerArgsType extends unknown[] = unknown[], HandlerReturnType = void>(opts: {
  topic: string;
  handler: (...args: HandlerArgsType) => ValueOrPromise<HandlerReturnType>;
}): void
```

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.

#### `ping()`

```typescript
ping(opts: { socket: IOSocket; doIgnoreAuth: boolean }): void
```

Sends a `ping` event to a specific client with `{ time: <ISO string> }`. Behavior:

- 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

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.

#### `disconnect()`

```typescript
disconnect(opts: { socket: IOSocket }): void
```

Disconnects a specific client and cleans up resources:

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

If the socket is `undefined` or not tracked in the client map, the method still calls `socket.disconnect()` for safety.

#### `onClientConnect()`

```typescript
onClientConnect(opts: { socket: IOSocket }): void
```

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.

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()`

#### `onClientAuthenticated()`

```typescript
onClientAuthenticated(opts: { socket: IOSocket }): void
```

Called after successful authentication. This method is public so it can be invoked externally for testing or custom auth flows.

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)

### Messaging via `send()`

The `send()` method uses the Redis emitter for message delivery, enabling cross-instance broadcasting:

```typescript
send(opts: {
  destination?: string;    // Socket ID, room name, or omit for broadcast
  payload: {
    topic: string;         // Event name
    data: any;             // Event payload
  };
  doLog?: boolean;         // Log the emission (default: false)
  cb?: () => void;         // Callback 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

The `send()` method silently returns (no error, no log) in these cases:
- `payload` is falsy
- `payload.topic` is falsy
- `payload.data` is falsy

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.

> [!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.

### Shutdown

```typescript
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`)

## 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.

### Constructor

```typescript
constructor(opts: ISocketIOClientOptions)
```

#### `ISocketIOClientOptions` Interface

```typescript
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>;
  onAuthenticated?: () => ValueOrPromise<void>;
  onUnauthenticated?: (message: string) => ValueOrPromise<void>;
}
```

#### `IOptions` Interface

```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()`

```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`).

### `authenticate()`

```typescript
authenticate(): void
```

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`.

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)

On call:
1. Sets state to `authenticating`
2. Emits `SocketIOConstants.EVENT_AUTHENTICATE` (value: `'authenticate'`)

### `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:

```typescript
const wrappedHandler = (data: T) => {
  try {
    Promise.resolve(handler(data)).catch(error => {
      logger.error('Handler error | event: %s | error: %s', event, error);
    });
  } catch (error) {
    logger.error('Handler error | event: %s | error: %s', event, error);
  }
};
```

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>;
```

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
```

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`

## Internals

### `resolveBindings()`

Reads all binding keys from the DI container and validates required ones:

| Binding | Validation | Error on Failure |
|---------|-----------|------------------|
| `SERVER_OPTIONS` | Optional, merged with defaults via `Object.assign()` | -- |
| `REDIS_CONNECTION` | Must be `instanceof DefaultRedisHelper` | `"Invalid instance of redisConnection | Please init connection with RedisHelper for single redis connection or RedisClusterHelper for redis cluster mode!"` |
| `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` | -- |

### `registerBunHook()`

Registers a post-start hook that:

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

### `createBunEngine()` Function

```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

```typescript
function createBunFetchHandler(opts: {
  engine: any;
  enginePath: string;
  honoServer: OpenAPIHono;
}): (req: Request, server: TBunServerInstance) => Response | Promise<Response>
```

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:

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`

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 `DefaultRedisHelper`:

```
RedisHelper (parent -- NOT consumed)
  |
  +-- client.duplicate() --> redisPub    (for Redis adapter -- publishes)
  |
  +-- client.duplicate() --> redisSub    (for Redis adapter -- subscribes)
  |
  +-- client.duplicate() --> redisEmitter (for @socket.io/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 `RedisHelper` connection remains independent and is not consumed -- it can be used for other purposes (e.g., caching, sessions)

**`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

The private `setRuntime()` method validates the constructor options based on the `runtime` discriminant:

| 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!"` |

### `initRedisClients()` -- Redis Initialization

```typescript
private initRedisClients(redisConnection: TSocketIOServerOptions['redisConnection']): void
```

**Throws** if `redisConnection` is falsy: `"Invalid redis connection to config socket.io adapter!"`

Creates 3 duplicated clients from the parent connection's underlying ioredis client.

### `initIOServer()` -- IO Server Initialization

Called during `configure()` after 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!"`

### Connection Lifecycle

When a client connects, the server manages a strict authentication flow:

```
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
```

#### Authentication Failure -- Two Code Paths

The `registerAuthHandler()` method handles authentication results through two distinct code paths:

**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)

**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

Both paths also handle the edge case where the client disconnected *during* authentication -- they check `this.clients.has(id)` before proceeding.

#### `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)
}
```

### Room Handlers

Room join/leave handlers are registered after successful authentication:

- **`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.

Both handlers parse the payload defensively: `const { rooms = [] } = payload || { rooms: [] }`. Empty `rooms` arrays are silently ignored.

Join handler validation errors are caught and logged but do not disconnect 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.

## 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: DefaultRedisHelper;
  defaultRooms?: string[];
  authenticateTimeout?: number;
  pingInterval?: number;
  authenticateFn: TSocketIOAuthenticateFn;
  validateRoomFn?: TSocketIOValidateRoomFn;
  clientConnectedFn?: TSocketIOClientConnectedFn;
}

// Node.js runtime variant
interface ISocketIOServerNodeOptions extends ISocketIOServerBaseOptions {
  runtime: typeof RuntimeModules.NODE;
  server: HTTPServer;
}

// Bun runtime variant
interface ISocketIOServerBunOptions extends ISocketIOServerBaseOptions {
  runtime: typeof RuntimeModules.BUN;
  engine: any;
}

// Tracked client entry (server-side)
interface ISocketIOClient {
  id: string;
  socket: IOSocket;
  state: TSocketIOClientState;
  interval?: NodeJS.Timeout;
  authenticateTimeout: NodeJS.Timeout;
}

// Redis client type alias
type TRedisClient = Redis | Cluster;
```

### Client Types

```typescript
// Client constructor options
interface ISocketIOClientOptions {
  identifier: string;
  host: string;
  options: IOptions;
  onConnected?: () => ValueOrPromise<void>;
  onDisconnected?: (reason: string) => ValueOrPromise<void>;
  onError?: (error: Error) => ValueOrPromise<void>;
  onAuthenticated?: () => ValueOrPromise<void>;
  onUnauthenticated?: (message: string) => ValueOrPromise<void>;
}

// Socket connection options (extends socket.io-client's SocketOptions)
interface IOptions extends SocketOptions {
  path: string;
  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

```typescript
// Server authentication handler
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
interface IResolvedBindings {
  redisConnection: DefaultRedisHelper;
  authenticateFn: TSocketIOAuthenticateFn;
  validateRoomFn?: TSocketIOValidateRoomFn;
  clientConnectedFn?: TSocketIOClientConnectedFn;
}
```

## 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

- [Setup & Configuration](./) -- Quick reference, installation, bindings, constants
- [Usage & Examples](./usage) -- Server-side usage, client helper, advanced patterns
- [Error Reference](./errors) -- Error conditions and troubleshooting