# Socket.IO

Runtime-agnostic Socket.IO server and client helpers with built-in authentication flow, room management, Redis adapter for horizontal scaling, and automatic heartbeat keep-alive.

## Quick Reference

| Class | Extends | Role |
|-------|---------|------|
| `SocketIOServerHelper` | `BaseHelper` | Manages a Socket.IO server with authentication, rooms, ping intervals, and Redis-backed messaging |
| `SocketIOClientHelper` | `BaseHelper` | Manages a Socket.IO client connection with authentication, event subscriptions, and room operations |

#### Import Paths

```typescript
import {
  SocketIOServerHelper,
  SocketIOClientHelper,
  SocketIOConstants,
  SocketIOClientStates,
} from '@venizia/ignis-helpers';

import type {
  TSocketIOServerOptions,
  ISocketIOServerBaseOptions,
  ISocketIOServerNodeOptions,
  ISocketIOServerBunOptions,
  ISocketIOClientOptions,
  IOptions,
  ISocketIOClient,
  IHandshake,
  TSocketIOAuthenticateFn,
  TSocketIOValidateRoomFn,
  TSocketIOClientConnectedFn,
  TSocketIOEventHandler,
  TSocketIOClientState,
} from '@venizia/ignis-helpers';
```

## Creating an Instance

### Server

`SocketIOServerHelper` requires a Redis connection for the pub/sub adapter, an HTTP server (Node.js) or Bun engine instance, and an authentication function.

```typescript
import { SocketIOServerHelper } from '@venizia/ignis-helpers';
import { DefaultRedisHelper } from '@venizia/ignis-helpers';
import { createServer } from 'node:http';

const httpServer = createServer();

const redisHelper = new DefaultRedisHelper({
  name: 'socket-redis',
  host: 'localhost',
  port: 6379,
});

const socketServer = new SocketIOServerHelper({
  identifier: 'my-socket-server',
  runtime: 'node',
  server: httpServer,
  redisConnection: redisHelper,
  serverOptions: {
    cors: { origin: '*' },
    path: '/socket.io',
  },
  authenticateFn: async (handshake) => {
    const token = handshake.auth?.token;
    return !!token; // Return true to accept, false to reject
  },
  validateRoomFn: async ({ socket, rooms }) => {
    // Return only the rooms the client is allowed to join
    return rooms.filter(r => r.startsWith('public-'));
  },
  clientConnectedFn: async ({ socket }) => {
    console.log('Client authenticated:', socket.id);
  },
  defaultRooms: ['io-default', 'io-notification'],
  authenticateTimeout: 10000,
  pingInterval: 30000,
});
```

#### `TSocketIOServerOptions`

A discriminated union based on the `runtime` field:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `identifier` | `string` | -- | Unique identifier for this server instance (used as logger scope) |
| `runtime` | `'node' \| 'bun'` | -- | Runtime environment. Determines which server field is required |
| `server` | `HTTPServer` | -- | Node.js HTTP server instance. **Required when `runtime` is `'node'`** |
| `engine` | `any` | -- | `@socket.io/bun-engine` Server instance. **Required when `runtime` is `'bun'`** |
| `serverOptions` | `Partial<ServerOptions>` | `{}` | Socket.IO `ServerOptions` (cors, path, transports, etc.) |
| `redisConnection` | `DefaultRedisHelper` | -- | **Required.** Redis helper used to create pub, sub, and emitter clients |
| `authenticateFn` | `TSocketIOAuthenticateFn` | -- | **Required.** Called with the client's handshake data. Return `true` to accept, `false` to reject |
| `validateRoomFn` | `TSocketIOValidateRoomFn` | `undefined` | Called when a client requests to join rooms. Return the allowed subset |
| `clientConnectedFn` | `TSocketIOClientConnectedFn` | `undefined` | Called after a client is fully authenticated and has joined default rooms |
| `defaultRooms` | `string[]` | `['io-default', 'io-notification']` | Rooms that every authenticated client joins automatically |
| `authenticateTimeout` | `number` | `10000` (10 s) | Milliseconds before an unauthenticated client is disconnected |
| `pingInterval` | `number` | `30000` (30 s) | Interval in milliseconds between heartbeat pings to authenticated clients |

> [!WARNING]
> If no `validateRoomFn` is provided, **all room join requests are rejected** with a warning log. You must provide this callback if you want clients to join custom rooms beyond the `defaultRooms`.

### Client

`SocketIOClientHelper` connects to a Socket.IO server. Configuration is done entirely via the constructor -- `configure()` is called automatically.

```typescript
import { SocketIOClientHelper } from '@venizia/ignis-helpers';

const socketClient = new SocketIOClientHelper({
  identifier: 'my-client',
  host: 'http://localhost:3000',
  options: {
    path: '/socket.io',
    extraHeaders: {
      Authorization: 'Bearer my-jwt-token',
    },
  },
  onConnected: () => {
    console.log('Connected to server');
    socketClient.authenticate();
  },
  onDisconnected: (reason) => {
    console.log('Disconnected:', reason);
  },
  onError: (error) => {
    console.error('Connection error:', error);
  },
  onAuthenticated: () => {
    console.log('Successfully authenticated');
  },
  onUnauthenticated: (message) => {
    console.warn('Authentication failed:', message);
  },
});
```

#### `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 (extends `SocketOptions` with `path` and `extraHeaders`) |
| `onConnected` | `() => ValueOrPromise<void>` | `undefined` | Called when the transport connection is established |
| `onDisconnected` | `(reason: string) => ValueOrPromise<void>` | `undefined` | Called when disconnected. The client state resets to `'unauthorized'` |
| `onError` | `(error: Error) => ValueOrPromise<void>` | `undefined` | Called on connection errors |
| `onAuthenticated` | `() => ValueOrPromise<void>` | `undefined` | Called when the server sends an `authenticated` event |
| `onUnauthenticated` | `(message: string) => ValueOrPromise<void>` | `undefined` | Called when the server rejects authentication |

#### `IOptions`

Extends `SocketOptions` from `socket.io-client`:

| Option | Type | Description |
|--------|------|-------------|
| `path` | `string` | Socket.IO server path (e.g., `'/socket.io'`) |
| `extraHeaders` | `Record<string \| symbol \| number, any>` | Additional headers sent with the connection request |

## Usage

### Server Setup

After constructing the server helper, call `configure()` to initialize the Socket.IO server, set up the Redis adapter, and start listening for connections.

```typescript
const socketServer = new SocketIOServerHelper({
  identifier: 'my-server',
  runtime: 'node',
  server: httpServer,
  redisConnection: redisHelper,
  serverOptions: { cors: { origin: '*' } },
  authenticateFn: async (handshake) => {
    return verifyToken(handshake.auth?.token);
  },
});

await socketServer.configure();
// Server is now ready and listening for connections

httpServer.listen(3000, () => {
  console.log('HTTP + Socket.IO server running on port 3000');
});
```

#### Bun Runtime

For Bun, pass the `@socket.io/bun-engine` instance instead of an HTTP server:

```typescript
import { SocketIOServerHelper } from '@venizia/ignis-helpers';

const socketServer = new SocketIOServerHelper({
  identifier: 'my-bun-server',
  runtime: 'bun',
  engine: bunEngineInstance,
  redisConnection: redisHelper,
  serverOptions: {},
  authenticateFn: async (handshake) => {
    return verifyToken(handshake.auth?.token);
  },
});

await socketServer.configure();
```

### Client Connection

The client connects automatically on construction. Call `authenticate()` after the connection is established to trigger the server-side authentication flow.

```typescript
const client = new SocketIOClientHelper({
  identifier: 'app-client',
  host: 'http://localhost:3000',
  options: {
    path: '/socket.io',
    extraHeaders: { Authorization: 'Bearer my-token' },
  },
  onConnected: () => {
    // Connection established -- initiate authentication
    client.authenticate();
  },
  onAuthenticated: () => {
    // Now safe to subscribe and emit
    client.joinRooms({ rooms: ['chat-room-1'] });
  },
});
```

### Emitting Events

#### From the Server

Use `send()` to emit events through the Redis emitter. Messages can target a specific socket ID, a room, or broadcast to all clients.

```typescript
// Send to a specific client
socketServer.send({
  destination: 'client-socket-id',
  payload: {
    topic: 'notification',
    data: { message: 'Hello!' },
  },
});

// Broadcast to all connected clients (no destination)
socketServer.send({
  payload: {
    topic: 'announcement',
    data: { message: 'Server update in 5 minutes' },
  },
});

// Send with logging and callback
socketServer.send({
  destination: 'some-room',
  payload: {
    topic: 'room-event',
    data: { action: 'update' },
  },
  doLog: true,
  cb: () => {
    console.log('Message queued');
  },
});
```

#### From the Client

Use `emit()` to send events to the server.

```typescript
client.emit({
  topic: 'chat-message',
  data: { text: 'Hello, world!' },
});

// With logging enabled
client.emit({
  topic: 'user-action',
  data: { action: 'click', target: 'button-1' },
  doLog: true,
});

// With callback
client.emit({
  topic: 'upload-complete',
  data: { fileId: '123' },
  cb: () => {
    console.log('Emit completed');
  },
});
```

### Listening for Events

#### Server-Side Event Binding

Use `on()` to register event handlers on the IO server instance.

```typescript
socketServer.on({
  topic: 'custom-event',
  handler: (data) => {
    console.log('Received:', data);
  },
});
```

#### Client-Side Event Subscription

Use `subscribe()` for single events and `subscribeMany()` for batch registration.

```typescript
// Single event
client.subscribe({
  event: 'notification',
  handler: (data) => {
    console.log('Notification:', data);
  },
});

// Prevent duplicate handlers (default behavior)
client.subscribe({
  event: 'notification',
  handler: (data) => { /* ... */ },
  ignoreDuplicate: true, // Default: true -- skips if handler already exists
});

// Allow multiple handlers for same event
client.subscribe({
  event: 'chat-message',
  handler: handler1,
  ignoreDuplicate: false,
});

// Batch subscribe
client.subscribeMany({
  events: {
    'user-joined': (data) => console.log('Joined:', data),
    'user-left': (data) => console.log('Left:', data),
    'typing': (data) => console.log('Typing:', data),
  },
});

// Unsubscribe from a specific event (removes all handlers)
client.unsubscribe({ event: 'notification' });

// Unsubscribe from multiple events
client.unsubscribeMany({ events: ['user-joined', 'user-left'] });
```

### Rooms

#### Client-Side Room Operations

```typescript
// Join rooms (validated by server's validateRoomFn)
client.joinRooms({ rooms: ['chat-room-1', 'notifications'] });

// Leave rooms
client.leaveRooms({ rooms: ['chat-room-1'] });
```

#### Server-Side Room Behavior

Authenticated clients automatically join the `defaultRooms` (by default, `'io-default'` and `'io-notification'`). Custom room join requests are validated through `validateRoomFn` before the client is allowed to join.

```typescript
const socketServer = new SocketIOServerHelper({
  // ...
  defaultRooms: ['general', 'announcements'],
  validateRoomFn: async ({ socket, rooms }) => {
    // Only allow rooms the user has permission for
    const userPermissions = await getUserPermissions(socket.id);
    return rooms.filter(room => userPermissions.includes(room));
  },
});
```

### Authentication Flow

The server enforces a post-connection authentication protocol:

```
Client connects
  |
  v
Server creates client entry (state: UNAUTHORIZED)
  |-- Starts authenticateTimeout timer (default: 10s)
  |-- Registers disconnect handler
  |
Client emits 'authenticate' event
  |
  v
Server calls authenticateFn(handshake)
  |
  +-- Returns true:
  |     |-- State -> AUTHENTICATED
  |     |-- Clear auth timeout
  |     |-- Join default rooms
  |     |-- Start ping interval
  |     |-- Emit 'authenticated' to client
  |     +-- Invoke clientConnectedFn
  |
  +-- Returns false:
  |     |-- State -> UNAUTHORIZED
  |     |-- Emit 'unauthenticated' to client
  |     +-- Disconnect
  |
  +-- Timeout (no auth within authenticateTimeout):
        +-- Disconnect
```

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

- **redisPub** -- Publishes adapter messages
- **redisSub** -- Subscribes to adapter messages
- **redisEmitter** -- Powers `send()` for cross-instance message delivery

All three connections are initialized and awaited during `configure()`. If the parent client uses `lazyConnect`, the duplicated clients will connect automatically.

```typescript
// Messages sent via send() use the Redis emitter,
// so they reach clients on ANY server instance
socketServer.send({
  destination: 'some-room',
  payload: {
    topic: 'update',
    data: { value: 42 },
  },
});
```

### Graceful Shutdown

#### Server

```typescript
await socketServer.shutdown();
// 1. Disconnects all clients (clears intervals and timeouts)
// 2. Closes the IO server
// 3. Quits all three Redis connections (pub, sub, emitter)
```

#### Client

```typescript
client.shutdown();
// 1. Removes all event listeners
// 2. Disconnects if connected
// 3. Resets state to 'unauthorized'
```

## Troubleshooting

### `[SocketIOServerHelper] Invalid HTTP server for Node.js runtime!`

**Cause:** The `server` option is missing or falsy when `runtime` is `'node'`.

**Fix:** Pass a valid `http.Server` instance.

### `[SocketIOServerHelper] Invalid @socket.io/bun-engine instance for Bun runtime!`

**Cause:** The `engine` option is missing or falsy when `runtime` is `'bun'`.

**Fix:** Pass a valid `@socket.io/bun-engine` Server instance.

### `[SocketIOServerHelper] Unsupported runtime!`

**Cause:** The `runtime` value is neither `'node'` nor `'bun'`.

**Fix:** Use `RuntimeModules.NODE` or `RuntimeModules.BUN`.

### `Invalid redis connection to config socket.io adapter!`

**Cause:** The `redisConnection` option is missing, `null`, or `undefined`.

**Fix:** Pass a valid `DefaultRedisHelper` instance.

### `[on] Invalid topic to start binding handler`

**Cause:** An empty or falsy `topic` was passed to `on()`.

**Fix:** Provide a non-empty string topic.

### `[on] IOServer is not initialized yet!`

**Cause:** `on()` was called before `configure()` completed.

**Fix:** Await `configure()` before registering event handlers.

### `Invalid socket client state to emit`

**Cause (client):** `emit()` was called when the client is not connected.

**Fix:** Check that the client is connected before emitting, or emit inside the `onConnected` callback.

### `Topic is required to emit`

**Cause (client):** `emit()` was called with an empty or falsy `topic`.

**Fix:** Provide a non-empty string topic.

## See Also

- [API Reference](./api) -- Full method signatures, types, and constants
- [WebSocket Helper](../websocket/) -- Bun-native WebSocket alternative