@veloxts/events 0.6.51

package/GUIDE.md

@@ -0,0 +1,199 @@
+# @veloxts/events Guide
+
+## Drivers
+
+### WebSocket Driver
+
+Real-time broadcasting via WebSocket. Supports Redis pub/sub for horizontal scaling.
+
+```typescript
+import { eventsPlugin } from '@veloxts/events';
+
+// Basic setup (single instance)
+app.use(eventsPlugin({
+  driver: 'ws',
+  config: {
+    path: '/ws',
+    pingInterval: 30000,
+  },
+}));
+
+// With Redis for horizontal scaling
+app.use(eventsPlugin({
+  driver: 'ws',
+  config: {
+    path: '/ws',
+    redis: process.env.REDIS_URL,
+  },
+}));
+```
+
+## Broadcasting Events
+
+```typescript
+// Broadcast to a channel
+await ctx.broadcast({
+  channel: 'orders.123',
+  event: 'order.shipped',
+  data: { trackingNumber: 'TRACK123' },
+});
+
+// Broadcast to all except sender
+await ctx.broadcast({
+  channel: 'chat.room-1',
+  event: 'message',
+  data: { text: 'Hello!' },
+  except: ctx.socketId,  // Exclude sender
+});
+```
+
+## Channel Types
+
+### Public Channels
+
+Anyone can subscribe.
+
+```typescript
+// Server
+await ctx.broadcast({
+  channel: 'announcements',
+  event: 'new-feature',
+  data: { title: 'New Feature!' },
+});
+
+// Client
+socket.subscribe('announcements');
+```
+
+### Private Channels
+
+Require authorization. Prefix with `private-`.
+
+```typescript
+// Server - requires authorization middleware
+await ctx.broadcast({
+  channel: 'private-user.123',
+  event: 'notification',
+  data: { message: 'You have a new message' },
+});
+```
+
+### Presence Channels
+
+Track who's online. Prefix with `presence-`.
+
+```typescript
+// Server
+await ctx.broadcast({
+  channel: 'presence-chat.room-1',
+  event: 'typing',
+  data: { userId: '123' },
+});
+
+// Client receives member_added/member_removed events automatically
+```
+
+## Client Integration
+
+### Browser Client
+
+```typescript
+const socket = new WebSocket('ws://localhost:3030/ws');
+
+socket.onopen = () => {
+  // Subscribe to channel
+  socket.send(JSON.stringify({
+    type: 'subscribe',
+    channel: 'orders.123',
+  }));
+};
+
+socket.onmessage = (event) => {
+  const message = JSON.parse(event.data);
+
+  if (message.type === 'event') {
+    console.log(`${message.event}:`, message.data);
+  }
+};
+
+// Unsubscribe
+socket.send(JSON.stringify({
+  type: 'unsubscribe',
+  channel: 'orders.123',
+}));
+```
+
+### Presence Channels (Client)
+
+```typescript
+// Join with user info
+socket.send(JSON.stringify({
+  type: 'subscribe',
+  channel: 'presence-chat.room-1',
+  data: { id: '123', name: 'John' },
+}));
+
+// Handle presence events
+socket.onmessage = (event) => {
+  const message = JSON.parse(event.data);
+
+  if (message.event === 'member_added') {
+    console.log('User joined:', message.data);
+  }
+  if (message.event === 'member_removed') {
+    console.log('User left:', message.data);
+  }
+};
+```
+
+## Server API
+
+```typescript
+// Get subscribers for a channel
+const subscribers = await ctx.events.getSubscribers('orders.123');
+
+// Get presence members
+const members = await ctx.events.getPresenceMembers('presence-chat.room-1');
+
+// Get connection count
+const count = await ctx.events.getConnectionCount('orders.123');
+
+// Get all active channels
+const channels = await ctx.events.getChannels();
+```
+
+## HTTP Upgrade (Manual Setup)
+
+If not using the plugin, handle WebSocket upgrade manually:
+
+```typescript
+import { createWsDriver } from '@veloxts/events';
+
+const events = await createWsDriver({ path: '/ws' });
+
+// In your HTTP server
+server.on('upgrade', (request, socket, head) => {
+  if (request.url === '/ws') {
+    events.handleUpgrade(request, socket, head);
+  }
+});
+```
+
+## Scaling with Redis
+
+For multi-instance deployments, events are broadcast via Redis pub/sub:
+
+```typescript
+app.use(eventsPlugin({
+  driver: 'ws',
+  config: {
+    path: '/ws',
+    redis: process.env.REDIS_URL,
+  },
+}));
+```
+
+All instances subscribe to a shared Redis channel. When you broadcast:
+1. Event is sent to local WebSocket clients
+2. Event is published to Redis
+3. Other instances receive from Redis and broadcast to their clients

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 VeloxTS Framework Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @veloxts/events
+
+> **Early Preview** - APIs may change before v1.0.
+
+Real-time event broadcasting via WebSocket with optional Redis pub/sub for scaling.
+
+## Installation
+
+```bash
+npm install @veloxts/events
+```
+
+## Quick Start
+
+```typescript
+import { eventsPlugin } from '@veloxts/events';
+
+app.use(eventsPlugin({ driver: 'ws', path: '/ws' }));
+
+// Broadcast an event
+await ctx.broadcast({
+  channel: 'orders.123',
+  event: 'order.shipped',
+  data: { trackingNumber: 'TRACK123' },
+});
+```
+
+See [GUIDE.md](./GUIDE.md) for detailed documentation.
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Channel Authentication
+ *
+ * HMAC-SHA256 signing for secure channel authorization.
+ * Prevents forgery of auth tokens for private/presence channels.
+ */
+/**
+ * Channel authentication signature generator.
+ * Uses HMAC-SHA256 for cryptographic security.
+ */
+export interface ChannelAuthSigner {
+    /**
+     * Generate a signed authentication token for a channel subscription.
+     *
+     * @param socketId - The unique socket identifier
+     * @param channel - The channel name being subscribed to
+     * @param channelData - Optional presence channel member data (JSON string)
+     * @returns The HMAC signature (hex-encoded)
+     */
+    sign(socketId: string, channel: string, channelData?: string): string;
+    /**
+     * Verify a signature is valid for the given parameters.
+     * Uses timing-safe comparison to prevent timing attacks.
+     *
+     * @param signature - The signature to verify
+     * @param socketId - The socket ID
+     * @param channel - The channel name
+     * @param channelData - Optional presence channel data
+     * @returns true if signature is valid
+     */
+    verify(signature: string, socketId: string, channel: string, channelData?: string): boolean;
+}
+/**
+ * Create a channel authentication signer with HMAC-SHA256.
+ *
+ * @param secret - The secret key (minimum 16 characters)
+ * @returns A signer instance
+ * @throws If secret is too short
+ *
+ * @example
+ * ```typescript
+ * const signer = createChannelAuthSigner(process.env.EVENTS_SECRET!);
+ *
+ * // Generate auth for private channel
+ * const signature = signer.sign('socket123', 'private-user-42');
+ *
+ * // Verify auth token
+ * const isValid = signer.verify(signature, 'socket123', 'private-user-42');
+ * ```
+ */
+export declare function createChannelAuthSigner(secret: string): ChannelAuthSigner;

package/dist/auth.js

@@ -0,0 +1,71 @@
+/**
+ * Channel Authentication
+ *
+ * HMAC-SHA256 signing for secure channel authorization.
+ * Prevents forgery of auth tokens for private/presence channels.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/**
+ * Minimum secret length for security.
+ */
+const MIN_SECRET_LENGTH = 16;
+/**
+ * Create a channel authentication signer with HMAC-SHA256.
+ *
+ * @param secret - The secret key (minimum 16 characters)
+ * @returns A signer instance
+ * @throws If secret is too short
+ *
+ * @example
+ * ```typescript
+ * const signer = createChannelAuthSigner(process.env.EVENTS_SECRET!);
+ *
+ * // Generate auth for private channel
+ * const signature = signer.sign('socket123', 'private-user-42');
+ *
+ * // Verify auth token
+ * const isValid = signer.verify(signature, 'socket123', 'private-user-42');
+ * ```
+ */
+export function createChannelAuthSigner(secret) {
+    if (secret.length < MIN_SECRET_LENGTH) {
+        throw new Error(`Auth secret must be at least ${MIN_SECRET_LENGTH} characters for security`);
+    }
+    /**
+     * Create the string to sign.
+     * Format: socketId:channel or socketId:channel:channelData
+     */
+    function createStringToSign(socketId, channel, channelData) {
+        const base = `${socketId}:${channel}`;
+        return channelData ? `${base}:${channelData}` : base;
+    }
+    /**
+     * Generate HMAC-SHA256 signature.
+     */
+    function generateSignature(stringToSign) {
+        return createHmac('sha256', secret).update(stringToSign, 'utf8').digest('hex');
+    }
+    return {
+        sign(socketId, channel, channelData) {
+            const stringToSign = createStringToSign(socketId, channel, channelData);
+            return generateSignature(stringToSign);
+        },
+        verify(signature, socketId, channel, channelData) {
+            const stringToSign = createStringToSign(socketId, channel, channelData);
+            const expectedSignature = generateSignature(stringToSign);
+            // Use timing-safe comparison to prevent timing attacks
+            try {
+                const signatureBuffer = Buffer.from(signature, 'hex');
+                const expectedBuffer = Buffer.from(expectedSignature, 'hex');
+                if (signatureBuffer.length !== expectedBuffer.length) {
+                    return false;
+                }
+                return timingSafeEqual(signatureBuffer, expectedBuffer);
+            }
+            catch {
+                // Invalid hex string or other error
+                return false;
+            }
+        },
+    };
+}

package/dist/drivers/sse.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Server-Sent Events (SSE) Driver
+ *
+ * Fallback driver for environments without WebSocket support.
+ * Uses HTTP streaming for server-to-client communication.
+ */
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import type { BroadcastDriver, EventsSseOptions, PresenceMember } from '../types.js';
+/**
+ * Create an SSE broadcast driver.
+ *
+ * @param config - SSE driver configuration
+ * @returns Broadcast driver implementation with handler
+ *
+ * @example
+ * ```typescript
+ * const driver = createSseDriver({
+ *   driver: 'sse',
+ *   path: '/events',
+ *   heartbeatInterval: 15000,
+ * });
+ *
+ * // Register the SSE endpoint
+ * app.get('/events', driver.handler);
+ *
+ * // Broadcast events
+ * await driver.broadcast({
+ *   channel: 'notifications',
+ *   event: 'new_message',
+ *   data: { text: 'Hello!' },
+ * });
+ * ```
+ */
+export declare function createSseDriver(config: EventsSseOptions): BroadcastDriver & {
+    handler: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    subscribe: (connectionId: string, channel: string, member?: PresenceMember) => void;
+    unsubscribe: (connectionId: string, channel: string) => void;
+};
+/**
+ * SSE driver name.
+ */
+export declare const DRIVER_NAME: "sse";

package/dist/drivers/sse.js

@@ -0,0 +1,284 @@
+/**
+ * Server-Sent Events (SSE) Driver
+ *
+ * Fallback driver for environments without WebSocket support.
+ * Uses HTTP streaming for server-to-client communication.
+ */
+/**
+ * Default SSE driver configuration.
+ */
+const DEFAULT_CONFIG = {
+    path: '/events',
+    heartbeatInterval: 15000,
+    retryInterval: 3000,
+    pingInterval: 30000,
+    connectionTimeout: 60000,
+};
+/**
+ * Create an SSE broadcast driver.
+ *
+ * @param config - SSE driver configuration
+ * @returns Broadcast driver implementation with handler
+ *
+ * @example
+ * ```typescript
+ * const driver = createSseDriver({
+ *   driver: 'sse',
+ *   path: '/events',
+ *   heartbeatInterval: 15000,
+ * });
+ *
+ * // Register the SSE endpoint
+ * app.get('/events', driver.handler);
+ *
+ * // Broadcast events
+ * await driver.broadcast({
+ *   channel: 'notifications',
+ *   event: 'new_message',
+ *   data: { text: 'Hello!' },
+ * });
+ * ```
+ */
+export function createSseDriver(config) {
+    const options = { ...DEFAULT_CONFIG, ...config };
+    const { heartbeatInterval, retryInterval } = options;
+    // Connection tracking
+    const connections = new Map();
+    // Channel subscriptions: channel -> Set of connection IDs
+    const channelSubscriptions = new Map();
+    // Presence data: channel -> Map of connection ID -> PresenceMember
+    const presenceData = new Map();
+    /**
+     * Generate a unique connection ID.
+     */
+    function generateConnectionId() {
+        return `sse-${Date.now().toString(36)}.${Math.random().toString(36).slice(2, 10)}`;
+    }
+    /**
+     * Send an SSE message to a connection.
+     */
+    function send(conn, message) {
+        try {
+            const data = JSON.stringify(message);
+            conn.reply.raw.write(`event: ${message.type}\n`);
+            conn.reply.raw.write(`data: ${data}\n\n`);
+            conn.lastActivity = new Date();
+        }
+        catch {
+            // Connection may be closed, ignore
+        }
+    }
+    /**
+     * Send a heartbeat comment to keep connection alive.
+     */
+    function sendHeartbeat(conn) {
+        try {
+            conn.reply.raw.write(`: heartbeat ${Date.now()}\n\n`);
+            conn.lastActivity = new Date();
+        }
+        catch {
+            // Connection closed, will be cleaned up
+        }
+    }
+    /**
+     * Broadcast an event to subscribers.
+     */
+    function broadcastLocal(event) {
+        const subscribers = channelSubscriptions.get(event.channel);
+        if (!subscribers)
+            return;
+        const message = {
+            type: 'event',
+            channel: event.channel,
+            event: event.event,
+            data: event.data,
+        };
+        for (const connId of subscribers) {
+            if (event.except && connId === event.except)
+                continue;
+            const conn = connections.get(connId);
+            if (conn) {
+                send(conn, message);
+            }
+        }
+    }
+    /**
+     * Subscribe a connection to a channel.
+     */
+    function subscribe(connectionId, channel, member) {
+        const conn = connections.get(connectionId);
+        if (!conn)
+            return;
+        // Add to connection's channels
+        conn.channels.add(channel);
+        // Add to channel subscriptions
+        let subscribers = channelSubscriptions.get(channel);
+        if (!subscribers) {
+            subscribers = new Set();
+            channelSubscriptions.set(channel, subscribers);
+        }
+        subscribers.add(connectionId);
+        // Handle presence channel
+        if (member && channel.startsWith('presence-')) {
+            let members = presenceData.get(channel);
+            if (!members) {
+                members = new Map();
+                presenceData.set(channel, members);
+            }
+            members.set(connectionId, member);
+            conn.presenceInfo.set(channel, member);
+            // Notify others of new member
+            broadcastLocal({
+                channel,
+                event: 'member_added',
+                data: member,
+                except: connectionId,
+            });
+        }
+        // Send success message
+        send(conn, {
+            type: 'subscription_succeeded',
+            channel,
+            data: member && channel.startsWith('presence-')
+                ? { members: Array.from(presenceData.get(channel)?.values() ?? []) }
+                : undefined,
+        });
+    }
+    /**
+     * Unsubscribe a connection from a channel.
+     */
+    function unsubscribe(connectionId, channel) {
+        const conn = connections.get(connectionId);
+        if (!conn)
+            return;
+        // Remove from connection's channels
+        conn.channels.delete(channel);
+        // Remove from channel subscriptions
+        const subscribers = channelSubscriptions.get(channel);
+        if (subscribers) {
+            subscribers.delete(connectionId);
+            if (subscribers.size === 0) {
+                channelSubscriptions.delete(channel);
+            }
+        }
+        // Handle presence channel
+        if (channel.startsWith('presence-')) {
+            const members = presenceData.get(channel);
+            if (members) {
+                const member = members.get(connectionId);
+                members.delete(connectionId);
+                conn.presenceInfo.delete(channel);
+                if (members.size === 0) {
+                    presenceData.delete(channel);
+                }
+                // Notify others of member leaving
+                if (member) {
+                    broadcastLocal({
+                        channel,
+                        event: 'member_removed',
+                        data: member,
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Handle connection close.
+     */
+    function handleDisconnect(connectionId) {
+        const conn = connections.get(connectionId);
+        if (!conn)
+            return;
+        // Unsubscribe from all channels
+        for (const channel of conn.channels) {
+            unsubscribe(connectionId, channel);
+        }
+        // Remove from connections
+        connections.delete(connectionId);
+    }
+    // Heartbeat interval to keep connections alive
+    const heartbeatIntervalId = setInterval(() => {
+        for (const conn of connections.values()) {
+            sendHeartbeat(conn);
+        }
+    }, heartbeatInterval);
+    /**
+     * SSE request handler.
+     */
+    async function handler(request, reply) {
+        const connectionId = generateConnectionId();
+        // Set SSE headers
+        reply.raw.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+            'X-Accel-Buffering': 'no', // Disable nginx buffering
+        });
+        // Send retry interval
+        reply.raw.write(`retry: ${retryInterval}\n\n`);
+        // Create connection
+        const conn = {
+            id: connectionId,
+            reply,
+            channels: new Set(),
+            presenceInfo: new Map(),
+            lastActivity: new Date(),
+        };
+        connections.set(connectionId, conn);
+        // Send connection info
+        send(conn, {
+            type: 'event',
+            event: 'connected',
+            data: { connectionId },
+        });
+        // Handle client disconnect
+        request.raw.on('close', () => {
+            handleDisconnect(connectionId);
+        });
+        // Keep connection open
+        // The reply is not ended here; SSE keeps streaming
+    }
+    const driver = {
+        handler,
+        subscribe,
+        unsubscribe,
+        async broadcast(event) {
+            broadcastLocal(event);
+        },
+        async getSubscribers(channel) {
+            const subscribers = channelSubscriptions.get(channel);
+            return subscribers ? Array.from(subscribers) : [];
+        },
+        async getPresenceMembers(channel) {
+            const members = presenceData.get(channel);
+            return members ? Array.from(members.values()) : [];
+        },
+        async getConnectionCount(channel) {
+            const subscribers = channelSubscriptions.get(channel);
+            return subscribers?.size ?? 0;
+        },
+        async getChannels() {
+            return Array.from(channelSubscriptions.keys());
+        },
+        async close() {
+            clearInterval(heartbeatIntervalId);
+            // Close all connections
+            for (const conn of connections.values()) {
+                try {
+                    conn.reply.raw.end();
+                }
+                catch {
+                    // Ignore
+                }
+            }
+            connections.clear();
+            channelSubscriptions.clear();
+            presenceData.clear();
+        },
+    };
+    return driver;
+}
+/**
+ * SSE driver name.
+ */
+export const DRIVER_NAME = 'sse';