@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/extensions/components/websocket/index.md

@@ -1,459 +1,127 @@
-# WebSocket -- Setup & Configuration
+---
+title: WebSocket Component
+description: Wires WebSocketServerHelper into the running Bun server, with Redis Pub/Sub scaling and post-connection authentication
+difficulty: intermediate
+---
 
-> Bun-native real-time, bidirectional communication using pure WebSocket -- with Redis Pub/Sub for horizontal scaling, application-level heartbeat, and post-connection authentication.
+# WebSocket Component
 
-> [!IMPORTANT]
-> **Bun only.** The WebSocket component will throw an error if the runtime is Node.js. For Node.js support, use the [Socket.IO Component](../socket-io/) instead.
-
-## Quick Reference
-
-| Item | Value |
-|------|-------|
-| **Package** | `@venizia/ignis` (core component) + `@venizia/ignis-helpers` (helper classes) |
-| **Component** | `WebSocketComponent` |
-| **Server Helper** | [`WebSocketServerHelper`](/extensions/helpers/websocket/) |
-| **Emitter Helper** | `WebSocketEmitter` (standalone Redis publisher) |
-| **Runtimes** | Bun only (throws on Node.js) |
-| **Scaling** | Redis Pub/Sub (ioredis -- single or Cluster) |
-
-#### Import Paths
+`WebSocketComponent` registers a Bun-native WebSocket server on your application by creating and binding a [`WebSocketServerHelper`](/extensions/helpers/websocket/) once the HTTP server is listening.
 
 > [!IMPORTANT]
-> `WebSocketComponent` and `WebSocketBindingKeys` are **not** exported from the `@venizia/ignis` barrel. You must import from the `@venizia/ignis/websocket` subpath.
-
-```typescript
-// From core -- subpath import (NOT from '@venizia/ignis')
-import {
-  WebSocketComponent,
-  WebSocketBindingKeys,
-} from '@venizia/ignis/websocket';
-
-// From helpers -- types, helpers, constants (exported from main entry)
-import {
-  WebSocketServerHelper,
-  WebSocketEmitter,
-  WebSocketDefaults,
-  WebSocketEvents,
-  WebSocketChannels,
-  WebSocketClientStates,
-  WebSocketMessageTypes,
-} from '@venizia/ignis-helpers';
-
-import type {
-  IWebSocketServerOptions,
-  IWebSocketEmitterOptions,
-  IWebSocketClient,
-  IWebSocketMessage,
-  IRedisSocketMessage,
-  IBunWebSocketConfig,
-  TWebSocketAuthenticateFn,
-  TWebSocketValidateRoomFn,
-  TWebSocketClientConnectedFn,
-  TWebSocketClientDisconnectedFn,
-  TWebSocketMessageHandler,
-  TWebSocketOutboundTransformer,
-  TWebSocketHandshakeFn,
-} from '@venizia/ignis-helpers';
-```
-
-> [!NOTE]
-> `IServerOptions` (the core component's subset type) is **not** exported from `@venizia/ignis` or `@venizia/ignis/websocket`. Only `WebSocketBindingKeys` and `WebSocketComponent` are exported from the core subpath. All helper types, constants, and classes are imported from `@venizia/ignis-helpers`.
+> **Bun only.** `binding()` throws if the runtime is Node.js. For Node.js support, use the [Socket.IO Component](../socket-io/) instead.
 
-### Use Cases
+## In one example
 
-- Live notifications and alerts
-- Real-time chat and messaging
-- Collaborative editing (docs, whiteboards)
-- Live data streams (dashboards, monitoring)
-- Multiplayer game state synchronization
-- IoT device communication
-- Background job progress updates (via `WebSocketEmitter`)
-- Cross-service event broadcasting (via `WebSocketEmitter`)
-
-## Setup
-
-### Step 1: Install Dependencies
-
-```bash
-# Core dependency (already included via @venizia/ignis)
-# ioredis is required for Redis Pub/Sub
-bun add ioredis
-```
-
-### Step 2: Bind Required Services
-
-In your application's `preConfigure()` method, bind the required services and register the component:
-
-#### Full Setup Example
 ```typescript
 import { BaseApplication } from '@venizia/ignis';
-import {
-  WebSocketComponent,
-  WebSocketBindingKeys,
-} from '@venizia/ignis/websocket';
-import {
-  RedisSingleHelper,
-} from '@venizia/ignis-helpers';
-import type {
-  TWebSocketAuthenticateFn,
-  TWebSocketValidateRoomFn,
-  TWebSocketClientConnectedFn,
-  TWebSocketClientDisconnectedFn,
-  TWebSocketMessageHandler,
-  TWebSocketOutboundTransformer,
-  TWebSocketHandshakeFn,
-  IBunWebSocketConfig,
-  ValueOrPromise,
-} from '@venizia/ignis-helpers';
+import { WebSocketComponent, WebSocketBindingKeys } from '@venizia/ignis/websocket';
+import { RedisSingleHelper, TWebSocketAuthenticateFn, ValueOrPromise } from '@venizia/ignis-helpers';
 
 export class Application extends BaseApplication {
-  private redisHelper: RedisSingleHelper;
-
   preConfigure(): ValueOrPromise<void> {
-    this.setupWebSocket();
-    // ... other setup
-  }
-
-  setupWebSocket() {
-    // 1. Redis connection (required for cross-instance messaging)
-    this.redisHelper = new RedisSingleHelper({
-      name: 'websocket-redis',
-      host: process.env.REDIS_HOST ?? 'localhost',
-      port: +(process.env.REDIS_PORT ?? 6379),
-      password: process.env.REDIS_PASSWORD,
-      autoConnect: false,
-    });
-
-    this.bind<RedisSingleHelper>({
-      key: WebSocketBindingKeys.REDIS_CONNECTION,
-    }).toValue(this.redisHelper);
-
-    // 2. Authentication handler (required)
-    const authenticateFn: TWebSocketAuthenticateFn = async (data) => {
-      const token = data.token as string;
-      if (!token) return null;
-
-      const user = await verifyJWT(token);
-      if (!user) return null;
-
-      return { userId: user.id, metadata: { role: user.role } };
-    };
-
-    this.bind<TWebSocketAuthenticateFn>({
-      key: WebSocketBindingKeys.AUTHENTICATE_HANDLER,
-    }).toValue(authenticateFn);
-
-    // 3. Room validation handler (optional -- joins rejected without this)
-    const validateRoomFn: TWebSocketValidateRoomFn = ({ clientId, userId, rooms }) => {
-      return rooms.filter(room => room.startsWith('public-'));
-    };
-
-    this.bind<TWebSocketValidateRoomFn>({
-      key: WebSocketBindingKeys.VALIDATE_ROOM_HANDLER,
-    }).toValue(validateRoomFn);
-
-    // 4. Client connected handler (optional)
-    const clientConnectedFn: TWebSocketClientConnectedFn = ({ clientId, userId }) => {
-      console.log('Client connected:', clientId, userId);
-    };
-
-    this.bind<TWebSocketClientConnectedFn>({
-      key: WebSocketBindingKeys.CLIENT_CONNECTED_HANDLER,
-    }).toValue(clientConnectedFn);
-
-    // 5. Client disconnected handler (optional)
-    const clientDisconnectedFn: TWebSocketClientDisconnectedFn = ({ clientId, userId }) => {
-      console.log('Client disconnected:', clientId, userId);
-    };
-
-    this.bind<TWebSocketClientDisconnectedFn>({
-      key: WebSocketBindingKeys.CLIENT_DISCONNECTED_HANDLER,
-    }).toValue(clientDisconnectedFn);
-
-    // 6. Message handler (optional -- for custom events)
-    const messageHandler: TWebSocketMessageHandler = ({ clientId, userId, message }) => {
-      console.log('Custom event:', message.event, message.data);
-    };
-
-    this.bind<TWebSocketMessageHandler>({
-      key: WebSocketBindingKeys.MESSAGE_HANDLER,
-    }).toValue(messageHandler);
-
-    // 7. Outbound transformer (optional -- for per-client encryption)
-    const outboundTransformer: TWebSocketOutboundTransformer = async ({ client, event, data }) => {
-      if (!client.encrypted) return null;
-      // Encrypt using client's derived AES key (from ECDH handshake)
-      const encrypted = await encryptForClient(client.id, JSON.stringify({ event, data }));
-      return { event: 'encrypted', data: encrypted };
-    };
-
-    this.bind<TWebSocketOutboundTransformer>({
-      key: WebSocketBindingKeys.OUTBOUND_TRANSFORMER,
-    }).toValue(outboundTransformer);
-
-    // 8. Handshake handler (optional -- required when requireEncryption is true)
-    const handshakeFn: TWebSocketHandshakeFn = async ({ clientId, data }) => {
-      const clientPubKey = data.publicKey as string;
-      if (!clientPubKey) return null; // Reject -- no public key provided
-      const salt = crypto.getRandomValues(new Uint8Array(32));
-      const saltB64 = Buffer.from(salt).toString('base64');
-      const aesKey = await deriveSharedSecret(clientPubKey, salt);
-      storeClientKey(clientId, aesKey);
-      return { serverPublicKey: serverPublicKeyB64, salt: saltB64 };
+    // 1. Redis connection (required, used for cross-instance Pub/Sub)
+    this.bind({ key: WebSocketBindingKeys.REDIS_CONNECTION }).toValue(
+      new RedisSingleHelper({ name: 'websocket-redis', host: 'localhost', port: 6379, autoConnect: false }),
+    );
+
+    // 2. Authenticate handler (required, decides accept/reject per client)
+    const authenticateFn: TWebSocketAuthenticateFn = async data => {
+      const user = await verifyJWT(data.token as string);
+      return user ? { userId: user.id } : null;
     };
+    this.bind({ key: WebSocketBindingKeys.AUTHENTICATE_HANDLER }).toValue(authenticateFn);
 
-    this.bind<TWebSocketHandshakeFn>({
-      key: WebSocketBindingKeys.HANDSHAKE_HANDLER,
-    }).toValue(handshakeFn);
-
-    // 9. Server options (optional -- customize defaults)
-    this.bind({
-      key: WebSocketBindingKeys.SERVER_OPTIONS,
-    }).toValue({
-      identifier: 'my-app-websocket',
-      requireEncryption: true,
-    });
-
-    // 10. Register the component
+    // 3. Register (binding() validates the two bindings above and defers the rest)
     this.component(WebSocketComponent);
   }
 }
 ```
 
-## Configuration
+`WebSocketComponent` and `WebSocketBindingKeys` come from the `@venizia/ignis/websocket` subpath. They are **not** exported from the `@venizia/ignis` root barrel. Helper types (`TWebSocketAuthenticateFn`, `WebSocketServerHelper`, `WebSocketEmitter`, `WebSocketDefaults`, ...) come from `@venizia/ignis-helpers`.
 
-The core component's `IServerOptions` interface controls the WebSocket server setup. Default values come from `DEFAULT_SERVER_OPTIONS` and `WebSocketDefaults`:
+## How it works
 
-```typescript
-{
-  identifier: 'WEBSOCKET_SERVER',
-  path: '/ws',                         // WebSocketDefaults.PATH
-  defaultRooms: [                      // Joined automatically after auth
-    'ws-default',                      // WebSocketDefaults.ROOM
-    'ws-notification',                 // WebSocketDefaults.NOTIFICATION_ROOM
-  ],
-  heartbeatInterval: 30000,            // 30 seconds (WebSocketDefaults.HEARTBEAT_INTERVAL)
-  heartbeatTimeout: 90000,             // 90 seconds (WebSocketDefaults.HEARTBEAT_TIMEOUT)
-  requireEncryption: false,
-  serverOptions: {                     // Bun native WebSocket config (IBunWebSocketConfig)
-    sendPings: true,                   // WebSocketDefaults.SEND_PINGS
-    idleTimeout: 60,                   // WebSocketDefaults.IDLE_TIMEOUT (seconds)
-    maxPayloadLength: 131072,          // WebSocketDefaults.MAX_PAYLOAD_LENGTH (128 KB)
-  },
-}
-```
+- **Two-phase startup solves a timing problem.** `binding()` runs during `initialize()`, before any Bun server exists. It validates bindings and registers a post-start hook. The actual `WebSocketServerHelper` is only constructed once `executePostStartHooks()` runs, after `Bun.serve()` has produced a live server instance.
+- **Two bindings gate startup.** `REDIS_CONNECTION` and `AUTHENTICATE_HANDLER` are both required. `REDIS_CONNECTION` must be an `AbstractRedisHelper` instance. `binding()` throws synchronously if either is missing or the wrong type - before the post-start hook is even registered.
+- **Runtime is checked first, fast.** `RuntimeModules.detect()` runs at the top of `binding()`. On Node.js it throws immediately, so a misconfigured app fails at startup, not on first connection.
+- **The instance appears only after start.** The post-start hook binds the configured helper to `WebSocketBindingKeys.WEBSOCKET_INSTANCE`. It does not exist during DI construction. Inject it lazily from a service or controller, never via `@inject` in a constructor.
+- **A custom `fetch` handler splits traffic.** After the post-start hook runs, `server.reload()` swaps in a new handler. It routes WebSocket upgrade requests - `GET <path>` with an `Upgrade: websocket` header - to Bun's native handler.
+  - Everything else goes to the existing Hono server, unchanged.
 
-> [!NOTE]
-> The `DEFAULT_SERVER_OPTIONS` in the core component only sets `identifier` and `path`. The remaining defaults (`defaultRooms`, `heartbeatInterval`, `heartbeatTimeout`, `serverOptions`) come from `WebSocketDefaults` applied by the helper constructor.
+## Common tasks
 
-To customize options, bind a partial options object before registering the component:
+### Customize the server path, rooms, and heartbeat
 
-#### Custom Server Options Example
-```typescript
-import { WebSocketBindingKeys } from '@venizia/ignis/websocket';
+Bind a partial options object to `SERVER_OPTIONS` before registering the component. Unset fields fall back to `WebSocketDefaults`.
 
-this.bind({
-  key: WebSocketBindingKeys.SERVER_OPTIONS,
-}).toValue({
-  identifier: 'my-app-websocket',
+```typescript
+this.bind({ key: WebSocketBindingKeys.SERVER_OPTIONS }).toValue({
   path: '/realtime',
-  defaultRooms: ['general', 'announcements'],  // Override default rooms
-  heartbeatInterval: 20000,                     // More frequent heartbeats
-  heartbeatTimeout: 60000,                      // Shorter timeout
-  requireEncryption: true,                      // Require ECDH handshake
-  serverOptions: {
-    maxPayloadLength: 2097152,                  // 2 MB max payload
-    backpressureLimit: 2097152,                 // 2 MB backpressure limit
-  },
+  defaultRooms: ['general', 'announcements'],
+  heartbeatInterval: 20_000,
+  heartbeatTimeout: 60_000,
 });
 ```
 
-> [!NOTE]
-> `authTimeout` and `encryptedBatchLimit` are properties of the helper's `IWebSocketServerOptions`, not the core component's `IServerOptions`. The component uses the helper defaults for those (`5000` ms and `10` respectively). If you need to customize them, you must set them on the helper directly (not via binding keys).
-
-### `WebSocketDefaults` Constants
-
-All tunable defaults are defined in the `WebSocketDefaults` class. The helper falls back to these when no explicit value is provided.
-
-| Constant | Value | Description |
-|----------|-------|-------------|
-| `PATH` | `'/ws'` | Default WebSocket endpoint path |
-| `ROOM` | `'ws-default'` | Default room name |
-| `NOTIFICATION_ROOM` | `'ws-notification'` | Default notification room name |
-| `BROADCAST_TOPIC` | `'ws:internal:broadcast'` | Internal Bun pub/sub broadcast topic |
-| `MAX_PAYLOAD_LENGTH` | `131072` (128 KB) | Maximum message payload size |
-| `IDLE_TIMEOUT` | `60` | Bun idle timeout in seconds |
-| `BACKPRESSURE_LIMIT` | `1048576` (1 MB) | Bun backpressure limit |
-| `SEND_PINGS` | `true` | Enable WebSocket pings |
-| `PUBLISH_TO_SELF` | `false` | Whether server receives its own publishes |
-| `AUTH_TIMEOUT` | `5000` (5 s) | Time to authenticate before disconnect |
-| `HEARTBEAT_INTERVAL` | `30000` (30 s) | Interval between heartbeat sweeps |
-| `HEARTBEAT_TIMEOUT` | `90000` (90 s) | Disconnect after 3 missed heartbeats |
-| `ENCRYPTED_BATCH_LIMIT` | `10` | Max concurrent encryption operations |
-
-> [!TIP]
-> `MAX_PAYLOAD_LENGTH`, `IDLE_TIMEOUT`, `BACKPRESSURE_LIMIT`, `SEND_PINGS`, and `PUBLISH_TO_SELF` are Bun-native WebSocket settings passed via `serverOptions` inside `IServerOptions`. The rest are application-level settings on `IWebSocketServerOptions` (the helper constructor options).
-
-#### Full `IBunWebSocketConfig` Interface
-```typescript
-/** Bun WebSocket native configuration options */
-interface IBunWebSocketConfig {
-  perMessageDeflate?: boolean;
-  maxPayloadLength?: number;          // Default: 128 KB (131072)
-  idleTimeout?: number;               // Default: 60 s
-  backpressureLimit?: number;         // Default: 1 MB (1048576)
-  closeOnBackpressureLimit?: boolean;
-  sendPings?: boolean;                // Default: true
-  publishToSelf?: boolean;            // Default: false
-}
-```
+### Add optional lifecycle callbacks
 
-These options are passed directly to Bun's native WebSocket handler. Set them via `serverOptions` inside the options bound to `WebSocketBindingKeys.SERVER_OPTIONS`.
+`VALIDATE_ROOM_HANDLER`, `CLIENT_CONNECTED_HANDLER`, `CLIENT_DISCONNECTED_HANDLER`, and `MESSAGE_HANDLER` are all optional bindings.
 
-#### Full `IServerOptions` Interface (Core Component)
 ```typescript
-interface IServerOptions {
-  identifier: string;                  // Default: 'WEBSOCKET_SERVER'
-  path?: string;                       // Default: '/ws' (from WebSocketDefaults.PATH)
-  defaultRooms?: string[];             // Default: ['ws-default', 'ws-notification']
-  serverOptions?: IBunWebSocketConfig; // Bun native WebSocket config
-  heartbeatInterval?: number;          // Default: 30000 (30 s)
-  heartbeatTimeout?: number;           // Default: 90000 (90 s)
-  requireEncryption?: boolean;         // Default: false
-}
+this.bind({ key: WebSocketBindingKeys.VALIDATE_ROOM_HANDLER }).toValue(
+  ({ rooms }: { rooms: string[] }) => rooms.filter(room => room.startsWith('public-')),
+);
 ```
 
-> [!NOTE]
-> `IServerOptions` is the **core component's** options type. It is a subset of the helper's `IWebSocketServerOptions`, which additionally includes `server`, `redisConnection`, callback functions, `authTimeout`, and `encryptedBatchLimit`. The component fills in those extra fields from the DI container before constructing the helper.
-
-## Binding Keys
-
-| Binding Key | Constant | Type | Required | Default |
-|------------|----------|------|----------|---------|
-| `@app/websocket/server-options` | `WebSocketBindingKeys.SERVER_OPTIONS` | `Partial<IServerOptions>` | No | See [Configuration](#configuration) |
-| `@app/websocket/redis-connection` | `WebSocketBindingKeys.REDIS_CONNECTION` | `IRedisHelper` | **Yes** | `null` |
-| `@app/websocket/authenticate-handler` | `WebSocketBindingKeys.AUTHENTICATE_HANDLER` | `TWebSocketAuthenticateFn` | **Yes** | `null` |
-| `@app/websocket/validate-room-handler` | `WebSocketBindingKeys.VALIDATE_ROOM_HANDLER` | `TWebSocketValidateRoomFn` | No | `null` |
-| `@app/websocket/client-connected-handler` | `WebSocketBindingKeys.CLIENT_CONNECTED_HANDLER` | `TWebSocketClientConnectedFn` | No | `null` |
-| `@app/websocket/client-disconnected-handler` | `WebSocketBindingKeys.CLIENT_DISCONNECTED_HANDLER` | `TWebSocketClientDisconnectedFn` | No | `null` |
-| `@app/websocket/message-handler` | `WebSocketBindingKeys.MESSAGE_HANDLER` | `TWebSocketMessageHandler` | No | `null` |
-| `@app/websocket/outbound-transformer` | `WebSocketBindingKeys.OUTBOUND_TRANSFORMER` | `TWebSocketOutboundTransformer` | No | `null` |
-| `@app/websocket/handshake-handler` | `WebSocketBindingKeys.HANDSHAKE_HANDLER` | `TWebSocketHandshakeFn` | No* | `null` |
-| `@app/websocket/instance` | `WebSocketBindingKeys.WEBSOCKET_INSTANCE` | `WebSocketServerHelper` | -- | *Set by component* |
-
-> [!NOTE]
-> `HANDSHAKE_HANDLER` is required when `IServerOptions.requireEncryption` is `true`. It performs ECDH key exchange during authentication.
-
-> [!NOTE]
-> `WEBSOCKET_INSTANCE` is **not** set by you -- the component creates and binds it automatically after the server starts. Inject it in services/controllers to interact with WebSocket.
-
-### Callback Type Signatures
-
-| Binding Key | Callback Type | Required | Description |
-|-------------|--------------|----------|-------------|
-| `AUTHENTICATE_HANDLER` | `TWebSocketAuthenticateFn` | **Yes** | Returns <code v-pre>{ userId, metadata }</code> or `null`/`false` to reject |
-| `VALIDATE_ROOM_HANDLER` | `TWebSocketValidateRoomFn` | No | Filters requested rooms, returns allowed rooms |
-| `CLIENT_CONNECTED_HANDLER` | `TWebSocketClientConnectedFn` | No | Called after successful authentication |
-| `CLIENT_DISCONNECTED_HANDLER` | `TWebSocketClientDisconnectedFn` | No | Called on disconnect (after cleanup) |
-| `MESSAGE_HANDLER` | `TWebSocketMessageHandler` | No | Handles non-system messages from authenticated clients |
-| `OUTBOUND_TRANSFORMER` | `TWebSocketOutboundTransformer` | No | Transforms outbound messages (e.g., per-client encryption) |
-| `HANDSHAKE_HANDLER` | `TWebSocketHandshakeFn` | When `requireEncryption: true` | Returns <code v-pre>{ serverPublicKey, salt }</code> or `null`/`false` to reject |
-
-#### `TWebSocketAuthenticateFn`
-```typescript
-type TWebSocketAuthenticateFn<
-  AuthDataType extends Record<string, unknown> = Record<string, unknown>,
-  MetadataType extends Record<string, unknown> = Record<string, unknown>,
-> = (
-  opts: AuthDataType,
-) => ValueOrPromise<{ userId?: string; metadata?: MetadataType } | null | false>;
-```
-
-Receives the `data` field from the client's `authenticate` event. Return <code v-pre>{ userId, metadata }</code> on success, or `null`/`false` to reject (closes with code `4003`).
-
-#### `TWebSocketValidateRoomFn`
-```typescript
-type TWebSocketValidateRoomFn = (opts: {
-  clientId: string;
-  userId?: string;
-  rooms: string[];
-}) => ValueOrPromise<string[]>;
-```
-
-Called when a client sends a `join` event. Receives the sanitized room list (internal `ws:` prefix rooms are already filtered out). Return the subset of rooms the client is allowed to join.
-
 > [!WARNING]
-> If no `validateRoomFn` is bound, **all join requests are rejected**. You must bind this handler if you want clients to join custom rooms.
+> Without `VALIDATE_ROOM_HANDLER` bound, **every** client `join` request is rejected.
 
-#### `TWebSocketClientConnectedFn`
-```typescript
-type TWebSocketClientConnectedFn<
-  MetadataType extends Record<string, unknown> = Record<string, unknown>,
-> = (opts: {
-  clientId: string;
-  userId?: string;
-  metadata?: MetadataType;
-}) => ValueOrPromise<void>;
-```
+### Inject the running instance in a service
 
-Called after a client has been fully authenticated, joined default rooms, and received the `connected` event. Errors thrown here are caught and logged -- they do not disconnect the client.
+`WEBSOCKET_INSTANCE` is bound after the server starts, so resolve it lazily rather than through the constructor.
 
-#### `TWebSocketClientDisconnectedFn`
 ```typescript
-type TWebSocketClientDisconnectedFn = (opts: {
-  clientId: string;
-  userId?: string;
-}) => ValueOrPromise<void>;
+private get ws(): WebSocketServerHelper {
+  return this.application.get<WebSocketServerHelper>({
+    key: WebSocketBindingKeys.WEBSOCKET_INSTANCE,
+  });
+}
 ```
 
-Called after internal cleanup (auth timer cleared, removed from user/room indexes, removed from clients map). Errors thrown here are caught and logged.
+### Send from a process with no WebSocket server
 
-#### `TWebSocketMessageHandler`
-```typescript
-type TWebSocketMessageHandler = (opts: {
-  clientId: string;
-  userId?: string;
-  message: IWebSocketMessage;
-}) => ValueOrPromise<void>;
-```
+Background workers, cron jobs, and other microservices use the standalone `WebSocketEmitter` - it uses the same Redis connection with no local server required.
 
-Called for any message from an authenticated client whose `event` is not a system event (`authenticate`, `connected`, `disconnect`, `join`, `leave`, `error`, `heartbeat`, `encrypted`). If no handler is bound, non-system messages are silently dropped.
-
-#### `TWebSocketOutboundTransformer`
 ```typescript
-type TWebSocketOutboundTransformer<
-  DataType = unknown,
-  MetadataType extends Record<string, unknown> = Record<string, unknown>,
-> = (opts: {
-  client: IWebSocketClient<MetadataType>;
-  event: string;
-  data: DataType;
-}) => ValueOrPromise<TNullable<{ event: string; data: DataType }>>;
+import { WebSocketEmitter } from '@venizia/ignis-helpers';
+
+const emitter = new WebSocketEmitter({ redisConnection: redisHelper });
+await emitter.configure();
+await emitter.toRoom({ room: 'dashboard-viewers', event: 'data:update', data: { cpu: 42 } });
 ```
 
-Intercepts every outbound message **to encrypted clients only** before `socket.send()`. Return `null` to send the original <code v-pre>{ event, data }</code> unchanged, or return a transformed <code v-pre>{ event, data }</code> (e.g., <code v-pre>{ event: 'encrypted', data: ciphertext }</code>).
+### Require encrypted sessions
 
-> [!NOTE]
-> The transformer is only called for clients where `client.encrypted === true`. Non-encrypted clients bypass this entirely (zero overhead).
+Set `requireEncryption: true` and bind a `HANDSHAKE_HANDLER`. It becomes required the moment encryption is turned on.
 
-#### `TWebSocketHandshakeFn`
 ```typescript
-type TWebSocketHandshakeFn<
-  AuthDataType extends Record<string, unknown> = Record<string, unknown>,
-> = (opts: {
-  clientId: string;
-  userId?: string;
-  data: AuthDataType;
-}) => ValueOrPromise<{ serverPublicKey: string; salt: string } | null | false>;
+this.bind({ key: WebSocketBindingKeys.SERVER_OPTIONS }).toValue({ requireEncryption: true });
+this.bind({ key: WebSocketBindingKeys.HANDSHAKE_HANDLER }).toValue(handshakeFn);
 ```
 
-Called during authentication when `requireEncryption` is `true`. Receives the same `data` payload as `authenticateFn`. Return <code v-pre>{ serverPublicKey, salt }</code> on success -- these are included in the `connected` event sent to the client. Return `null`/`false` to reject (closes with code `4004`).
+## See also
+
+- [Usage & Examples](./usage) - injecting the helper, `WebSocketEmitter`, wire protocol, client tracking, delivery strategy
+- [Full Reference](./api) - lifecycle diagram, binding keys, configuration options, `WebSocketEmitter` API, internals
+- [Error Reference](./errors) - error conditions and troubleshooting
+- [WebSocketServerHelper](/extensions/helpers/websocket/) - the helper this component wires in
+- [Socket.IO Component](../socket-io/) - Node.js-compatible alternative
+- [Bun WebSocket Documentation](https://bun.sh/docs/api/websockets) - official Bun WebSocket API reference
 
-## See Also
+**Files:**
 
-- [Usage & Examples](./usage) - Server-side usage, emitter, wire protocol, client tracking, and delivery strategy
-- [API Reference](./api) - Architecture, WebSocketEmitter API, and internals
-- [Error Reference](./errors) - Error conditions table and troubleshooting
-- [WebSocketServerHelper](/extensions/helpers/websocket/) - Helper API documentation
-- [Socket.IO Component](../socket-io/) - Node.js-compatible alternative with Socket.IO
-- [Bun WebSocket Documentation](https://bun.sh/docs/api/websockets) - Official Bun WebSocket API reference
+- [`packages/core-server/src/components/websocket/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/websocket/component.ts) - `WebSocketComponent`
+- [`packages/core-server/src/components/websocket/common/keys.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/websocket/common/keys.ts) - `WebSocketBindingKeys`
+- [`packages/core-server/src/components/websocket/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/websocket/common/types.ts) - `IServerOptions`, `DEFAULT_SERVER_OPTIONS`
+- [`packages/core-server/src/components/websocket/handlers/bun.handler.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/components/websocket/handlers/bun.handler.ts) - `createBunFetchHandler`