@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

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

@@ -1,46 +1,52 @@
-# Socket.IO -- Error Reference
+---
+title: Socket.IO Component - Error Reference
+description: Error conditions, failure messages, and troubleshooting for the Socket.IO component, server helper, and client helper
+difficulty: intermediate
+---
 
-> Error conditions, failure messages, and troubleshooting for the Socket.IO component, server helper, and client helper.
+# Error Reference
 
-## Error Conditions
+Every error condition the Socket.IO component and its two helpers can raise, plus fixes for the ones you'll actually hit.
 
-### Component Errors
+## Error conditions
 
-| Method | Condition | Error Message |
-|--------|-----------|---------------|
+### Component errors
+
+| Method | Condition | Error message |
+|---|---|---|
 | `binding()` | `application` is falsy | `"[binding] Invalid application to bind SocketIOComponent"` |
 | `binding()` | Unsupported runtime | `"[SocketIOComponent] Unsupported runtime: <runtime>"` |
-| `resolveBindings()` | `REDIS_CONNECTION` not instanceof `AbstractRedisHelper` | `"Invalid instance of redisConnection | Please init connection with RedisSingleHelper for single redis connection, RedisClusterHelper for cluster mode, or RedisSentinelHelper for sentinel mode!"` |
+| `resolveBindings()` | `REDIS_CONNECTION` fails `isRedisHelper()` | `"Invalid instance of redisConnection..."` |
 | `resolveBindings()` | `AUTHENTICATE_HANDLER` is falsy | `"[DANGER][SocketIOComponent] Invalid authenticateFn to setup io socket server!"` |
 | `registerNodeHook()` | HTTP server not available | `"[SocketIOComponent] HTTP server not available for Node.js runtime!"` |
 
-### Server Helper Errors
+### Server helper errors
 
-| Method | Condition | Error Message |
-|--------|-----------|---------------|
+| Method | Condition | Error message |
+|---|---|---|
 | `setRuntime()` | Node.js runtime, `server` missing | `"[SocketIOServerHelper] Invalid HTTP server for Node.js runtime!"` |
 | `setRuntime()` | Bun runtime, `engine` missing | `"[SocketIOServerHelper] Invalid @socket.io/bun-engine instance for Bun runtime!"` |
 | `setRuntime()` | Unknown runtime | `"[SocketIOServerHelper] Unsupported runtime!"` |
 | `initRedisClients()` | `redisConnection` is falsy | `"Invalid redis connection to config socket.io adapter!"` |
-| `initIOServer()` | Node.js runtime, `server` missing at configure time | `"[DANGER] Invalid HTTP server instance to init Socket.io server!"` |
-| `initIOServer()` | Bun runtime, `engine` missing at configure time | `"[DANGER] Invalid @socket.io/bun-engine instance to init Socket.io server!"` |
+| `initIOServer()` | Node.js, `server` missing at configure time | `"[DANGER] Invalid HTTP server instance to init Socket.io server!"` |
+| `initIOServer()` | Bun, `engine` missing at configure time | `"[DANGER] Invalid @socket.io/bun-engine instance to init Socket.io server!"` |
 | `initIOServer()` | Unknown runtime at configure time | `"[configure] Unsupported runtime: <runtime>"` |
 | `getEngine()` | Runtime is not Bun | `"[getEngine] Engine is only available for Bun runtime!"` |
 | `on()` | `topic` is empty | `"[on] Invalid topic to start binding handler"` |
-| `on()` | `handler` is falsy | `"[on] Invalid event handler | topic: <topic>"` |
+| `on()` | `handler` is falsy | `"[on] Invalid event handler \| topic: <topic>"` |
 | `on()` | IO server not initialized | `"[on] IOServer is not initialized yet!"` |
 
-### Client Helper Errors
+### Client helper errors
 
-| Method | Condition | Error Message |
-|--------|-----------|---------------|
-| `emit()` | Socket not connected | `"Invalid socket client state to emit"` (statusCode: 400) |
-| `emit()` | `topic` is falsy | `"Topic is required to emit"` (statusCode: 400) |
+| Method | Condition | statusCode | Error message |
+|---|---|---|---|
+| `emit()` | Socket not connected | `400` | `"Invalid socket client state to emit"` |
+| `emit()` | `topic` is falsy | `400` | `"Topic is required to emit"` |
 
-### Server Authentication Errors (sent to client)
+### Server authentication errors (sent to the client)
 
 | Condition | Event | Message |
-|-----------|-------|---------|
+|---|---|---|
 | `authenticateFn` returned `false` | `unauthenticated` | `"Invalid token to authenticate! Please login again!"` |
 | `authenticateFn` threw an error | `unauthenticated` | `"Failed to authenticate connection! Please login again!"` |
 
@@ -48,74 +54,66 @@
 
 ### "SocketIO not initialized"
 
-**Cause**: You're trying to use `SocketIOServerHelper` before the server has started (e.g., during DI construction).
-
-**Fix**: Use the lazy getter pattern shown in the [Usage & Examples](./usage) page. Never `@inject` `SOCKET_IO_INSTANCE` directly in a constructor -- it doesn't exist yet at construction time.
+- **Cause:** You used `SocketIOServerHelper` before the server started - typically during DI construction.
+- **Fix:** Use the lazy getter pattern from [Usage & Examples](./usage#inject-the-helper-in-a-service-or-controller). Never `@inject` `SOCKET_IO_INSTANCE` in a constructor - it doesn't exist yet at that point.
 
 ### "Invalid instance of redisConnection"
 
-**Cause**: The value bound to `REDIS_CONNECTION` is not an instance of `AbstractRedisHelper` (i.e. not a `RedisSingleHelper`, `RedisClusterHelper`, or `RedisSentinelHelper`).
-
-**Fix**: Use one of the concrete topology helpers:
+- **Cause:** The value bound to `REDIS_CONNECTION` isn't an `AbstractRedisHelper` instance - not a `RedisSingleHelper`, `RedisClusterHelper`, or `RedisSentinelHelper`.
+- **Fix:** Bind one of the concrete topology helpers, never a raw `ioredis` client.
 
 ```typescript
 import { SocketIOBindingKeys } from '@venizia/ignis/socket-io';
 
-// Correct -- single instance
+// Correct - single instance
 this.bind({ key: SocketIOBindingKeys.REDIS_CONNECTION })
   .toValue(new RedisSingleHelper({ name: 'socket-io', host, port, password }));
 
-// Correct -- cluster mode
+// Correct - cluster mode
 this.bind({ key: SocketIOBindingKeys.REDIS_CONNECTION })
   .toValue(new RedisClusterHelper({ name: 'socket-io', nodes, password }));
 
-// Wrong -- raw ioredis client
-this.bind({ key: SocketIOBindingKeys.REDIS_CONNECTION })
-  .toValue(new Redis(6379));  // This is NOT an AbstractRedisHelper!
+// Wrong - raw ioredis client, not an AbstractRedisHelper
+this.bind({ key: SocketIOBindingKeys.REDIS_CONNECTION }).toValue(new Redis(6379));
 ```
 
 ### "Cannot find module '@socket.io/bun-engine'"
 
-**Cause**: Running on Bun runtime without the optional peer dependency installed.
-
-**Fix**: `bun add @socket.io/bun-engine`
+- **Cause:** Running on Bun without the optional peer dependency installed.
+- **Fix:** `bun add @socket.io/bun-engine`
 
 ### Socket.IO connects but events aren't received
 
-**Cause**: Clients must emit `authenticate` after connecting. Unauthenticated clients are disconnected after the timeout (default: 10 seconds).
-
-**Fix**: Ensure your client emits the authenticate event:
+- **Cause:** The client never emitted `authenticate`. Unauthenticated clients are disconnected after the timeout (default: 10 seconds).
+- **Fix:** Emit `authenticate` right after connecting.
 
 ```typescript
 socket.on('connect', () => {
   socket.emit('authenticate');
 });
 
-socket.on('authenticated', (data) => {
+socket.on('authenticated', data => {
   // Now ready to send/receive events
 });
 ```
 
 ### "Invalid socket client state to emit"
 
-**Cause**: Calling `emit()` on `SocketIOClientHelper` when the socket is not connected.
-
-**Fix**: Ensure the socket is connected before emitting. Check `client.getSocketClient().connected` or wait for the `onConnected` callback.
+- **Cause:** You called `emit()` on `SocketIOClientHelper` while the socket wasn't connected.
+- **Fix:** Confirm the socket is connected before emitting. Check `client.getSocketClient().connected`, or wait for the `onConnected` callback.
 
 ### Client disconnects immediately after connecting
 
-**Cause**: The authentication timeout expired (default: 10 seconds). The client connected but did not emit `authenticate` in time.
-
-**Fix**: Emit `authenticate` immediately on connect, or increase the `authenticateTimeout` in the server helper options.
+- **Cause:** The authentication timeout expired (default: 10 seconds) before the client emitted `authenticate`.
+- **Fix:** Emit `authenticate` immediately on connect, or raise `authenticateTimeout` in the server helper options.
 
 ### Room join requests are silently rejected
 
-**Cause**: No `validateRoomFn` is bound. Without a validation function, all room join requests are rejected by design (security-by-default).
-
-**Fix**: Bind a `VALIDATE_ROOM_HANDLER` that returns the list of allowed rooms.
+- **Cause:** No `validateRoomFn` is bound. Every join is rejected by design when it's missing - security-by-default.
+- **Fix:** Bind a `VALIDATE_ROOM_HANDLER` that returns the list of allowed rooms.
 
-## See Also
+## See also
 
-- [Setup & Configuration](./) -- Quick reference, required bindings, how it works
-- [Usage & Examples](./usage) -- Full setup steps, server-side usage, client helper, advanced patterns
-- [API Reference](./api) -- Architecture, configuration reference, method signatures, internals, types
+- [Overview](./) - quick start, imports, common configuration tasks
+- [Usage & Examples](./usage) - full setup steps, server-side usage, client helper, advanced patterns
+- [Full Reference](./api) - architecture, configuration reference, method signatures, internals, types

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

@@ -1,47 +1,17 @@
-# Socket.IO -- Setup & Configuration
+---
+title: Socket.IO Component
+description: Wires SocketIOServerHelper into the app lifecycle for Node.js and Bun, with Redis-backed horizontal scaling and a mandatory authentication handshake
+difficulty: intermediate
+---
 
-> Real-time, bidirectional, event-based communication using Socket.IO -- with automatic runtime detection for Node.js and Bun, horizontal scaling via Redis, and a built-in authentication handshake.
+# Socket.IO Component
 
-## Quick Reference
+`SocketIOComponent` registers a [`SocketIOServerHelper`](/extensions/helpers/socket-io/) on your application once the server starts. It runs on both Node.js and Bun, and scales across instances through a Redis adapter. Every client must authenticate before it can send or receive anything.
 
-| Item | Value |
-|------|-------|
-| **Package** | `@venizia/ignis` (core) |
-| **Class** | `SocketIOComponent` |
-| **Server Helper** | [`SocketIOServerHelper`](/extensions/helpers/socket-io/) |
-| **Client Helper** | [`SocketIOClientHelper`](/extensions/helpers/socket-io/) |
-| **Runtimes** | Node.js (`@hono/node-server`) and Bun (native) |
-| **Scaling** | `@socket.io/redis-adapter` + `@socket.io/redis-emitter` |
+> [!TIP]
+> Bun-only and don't need Socket.IO's handshake protocol? The [WebSocket Component](../websocket/) is a lighter alternative.
 
-> [!IMPORTANT]
-> `SocketIOComponent` and `SocketIOBindingKeys` are **not** exported from the `@venizia/ignis` barrel -- import from the `@venizia/ignis/socket-io` subpath.
-
-```typescript
-// From core -- subpath import (NOT from '@venizia/ignis')
-import { SocketIOComponent, SocketIOBindingKeys } from '@venizia/ignis/socket-io';
-
-// From helpers -- subpath import
-import { SocketIOServerHelper, SocketIOClientHelper, SocketIOConstants } from '@venizia/ignis-helpers/socket-io';
-import type { TSocketIOAuthenticateFn, TSocketIOValidateRoomFn } from '@venizia/ignis-helpers/socket-io';
-```
-
-**Use cases:**
-
-- Live notifications and alerts
-- Real-time chat and collaborative editing
-- Live dashboards and monitoring streams
-- Multiplayer game state synchronization
-- Service-to-service real-time messaging (via `SocketIOClientHelper`)
-
-## Setup
-
-Three pieces are bound in `preConfigure()`, before the component itself is registered:
-
-| Step | Binding key | Required |
-|------|-------------|----------|
-| 1. Redis connection | `SocketIOBindingKeys.REDIS_CONNECTION` | Yes |
-| 2. Authenticate handler | `SocketIOBindingKeys.AUTHENTICATE_HANDLER` | Yes |
-| 3. Room / connected handlers | `VALIDATE_ROOM_HANDLER`, `CLIENT_CONNECTED_HANDLER` | No |
+## In one example
 
 ```typescript
 import { BaseApplication } from '@venizia/ignis';
@@ -51,39 +21,43 @@ import type { TSocketIOAuthenticateFn } from '@venizia/ignis-helpers/socket-io';
 
 export class Application extends BaseApplication {
   preConfigure(): ValueOrPromise<void> {
-    // 1. Redis connection -- required for the adapter + emitter
-    const redisHelper = new RedisSingleHelper({
-      name: 'socket-io-redis',
-      host: process.env.REDIS_HOST ?? 'localhost',
-      port: +(process.env.REDIS_PORT ?? 6379),
-      autoConnect: false,
-    });
-    this.bind({ key: SocketIOBindingKeys.REDIS_CONNECTION }).toValue(redisHelper);
-
-    // 2. Authentication handler -- required
+    // 1. Redis connection (required - used for the adapter + emitter)
+    this.bind({ key: SocketIOBindingKeys.REDIS_CONNECTION }).toValue(
+      new RedisSingleHelper({ name: 'socket-io-redis', host: 'localhost', port: 6379, autoConnect: false }),
+    );
+
+    // 2. Authenticate handler (required - decides accept/reject per client)
     const authenticateFn: TSocketIOAuthenticateFn = handshake => !!handshake.headers.authorization;
     this.bind({ key: SocketIOBindingKeys.AUTHENTICATE_HANDLER }).toValue(authenticateFn);
 
-    // 3. Register the component
+    // 3. Register - binding() validates the two bindings above and defers the rest
     this.component(SocketIOComponent);
   }
 }
 ```
 
+`SocketIOComponent` and `SocketIOBindingKeys` come from the `@venizia/ignis/socket-io` subpath. They are **not** exported from the `@venizia/ignis` root barrel. Helper types (`TSocketIOAuthenticateFn`, `SocketIOServerHelper`, `SocketIOClientHelper`, `SocketIOConstants`, ...) come from `@venizia/ignis-helpers/socket-io`.
+
 > [!WARNING]
-> `autoConnect: false` is required on the Redis helper -- the server helper duplicates the connection into 3 independent clients and connects them itself during `configure()`. Connecting the parent first races against the duplicates. Full step-by-step setup (Bun peer dependency, room validation, cluster/sentinel Redis, the `autoConnect` rationale) is in [Usage & Examples](./usage#full-setup).
+> `autoConnect: false` is required on the Redis helper. The server helper duplicates the connection into 3 independent clients and connects them itself during `configure()`. Connect the parent first and it races against the duplicates. Full explanation in [Usage & Examples](./usage#full-setup).
 
-## How It Works
+## How it works
 
-- **Post-start hook, not immediate init.** Socket.IO needs a running server, but components initialize *before* the server starts. `binding()` resolves all bindings and registers a post-start hook; the hook builds `SocketIOServerHelper` and binds it to `SOCKET_IO_INSTANCE` only after `start()` brings the server up.
-- **Runtime detection picks the wiring.** `RuntimeModules.detect()` selects Node.js (Socket.IO attaches to `node:http.Server` directly) or Bun (`@socket.io/bun-engine` is dynamically imported and wired into `server.reload()`). See the [runtime matrix](./api#runtime-specific-behavior) for the full comparison.
-- **One Redis connection becomes three.** The connection you bind is never consumed directly -- the helper calls `duplicateClient()` three times: a pub/sub pair for the Redis adapter (cross-instance room broadcast) and a third client for the Redis emitter (cross-instance direct send).
-- **Authentication is mandatory.** Every client starts `unauthorized` and must emit `authenticate` within `authenticateTimeout` (default 10s) or it is disconnected. Success joins the client to the default rooms and starts a keep-alive ping.
-- **Room joins are opt-in by default.** Without a bound `VALIDATE_ROOM_HANDLER`, every `join` request is silently rejected -- security-by-default, not a bug.
+Socket.IO needs a running server, but components initialize before the server exists. Five mechanisms bridge that gap and keep every client on a security-by-default path:
 
-## Common Tasks
+| Mechanism | What happens |
+|---|---|
+| Post-start hook | `binding()` runs during `initialize()`, resolves bindings, and registers a hook. The hook builds `SocketIOServerHelper` and binds it to `SOCKET_IO_INSTANCE` only after `start()` runs. |
+| Runtime detection | `RuntimeModules.detect()` picks Node.js (Socket.IO attaches to `node:http.Server` directly) or Bun (`@socket.io/bun-engine` is dynamically imported and wired into `server.reload()`). See the [runtime comparison](./api#runtime-specific-behavior). |
+| Redis fan-out | The connection you bind is never consumed directly. The helper calls `duplicateClient()` three times: a pub/sub pair for the Redis adapter, and a third client for the Redis emitter. |
+| Mandatory authentication | Every client starts `unauthorized`. It must emit `authenticate` within `authenticateTimeout` (default 10s) or it gets disconnected. Success joins the client to the default rooms and starts a keep-alive ping. |
+| Opt-in rooms | No `VALIDATE_ROOM_HANDLER` bound means every `join` request is rejected. That's security-by-default, not a bug. |
 
-**Restrict CORS for production.** Bind `SERVER_OPTIONS` before registering the component -- the default (`cors.origin: '*'`) is for local development only.
+## Common tasks
+
+### Restrict CORS for production
+
+Bind `SERVER_OPTIONS` before registering the component. The default (`cors.origin: '*'`) is for local development only.
 
 ```typescript
 import type { ServerOptions } from 'socket.io';
@@ -94,39 +68,49 @@ this.bind<Partial<ServerOptions>>({ key: SocketIOBindingKeys.SERVER_OPTIONS }).t
 this.component(SocketIOComponent);
 ```
 
-**Send a message from a service.** `SOCKET_IO_INSTANCE` is bound by the component after the server starts, so resolve it lazily -- never `@inject` it in a constructor. Full pattern in [Usage & Examples](./usage).
+### Send a message from a service
+
+`SOCKET_IO_INSTANCE` is bound by the component after the server starts, so resolve it lazily - never `@inject` it in a constructor. Full pattern in [Inject the helper in a service or controller](./usage#inject-the-helper-in-a-service-or-controller).
 
 ```typescript
 this.io.send({ destination: userId, payload: { topic: 'notification', data } });
 ```
 
-**Scale Redis beyond a single node.** Swap `RedisSingleHelper` for `RedisClusterHelper` or `RedisSentinelHelper` -- both satisfy the `IRedisHelper` interface the component validates against. See [Redis Connection Alternatives](./usage#redis-connection-alternatives).
-
-**Look up every default, binding key, and constant.** Full `DEFAULT_SERVER_OPTIONS`, the binding key table, system events, default rooms, and the client state machine are in the [API Reference](./api#configuration-reference).
-
-## See Also
-
-- [Usage & Examples](./usage) -- Full setup steps, server-side usage, client helper, advanced patterns
-- [API Reference](./api) -- Architecture, configuration reference, method signatures, internals, types
-- [Error Reference](./errors) -- Error conditions and troubleshooting
-- **Guides:**
-  - [Components Overview](/guides/core-concepts/components) -- Component system basics
-  - [Application](/guides/core-concepts/application/) -- Registering components
-- **Components:**
-  - [Components Index](../index) -- All built-in components
-- **Helpers:**
-  - [Socket.IO Helper](/extensions/helpers/socket-io/) -- Full `SocketIOServerHelper` + `SocketIOClientHelper` API reference
-- **External Resources:**
-  - [Socket.IO Documentation](https://socket.io/docs/) -- Official docs
-  - [Socket.IO Redis Adapter](https://socket.io/docs/v4/redis-adapter/) -- Horizontal scaling guide
-  - [@socket.io/bun-engine](https://github.com/socketio/bun-engine) -- Bun runtime support
-- **Tutorials:**
-  - [Real-Time Chat](/guides/tutorials/realtime-chat) -- Building a chat app with Socket.IO
-- **Changelog:**
-  - [2026-02-06: Socket.IO Integration Fix](/changelogs/2026-02-06-socket-io-integration-fix) -- Lifecycle timing fix + Bun runtime support
+### Scale Redis beyond a single node
+
+Swap `RedisSingleHelper` for `RedisClusterHelper` or `RedisSentinelHelper`. Both satisfy the `IRedisHelper` interface the component validates against. See [Redis connection alternatives](./usage#redis-connection-alternatives) for the full example.
+
+```typescript
+import { RedisClusterHelper } from '@venizia/ignis-helpers';
+
+this.bind({ key: SocketIOBindingKeys.REDIS_CONNECTION }).toValue(
+  new RedisClusterHelper({
+    name: 'socket-io-redis-cluster',
+    nodes: [{ host: 'redis-node-1', port: 6379 }],
+    autoConnect: false,
+  }),
+);
+```
+
+### Look up a default, binding key, or event name
+
+Every `DEFAULT_SERVER_OPTIONS` field, the binding key table, system events, default rooms, and the client state machine live in the [Full Reference](./api#configuration-reference).
+
+## See also
+
+- [Usage & Examples](./usage) - full setup steps, server-side usage, client helper, advanced patterns
+- [Full Reference](./api) - architecture, configuration reference, method signatures, internals, types
+- [Error Reference](./errors) - error conditions and troubleshooting
+- [Socket.IO Helper](/extensions/helpers/socket-io/) - full `SocketIOServerHelper` + `SocketIOClientHelper` API reference
+- [WebSocket Component](../websocket/) - Bun-only alternative
+- [Real-Time Chat tutorial](/guides/tutorials/realtime-chat) - building a chat app with Socket.IO
+- [Socket.IO Documentation](https://socket.io/docs/) - official docs
+- [Socket.IO Redis Adapter](https://socket.io/docs/v4/redis-adapter/) - horizontal scaling guide
+- [@socket.io/bun-engine](https://github.com/socketio/bun-engine) - Bun runtime support
+- [2026-02-06: Socket.IO Integration Fix](/changelogs/2026-02-06-socket-io-integration-fix) - lifecycle timing fix + Bun runtime support
 
 **Files:**
 
-- [`packages/core/src/components/socket-io/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/socket-io/component.ts) -- `SocketIOComponent`
-- [`packages/core/src/components/socket-io/common/keys.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/socket-io/common/keys.ts) -- `SocketIOBindingKeys`
-- [`packages/core/src/components/socket-io/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/socket-io/common/types.ts) -- `IServerOptions`, `DEFAULT_SERVER_OPTIONS`
+- [`packages/core-server/src/components/socket-io/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/socket-io/component.ts) - `SocketIOComponent`
+- [`packages/core-server/src/components/socket-io/common/keys.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/socket-io/common/keys.ts) - `SocketIOBindingKeys`
+- [`packages/core-server/src/components/socket-io/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/socket-io/common/types.ts) - `IServerOptions`, `DEFAULT_SERVER_OPTIONS`