@venizia/ignis-docs 0.2.0 → 0.2.1-0

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

@@ -1,12 +1,132 @@
 # Socket.IO -- Usage & Examples
 
-> Server-side usage patterns, client helper setup, and advanced examples.
+> Full setup steps, server-side usage patterns, client helper, and advanced examples.
+
+## Full Setup
+
+### 1. Install Dependencies
+
+```bash
+# Core dependency (already included via @venizia/ignis)
+# ioredis is required for the Redis adapter
+
+# For Bun runtime only -- optional peer dependency
+bun add @socket.io/bun-engine
+```
+
+### 2. Bind Required + 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
+      const allowedRooms = rooms.filter(room => room.startsWith('public-'));
+      return allowedRooms;
+    };
+
+    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 connection, not you.** `RedisSingleHelper` is created with `autoConnect: false` because the server helper internally calls `client.duplicate()` to create 3 independent Redis connections (pub, sub, emitter).
+- **Duplicates inherit `lazyConnect`, not connection state.** During `configure()`, the helper detects clients in `wait` status and explicitly calls `client.connect()` on each, then awaits all 3 to reach `ready` status before proceeding.
+- **This avoids a race.** If the parent connects before the duplicates exist, the duplicates can end up in an inconsistent state relative to 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 are supported transparently.
+
+> [!NOTE]
+> Full defaults, the complete binding key table, and every system event/room constant are in the [API Reference](./api#configuration-reference).
 
 ## Server-Side Usage
 
 ### Inject and Use in Services/Controllers
 
-Inject `SocketIOServerHelper` to interact with Socket.IO:
+- **`SOCKET_IO_INSTANCE` does not exist at construction time.** The component binds `SocketIOServerHelper` from a post-start hook, which runs after the server starts -- well after every service/controller has already been constructed by the DI container.
+- **Use a lazy getter, not `@inject`.** Resolve the helper from the application container on first access, and cache it. `@inject`-ing `SOCKET_IO_INSTANCE` directly in a constructor will resolve to nothing.
 
 ```typescript
 import {
@@ -19,7 +139,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(
@@ -78,19 +197,14 @@ export class NotificationService extends BaseService {
 }
 ```
 
-> [!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.
-
 ## 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` 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 `socket.io-client` with authentication flow, lifecycle callbacks, and error-safe event subscription.
 
 ### 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',
@@ -122,13 +236,13 @@ const client = new SocketIOClientHelper({
 });
 ```
 
-#### Constructor Behavior
-
-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.
+- **The constructor calls `configure()` immediately.** `configure()` 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 does not connect on its own accord unless `autoConnect` allows it.** Call `client.connect()` explicitly when `autoConnect: false` is set in `options`; otherwise the socket connects automatically.
 
 #### `connect` vs `connection` Event
 
-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'`.
+- **Client and server use different event names.** `socket.io-client` fires `connect` (no suffix) when the connection is established; server-side `socket.io` fires `connection` (with the suffix). This is a Socket.IO convention, not IGNIS-specific.
+- **The two helpers mirror this.** The client helper registers on `'connect'`; the server helper registers on `SocketIOConstants.EVENT_CONNECT`, which equals `'connection'`.
 
 ### Authentication Flow
 
@@ -139,20 +253,21 @@ After connecting, the client must emit `authenticate` to start the auth handshak
 client.authenticate();
 ```
 
-The `authenticate()` method has two guard conditions:
+`authenticate()` has two guard conditions -- both make the call a no-op with a warning log:
+
 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
+2. The current state must be `unauthorized` -- calling `authenticate()` while `authenticating` or already `authenticated` does nothing
 
 #### Authentication Failure Details
 
-The server sends two distinct error messages depending on how the `authenticateFn` fails:
+The server sends two distinct error messages depending on how `authenticateFn` fails:
 
 | 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 |
 
-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).
+Both failure paths set the client state back to `unauthorized`, emit the `unauthenticated` event to the client with the message, and disconnect the socket after the message is delivered (via a `setImmediate` callback).
 
 ### Event Subscription
 
@@ -186,7 +301,8 @@ client.subscribeMany({
 
 #### 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 listeners already exist for the event, `subscribe()` is a no-op and logs an info message.
+- **Set `ignoreDuplicate: false` to stack handlers.** This allows multiple handlers to run for the same event.
 
 ### Unsubscribing
 
@@ -207,14 +323,14 @@ client.unsubscribeMany({ events: ['chat:message', 'user:joined', 'room:updated']
 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 no `topic` is provided. Unlike `send()` on the server helper, this method does **not** silently swallow missing-argument errors.
 
 ### Room Management
 
@@ -226,7 +342,7 @@ 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 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.
 
 ### Connection Management
 
@@ -251,7 +367,8 @@ const rawSocket = client.getSocketClient();
 client.shutdown();
 ```
 
-The `shutdown()` method:
+`shutdown()` does three things, in order:
+
 1. Calls `removeAllListeners()` on the underlying socket to prevent memory leaks
 2. Disconnects if still connected
 3. Resets state to `unauthorized`
@@ -317,6 +434,6 @@ Review the example code to understand production-ready patterns for:
 
 ## See Also
 
-- [Setup & Configuration](./) -- Quick reference, installation, bindings, constants
-- [API Reference](./api) -- Architecture, method signatures, internals, types
+- [Setup & Configuration](./) -- Quick reference, import paths, use cases
+- [API Reference](./api) -- Architecture, configuration reference, method signatures, internals, types
 - [Error Reference](./errors) -- Error conditions and troubleshooting