@venizia/ignis-docs 0.2.0 → 0.2.1-1

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

@@ -1,12 +1,141 @@
-# Socket.IO -- Usage & Examples
+---
+title: Socket.IO Component - Usage & Examples
+description: Full setup steps, server-side usage, the client helper, and advanced patterns
+difficulty: intermediate
+---
 
-> Server-side usage patterns, client helper setup, and advanced examples.
+# Usage & Examples
 
-## Server-Side Usage
+Task-oriented patterns for the Socket.IO component: full setup, sending messages from a service, using the standalone client helper, and reading the example app.
 
-### Inject and Use in Services/Controllers
+## Full setup
 
-Inject `SocketIOServerHelper` to interact with Socket.IO:
+### 1. Install dependencies
+
+```bash
+# Core dependency (already included via @venizia/ignis)
+# ioredis is required for the Redis adapter
+
+# Bun runtime only - optional peer dependency
+bun add @socket.io/bun-engine
+```
+
+### 2. Bind required and optional services
+
+```typescript
+import { BaseApplication } from '@venizia/ignis';
+import { SocketIOComponent, SocketIOBindingKeys } from '@venizia/ignis/socket-io';
+import { RedisSingleHelper, ValueOrPromise } from '@venizia/ignis-helpers';
+import type {
+  TSocketIOAuthenticateFn,
+  TSocketIOValidateRoomFn,
+  TSocketIOClientConnectedFn,
+} from '@venizia/ignis-helpers/socket-io';
+
+export class Application extends BaseApplication {
+  private redisHelper: RedisSingleHelper;
+
+  preConfigure(): ValueOrPromise<void> {
+    this.setupSocketIO();
+    // ... other setup
+  }
+
+  setupSocketIO() {
+    // 1. Redis connection (required for adapter + emitter)
+    this.redisHelper = new RedisSingleHelper({
+      name: 'socket-io-redis',
+      host: process.env.REDIS_HOST ?? 'localhost',
+      port: +(process.env.REDIS_PORT ?? 6379),
+      password: process.env.REDIS_PASSWORD,
+      autoConnect: false,
+    });
+
+    this.bind<RedisSingleHelper>({
+      key: SocketIOBindingKeys.REDIS_CONNECTION,
+    }).toValue(this.redisHelper);
+
+    // 2. Authentication handler (required)
+    const authenticateFn: TSocketIOAuthenticateFn = handshake => {
+      const token = handshake.headers.authorization;
+      // Implement your auth logic: JWT verification, session check, etc.
+      return !!token;
+    };
+
+    this.bind<TSocketIOAuthenticateFn>({
+      key: SocketIOBindingKeys.AUTHENTICATE_HANDLER,
+    }).toValue(authenticateFn);
+
+    // 3. Room validation handler (optional - joins rejected without this)
+    const validateRoomFn: TSocketIOValidateRoomFn = ({ socket, rooms }) => {
+      // Return the rooms that the client is allowed to join
+      return rooms.filter(room => room.startsWith('public-'));
+    };
+
+    this.bind<TSocketIOValidateRoomFn>({
+      key: SocketIOBindingKeys.VALIDATE_ROOM_HANDLER,
+    }).toValue(validateRoomFn);
+
+    // 4. Client connected handler (optional)
+    const clientConnectedFn: TSocketIOClientConnectedFn = ({ socket }) => {
+      console.log('Client connected:', socket.id);
+      // Register custom event handlers on the socket
+    };
+
+    this.bind<TSocketIOClientConnectedFn>({
+      key: SocketIOBindingKeys.CLIENT_CONNECTED_HANDLER,
+    }).toValue(clientConnectedFn);
+
+    // 5. Register the component - that's it!
+    this.component(SocketIOComponent);
+  }
+}
+```
+
+### 3. Why `autoConnect: false`
+
+The helper owns the connection timing, not you. `RedisSingleHelper` is created with `autoConnect: false` because the server helper calls `duplicateClient()` three times:
+
+| Duplicate | Role |
+|---|---|
+| `redisPub` | Redis adapter - publishes room broadcasts |
+| `redisSub` | Redis adapter - subscribes to room broadcasts |
+| `redisEmitter` | Redis emitter - direct cross-instance send |
+
+- **Duplicates inherit `lazyConnect`, not connection state.** During `configure()`, the helper checks each client's status. Any client still `wait`ing gets `connect()` called on it explicitly. The helper then waits for all three to reach `ready` before proceeding.
+- **This avoids a race.** If the parent connects before the duplicates exist, the duplicates can end up in a state inconsistent with the parent's connection lifecycle.
+
+### Redis connection alternatives
+
+`RedisSingleHelper` (single instance), `RedisClusterHelper` (cluster mode), and `RedisSentinelHelper` (Sentinel HA) all extend `AbstractRedisHelper` and satisfy the `IRedisHelper` interface the component validates against.
+
+```typescript
+import { RedisClusterHelper } from '@venizia/ignis-helpers';
+
+// For Redis Cluster deployments
+const redisHelper = new RedisClusterHelper({
+  name: 'socket-io-redis-cluster',
+  nodes: [
+    { host: 'redis-node-1', port: 6379 },
+    { host: 'redis-node-2', port: 6380 },
+    { host: 'redis-node-3', port: 6381 },
+  ],
+  password: process.env.REDIS_PASSWORD,
+  autoConnect: false,
+});
+
+this.bind<RedisClusterHelper>({
+  key: SocketIOBindingKeys.REDIS_CONNECTION,
+}).toValue(redisHelper);
+```
+
+The internal `TRedisClient` type is `Redis | Cluster`, so both ioredis connection types work transparently.
+
+> [!NOTE]
+> Full defaults, the complete binding key table, and every system event/room constant are in the [Full Reference](./api#configuration-reference).
+
+## Inject the helper in a service or controller
+
+`SocketIOServerHelper` is bound to `SOCKET_IO_INSTANCE` inside a post-start hook. That hook runs after the server starts - well after the DI container already built every service and controller. Use a lazy getter that resolves the helper on first access. Never `@inject` it in a constructor.
 
 ```typescript
 import {
@@ -19,7 +148,6 @@ import { SocketIOBindingKeys } from '@venizia/ignis/socket-io';
 import { SocketIOServerHelper } from '@venizia/ignis-helpers/socket-io';
 
 export class NotificationService extends BaseService {
-  // Lazy getter pattern -- helper is bound AFTER server starts
   private _io: SocketIOServerHelper | null = null;
 
   constructor(
@@ -59,47 +187,37 @@ export class NotificationService extends BaseService {
   notifyRoom(opts: { room: string; message: string }) {
     this.io.send({
       destination: opts.room,
-      payload: {
-        topic: 'room:update',
-        data: { message: opts.message },
-      },
+      payload: { topic: 'room:update', data: { message: opts.message } },
     });
   }
 
   // Broadcast to all clients
   broadcastAnnouncement(opts: { message: string }) {
     this.io.send({
-      payload: {
-        topic: 'system:announcement',
-        data: { message: opts.message },
-      },
+      payload: { topic: 'system:announcement', data: { message: opts.message } },
     });
   }
 }
 ```
 
-> [!IMPORTANT]
-> **Lazy getter pattern**: Since `SocketIOServerHelper` is bound via a post-start hook, it's not available during DI construction. Use a lazy getter that resolves from the application container on first access.
+- **Never `@inject` `SOCKET_IO_INSTANCE` in a constructor.** It is not bound yet at that point.
+- **`send()` reads via the Redis emitter.** It works even if the destination client is connected to a different server instance - see [`send()` in the Full Reference](./api#messaging-via-send).
 
-## Client Helper
+## Use the client helper
 
-`SocketIOClientHelper` provides a managed Socket.IO client for connecting to Socket.IO servers -- useful for service-to-service communication, testing, or building relay services. It extends `BaseHelper` for scoped logging and wraps the `socket.io-client` library with authentication flow, lifecycle callbacks, and error-safe event subscription.
+`SocketIOClientHelper` wraps `socket.io-client` with authentication flow, lifecycle callbacks, and error-safe event subscription. Use it when your process needs to connect *to* a Socket.IO server, not run one - service-to-service communication, testing, or relay services.
 
-### Client Setup
+### Client setup
 
 ```typescript
-import {
-  SocketIOClientHelper,
-} from '@venizia/ignis-helpers/socket-io';
+import { SocketIOClientHelper } from '@venizia/ignis-helpers/socket-io';
 
 const client = new SocketIOClientHelper({
   identifier: 'notification-relay',
   host: 'http://localhost:3000',
   options: {
     path: '/io',
-    extraHeaders: {
-      authorization: 'Bearer <token>',
-    },
+    extraHeaders: { authorization: 'Bearer <token>' },
   },
 
   // Lifecycle callbacks (all optional)
@@ -107,56 +225,52 @@ const client = new SocketIOClientHelper({
     console.log('Connected to server');
     client.authenticate();
   },
-  onDisconnected: (reason) => {
-    console.log('Disconnected:', reason);
-  },
-  onError: (error) => {
-    console.error('Connection error:', error);
-  },
-  onAuthenticated: () => {
-    console.log('Authentication successful');
-  },
-  onUnauthenticated: (message) => {
-    console.warn('Authentication failed:', message);
-  },
+  onDisconnected: reason => console.log('Disconnected:', reason),
+  onError: error => console.error('Connection error:', error),
+  onAuthenticated: () => console.log('Authentication successful'),
+  onUnauthenticated: message => console.warn('Authentication failed:', message),
 });
 ```
 
-#### Constructor Behavior
+- **The constructor calls `configure()` immediately.** It creates the `socket.io-client` `Socket` instance via `io(host, options)` and registers the internal event handlers. See the [full handler table](./api#client-configure-event-handlers) in the Full Reference.
+- **The socket connects on its own unless you disable it.** Set `autoConnect: false` in `options` and call `client.connect()` yourself when you're ready.
+
+#### `connect` vs `connection` event
 
-The constructor immediately calls `configure()`, which creates the `socket.io-client` `Socket` instance via `io(host, options)` and registers all internal event handlers (`connect`, `disconnect`, `connect_error`, `authenticated`, `unauthenticated`, `ping`). The socket is **not** connected until you call `client.connect()` (if using `autoConnect: false` in the options) or it connects automatically if `autoConnect` is not explicitly disabled.
+Client and server fire different event names for the same moment:
 
-#### `connect` vs `connection` Event
+| Side | Fires |
+|---|---|
+| Client (`socket.io-client`) | `connect` - no suffix |
+| Server (`socket.io`) | `connection` - with the suffix |
 
-The client-side `socket.io-client` library fires the `connect` event (no "ion" suffix) when the connection is established. The server-side `socket.io` library fires `connection` (with the suffix). This is a Socket.IO convention, not an IGNIS-specific behavior. The client helper registers on `'connect'` while the server helper registers on `SocketIOConstants.EVENT_CONNECT` which equals `'connection'`.
+This is a Socket.IO convention, not an IGNIS one. The client helper listens on `'connect'`. The server helper listens on `SocketIOConstants.EVENT_CONNECT`, which equals `'connection'`.
 
-### Authentication Flow
+### Authentication flow
 
-After connecting, the client must emit `authenticate` to start the auth handshake. The server validates credentials from the socket handshake (headers, query params, `auth` object) and responds with either `authenticated` or `unauthenticated`.
+After connecting, the client must emit `authenticate` to start the handshake. The server validates credentials from the socket handshake (headers, query params, `auth` object) and responds with either `authenticated` or `unauthenticated`.
 
 ```typescript
-// Manual authentication after connection
 client.authenticate();
 ```
 
-The `authenticate()` method has two guard conditions:
-1. The socket must be connected (`client.connected === true`)
-2. The current state must be `unauthorized` -- calling `authenticate()` while `authenticating` or already `authenticated` is a no-op with a warning log
+`authenticate()` is a no-op with a warning log unless both conditions hold:
 
-#### Authentication Failure Details
+1. The socket is connected (`client.connected === true`).
+2. The current state is `unauthorized` - calling `authenticate()` while `authenticating` or already `authenticated` does nothing.
 
-The server sends two distinct error messages depending on how the `authenticateFn` fails:
+#### Authentication failure messages
 
-| Failure Mode | Message | Cause |
-|-------------|---------|-------|
-| `authenticateFn` returned `false` | `"Invalid token to authenticate! Please login again!"` | Credentials were checked but deemed invalid |
-| `authenticateFn` threw an error | `"Failed to authenticate connection! Please login again!"` | An unexpected error occurred during validation |
+The server sends a different message depending on how `authenticateFn` failed. Both paths reset the client to `unauthorized`, emit `unauthenticated` with the message, and disconnect the socket after delivery (via `setImmediate`).
 
-Both failure paths set the client state back to `unauthorized`, emit the `unauthenticated` event to the client with the message, and then disconnect the socket after the message is delivered (via `setImmediate` callback).
+| Failure mode | Message |
+|---|---|
+| `authenticateFn` returned `false` | `"Invalid token to authenticate! Please login again!"` |
+| `authenticateFn` threw an error | `"Failed to authenticate connection! Please login again!"` |
 
-### Event Subscription
+### Event subscription
 
-Subscribe to custom events with automatic error safety. Handlers are wrapped in a dual try-catch that catches both synchronous throws and asynchronous rejections:
+Handlers are wrapped in a dual try-catch. It catches both synchronous throws and asynchronous rejections, so a broken handler never crashes the client.
 
 ```typescript
 // Subscribe to a single event
@@ -167,26 +281,24 @@ client.subscribe({
   },
 });
 
-// Subscribe with duplicate detection disabled
+// ignoreDuplicate: false stacks a second handler for the same event
 client.subscribe({
   event: 'chat:message',
-  handler: (data) => { /* second handler */ },
-  ignoreDuplicate: false, // default: true -- set to false to allow multiple handlers
+  handler: data => { /* second handler */ },
+  ignoreDuplicate: false,
 });
 
 // Subscribe to multiple events at once
 client.subscribeMany({
   events: {
-    'user:joined': (data) => console.log('User joined:', data),
-    'user:left': (data) => console.log('User left:', data),
-    'room:updated': (data) => console.log('Room updated:', data),
+    'user:joined': data => console.log('User joined:', data),
+    'user:left': data => console.log('User left:', data),
+    'room:updated': data => console.log('Room updated:', data),
   },
 });
 ```
 
-#### Deduplication Behavior
-
-By default (`ignoreDuplicate: true`), `subscribe()` checks `socket.hasListeners(event)` before registering. If listeners already exist for the event, the call is a no-op and logs an info message. Set `ignoreDuplicate: false` to allow multiple handlers for the same event.
+The default (`ignoreDuplicate: true`) checks `socket.hasListeners(event)` first. If a listener already exists, `subscribe()` is a no-op that logs an info message. Set `ignoreDuplicate: false` to stack handlers instead.
 
 ### Unsubscribing
 
@@ -201,22 +313,22 @@ client.unsubscribe({ event: 'chat:message', handler: myHandler });
 client.unsubscribeMany({ events: ['chat:message', 'user:joined', 'room:updated'] });
 ```
 
-### Emitting Events
+### Emitting events
 
 ```typescript
 client.emit({
   topic: 'chat:send',
   data: { text: 'Hello world' },
-  doLog: true,   // optional: log the emission
-  cb: () => {    // optional: callback via setImmediate after emit
+  doLog: true,       // optional: log the emission
+  callback: () => {  // optional: invoked via setImmediate after emit
     console.log('Message sent');
   },
 });
 ```
 
-The `emit()` method throws if the socket is not connected or if no `topic` is provided. Unlike `send()` on the server helper, this method does **not** silently swallow errors.
+`emit()` throws if the socket is not connected or if `topic` is missing. The server helper's `send()` silently drops a message with a missing field - `emit()` never does that. It always throws instead.
 
-### Room Management
+### Room management
 
 ```typescript
 // Request to join rooms (server validates via validateRoomFn)
@@ -226,9 +338,9 @@ client.joinRooms({ rooms: ['chat-room-1', 'notifications'] });
 client.leaveRooms({ rooms: ['chat-room-1'] });
 ```
 
-Both methods emit Socket.IO events (`join` / `leave`) to the server. The actual join/leave happens server-side. If the socket is not connected, the call is a no-op with a warning log.
+Both methods emit a Socket.IO event to the server: `join` or `leave`. The actual join or leave happens server-side. If the socket isn't connected, the call is a no-op with a warning log.
 
-### Connection Management
+### Connection management
 
 ```typescript
 // Manually connect (useful when autoConnect: false in options)
@@ -247,34 +359,30 @@ const rawSocket = client.getSocketClient();
 ### Shutdown
 
 ```typescript
-// Clean shutdown: removes all listeners, disconnects, resets state
 client.shutdown();
 ```
 
-The `shutdown()` method:
-1. Calls `removeAllListeners()` on the underlying socket to prevent memory leaks
-2. Disconnects if still connected
-3. Resets state to `unauthorized`
+`shutdown()` does three things, in order:
 
-## Advanced Usage
+1. Calls `removeAllListeners()` on the underlying socket to prevent memory leaks.
+2. Disconnects if still connected.
+3. Resets state to `unauthorized`.
 
-### Complete Example
+## Run the complete example
 
-A full working example is available at `examples/socket-io-test/`. It demonstrates:
+A full working example lives at `examples/socket-io-test/`.
 
 | Feature | Implementation |
-|---------|---------------|
-| Application setup | `src/application.ts` -- bindings, component registration, graceful shutdown |
-| REST endpoints | `src/controllers/socket-test.controller.ts` -- 9 endpoints for Socket.IO management |
-| Event handling | `src/services/socket-event.service.ts` -- chat, echo, room management |
-| Automated test client | `client.ts` -- 15+ test cases covering all features |
-
-#### REST API Endpoints
+|---|---|
+| Application setup | `src/application.ts` - bindings, component registration, graceful shutdown |
+| REST endpoints | `src/controllers/socket-test.controller.ts` - 9 endpoints for Socket.IO management |
+| Event handling | `src/services/socket-event.service.ts` - chat, echo, room management |
+| Automated test client | `client.ts` - 15+ test cases covering all features |
 
-The example provides a REST API for managing Socket.IO:
+### REST API endpoints
 
 | Method | Path | Description |
-|--------|------|-------------|
+|---|---|---|
 | `GET` | `/socket/info` | Server status + connected client count |
 | `GET` | `/socket/clients` | List all connected client IDs |
 | `GET` | `/socket/health` | Health check (is SocketIO ready?) |
@@ -285,38 +393,37 @@ The example provides a REST API for managing Socket.IO:
 | `POST` | `/socket/client/{clientId}/leave` | Remove client from <code v-pre>{{ rooms: string[] }}</code> |
 | `GET` | `/socket/client/{clientId}/rooms` | List rooms a client belongs to |
 
-#### Running the Example
+### Running the example
 
 ```bash
 # Start the server
 cd examples/socket-io-test
 bun run server:dev
 
-# In another terminal -- run automated tests
+# In another terminal - run automated tests
 bun client.ts
 ```
 
-The automated client tests the following features:
+The automated client exercises:
 
-- Authentication (valid and invalid tokens)
+- Authentication with valid and invalid tokens
 - Ping/pong keepalive
 - Room join/leave with validation
 - Client-to-client messaging
-- Room broadcasting
-- Global broadcasting
-- REST API for Socket.IO management
+- Room and global broadcasting
+- The REST API
 - Graceful disconnection
 
-Review the example code to understand production-ready patterns for:
+Read the example for these production-ready patterns:
 
-- Binding multiple handlers in a single `setupSocketIO()` method
-- Lazy getter pattern for accessing `SocketIOServerHelper` in services
+- Binding multiple handlers in one `setupSocketIO()` method
+- The lazy getter pattern for `SocketIOServerHelper`
 - Custom event registration via `CLIENT_CONNECTED_HANDLER`
-- Room validation logic preventing unauthorized room access
-- Graceful shutdown sequence in `application.stop()`
+- Room validation that blocks unauthorized rooms
+- A graceful shutdown sequence in `application.stop()`
 
-## See Also
+## See also
 
-- [Setup & Configuration](./) -- Quick reference, installation, bindings, constants
-- [API Reference](./api) -- Architecture, method signatures, internals, types
-- [Error Reference](./errors) -- Error conditions and troubleshooting
+- [Overview](./) - quick start, imports, common configuration tasks
+- [Full Reference](./api) - architecture, configuration reference, method signatures, internals, types
+- [Error Reference](./errors) - error conditions and troubleshooting