@africode/core 5.0.0

package/core/websocket.js

@@ -0,0 +1,639 @@
+/**
+ * AfriCode WebSocket Support
+ * 
+ * Real-time bidirectional communication with:
+ * - Persistent WebSocket connections
+ * - Room/channel management
+ * - Event broadcasting
+ * - Message queueing
+ * - Presence tracking
+ * - Automatic reconnection
+ */
+
+/**
+ * WebSocket Server Manager
+ * Handles connections, rooms, and broadcasting
+ */
+export class WebSocketServer {
+    constructor() {
+        this.connections = new Map(); // connection_id -> WebSocket
+        this.rooms = new Map(); // room_name -> Set of connection_ids
+        this.messageHandlers = new Map(); // event_type -> handler function
+        this.userConnections = new Map(); // user_id -> Set of connection_ids
+        this.messageQueue = []; // For offline message queueing
+        this.maxQueueSize = 1000;
+        this.connectionCounter = 0;
+    }
+
+    /**
+     * Register a message handler for a specific event type
+     */
+    on(eventType, handler) {
+        if (!this.messageHandlers.has(eventType)) {
+            this.messageHandlers.set(eventType, []);
+        }
+        this.messageHandlers.get(eventType).push(handler);
+        return this;
+    }
+
+    /**
+     * Handle new WebSocket connection
+     */
+    handleConnection(ws, userId = null) {
+        const connectionId = `conn_${++this.connectionCounter}`;
+        this.connections.set(connectionId, {
+            ws,
+            userId,
+            connectedAt: Date.now(),
+            lastHeartbeat: Date.now(),
+            rooms: new Set()
+        });
+
+        if (userId) {
+            if (!this.userConnections.has(userId)) {
+                this.userConnections.set(userId, new Set());
+            }
+            this.userConnections.get(userId).add(connectionId);
+            this.broadcast('user:online', { userId, connectionId }, null, 'presence');
+        }
+
+        // Setup message handler
+        ws.onmessage = (event) => this.handleMessage(connectionId, event);
+
+        // Setup close handler
+        ws.onclose = () => this.handleDisconnection(connectionId);
+
+        // Send welcome message
+        this.send(connectionId, 'connection:established', {
+            connectionId,
+            userId,
+            serverTime: Date.now()
+        });
+
+        // Start heartbeat
+        this.startHeartbeat(connectionId);
+
+        return connectionId;
+    }
+
+    /**
+     * Handle incoming messages
+     */
+    handleMessage(connectionId, event) {
+        try {
+            const data = JSON.parse(event.data);
+            const { type, payload, roomId } = data;
+
+            const connInfo = this.connections.get(connectionId);
+            if (!connInfo) return;
+
+            connInfo.lastHeartbeat = Date.now();
+
+            // Handle special system messages
+            if (type === 'ping') {
+                this.send(connectionId, 'pong', { timestamp: Date.now() });
+                return;
+            }
+
+            if (type === 'join:room') {
+                this.joinRoom(connectionId, payload.roomId, payload.userId);
+                return;
+            }
+
+            if (type === 'leave:room') {
+                this.leaveRoom(connectionId, payload.roomId);
+                return;
+            }
+
+            // Call registered handlers
+            const handlers = this.messageHandlers.get(type) || [];
+            for (const handler of handlers) {
+                try {
+                    handler({
+                        connectionId,
+                        userId: connInfo.userId,
+                        payload,
+                        roomId,
+                        timestamp: Date.now()
+                    });
+                } catch (error) {
+                    console.error(`Error in handler for ${type}:`, error);
+                }
+            }
+        } catch (error) {
+            console.error('Error handling message:', error);
+        }
+    }
+
+    /**
+     * Handle disconnection
+     */
+    handleDisconnection(connectionId) {
+        const connInfo = this.connections.get(connectionId);
+        if (!connInfo) return;
+
+        const { userId } = connInfo;
+
+        // Remove from all rooms
+        for (const roomId of connInfo.rooms) {
+            this.leaveRoom(connectionId, roomId);
+        }
+
+        // Remove from user connections
+        if (userId) {
+            const userConns = this.userConnections.get(userId);
+            if (userConns) {
+                userConns.delete(connectionId);
+                if (userConns.size === 0) {
+                    this.userConnections.delete(userId);
+                    this.broadcast('user:offline', { userId }, null, 'presence');
+                }
+            }
+        }
+
+        this.connections.delete(connectionId);
+    }
+
+    /**
+     * Join a room
+     */
+    joinRoom(connectionId, roomId, userId = null) {
+        if (!this.rooms.has(roomId)) {
+            this.rooms.set(roomId, new Set());
+        }
+
+        const room = this.rooms.get(roomId);
+        room.add(connectionId);
+
+        const connInfo = this.connections.get(connectionId);
+        if (connInfo) {
+            connInfo.rooms.add(roomId);
+        }
+
+        // Broadcast user joined to room
+        this.broadcast(
+            'room:user:joined',
+            { userId, connectionId, roomId },
+            roomId,
+            'room'
+        );
+
+        // Send room members list to new member
+        const members = Array.from(room).map(cid => {
+            const ci = this.connections.get(cid);
+            return { connectionId: cid, userId: ci?.userId };
+        });
+
+        this.send(connectionId, 'room:members', { roomId, members });
+    }
+
+    /**
+     * Leave a room
+     */
+    leaveRoom(connectionId, roomId) {
+        const room = this.rooms.get(roomId);
+        if (!room) return;
+
+        room.delete(connectionId);
+
+        const connInfo = this.connections.get(connectionId);
+        if (connInfo) {
+            connInfo.rooms.delete(roomId);
+        }
+
+        // Broadcast user left to room
+        this.broadcast(
+            'room:user:left',
+            { connectionId, roomId },
+            roomId,
+            'room'
+        );
+
+        // Clean up empty rooms
+        if (room.size === 0) {
+            this.rooms.delete(roomId);
+        }
+    }
+
+    /**
+     * Send message to specific connection
+     */
+    send(connectionId, type, payload) {
+        const connInfo = this.connections.get(connectionId);
+        if (!connInfo) return false;
+
+        try {
+            connInfo.ws.send(JSON.stringify({
+                type,
+                payload,
+                timestamp: Date.now()
+            }));
+            return true;
+        } catch (error) {
+            console.error(`Error sending to ${connectionId}:`, error);
+            return false;
+        }
+    }
+
+    /**
+     * Broadcast message to all connections in a room or globally
+     */
+    broadcast(type, payload, roomId = null, scope = 'global') {
+        const timestamp = Date.now();
+
+        if (scope === 'room' && roomId) {
+            const room = this.rooms.get(roomId);
+            if (room) {
+                for (const connectionId of room) {
+                    const connInfo = this.connections.get(connectionId);
+                    if (connInfo) {
+                        try {
+                            connInfo.ws.send(JSON.stringify({
+                                type,
+                                payload,
+                                roomId,
+                                timestamp
+                            }));
+                        } catch (error) {
+                            console.error(`Error broadcasting to ${connectionId}:`, error);
+                        }
+                    }
+                }
+            }
+        } else if (scope === 'user' && payload.userId) {
+            const userConns = this.userConnections.get(payload.userId);
+            if (userConns) {
+                for (const connectionId of userConns) {
+                    this.send(connectionId, type, payload);
+                }
+            }
+        } else if (scope === 'presence') {
+            // Broadcast presence to all connections
+            for (const [connId, connInfo] of this.connections.entries()) {
+                try {
+                    connInfo.ws.send(JSON.stringify({
+                        type,
+                        payload,
+                        timestamp
+                    }));
+                } catch (error) {
+                    console.error(`Error broadcasting presence to ${connId}:`, error);
+                }
+            }
+        } else {
+            // Global broadcast
+            for (const [connId, connInfo] of this.connections.entries()) {
+                try {
+                    connInfo.ws.send(JSON.stringify({
+                        type,
+                        payload,
+                        timestamp
+                    }));
+                } catch (error) {
+                    console.error(`Error broadcasting to ${connId}:`, error);
+                }
+            }
+        }
+    }
+
+    /**
+     * Send message to all users in a room
+     */
+    toRoom(roomId, type, payload, excludeConnectionId = null) {
+        const room = this.rooms.get(roomId);
+        if (!room) return;
+
+        for (const connectionId of room) {
+            if (excludeConnectionId === connectionId) continue;
+            this.send(connectionId, type, payload);
+        }
+    }
+
+    /**
+     * Send message to specific user (all their connections)
+     */
+    toUser(userId, type, payload) {
+        const userConns = this.userConnections.get(userId);
+        if (!userConns) return;
+
+        for (const connectionId of userConns) {
+            this.send(connectionId, type, payload);
+        }
+    }
+
+    /**
+     * Queue message for offline user
+     */
+    queueMessage(userId, type, payload) {
+        if (this.messageQueue.length >= this.maxQueueSize) {
+            this.messageQueue.shift(); // Remove oldest
+        }
+
+        this.messageQueue.push({
+            userId,
+            type,
+            payload,
+            queuedAt: Date.now()
+        });
+    }
+
+    /**
+     * Deliver queued messages to user
+     */
+    deliverQueuedMessages(userId) {
+        const queued = this.messageQueue.filter(msg => msg.userId === userId);
+        
+        for (const msg of queued) {
+            this.toUser(userId, msg.type, msg.payload);
+            this.messageQueue = this.messageQueue.filter(m => m !== msg);
+        }
+
+        return queued.length;
+    }
+
+    /**
+     * Start heartbeat for connection
+     */
+    startHeartbeat(connectionId) {
+        const interval = setInterval(() => {
+            const connInfo = this.connections.get(connectionId);
+            if (!connInfo) {
+                clearInterval(interval);
+                return;
+            }
+
+            const timeSinceLastHeartbeat = Date.now() - connInfo.lastHeartbeat;
+            if (timeSinceLastHeartbeat > 60000) {
+                // No heartbeat for 60 seconds, consider dead
+                try {
+                    connInfo.ws.close(1000, 'Heartbeat timeout');
+                } catch (e) {
+                    // Already closed
+                }
+                clearInterval(interval);
+                return;
+            }
+
+            this.send(connectionId, 'ping', { timestamp: Date.now() });
+        }, 30000); // Every 30 seconds
+
+        return interval;
+    }
+
+    /**
+     * Get room information
+     */
+    getRoomInfo(roomId) {
+        const room = this.rooms.get(roomId);
+        if (!room) return null;
+
+        const members = Array.from(room).map(connId => {
+            const connInfo = this.connections.get(connId);
+            return {
+                connectionId: connId,
+                userId: connInfo?.userId,
+                connectedAt: connInfo?.connectedAt
+            };
+        });
+
+        return {
+            roomId,
+            memberCount: room.size,
+            members,
+            createdAt: Math.min(...members.map(m => m.connectedAt))
+        };
+    }
+
+    /**
+     * Get user presence information
+     */
+    getUserPresence(userId) {
+        const userConns = this.userConnections.get(userId);
+        if (!userConns) return null;
+
+        const connections = Array.from(userConns).map(connId => {
+            const connInfo = this.connections.get(connId);
+            return {
+                connectionId: connId,
+                connectedAt: connInfo?.connectedAt,
+                rooms: Array.from(connInfo?.rooms || [])
+            };
+        });
+
+        return {
+            userId,
+            connectionCount: userConns.size,
+            connections,
+            isOnline: userConns.size > 0
+        };
+    }
+
+    /**
+     * Get all active rooms
+     */
+    getAllRooms() {
+        const roomList = [];
+        
+        for (const [roomId, members] of this.rooms.entries()) {
+            roomList.push({
+                roomId,
+                memberCount: members.size
+            });
+        }
+
+        return roomList;
+    }
+
+    /**
+     * Get connection statistics
+     */
+    getStats() {
+        return {
+            activeConnections: this.connections.size,
+            activeRooms: this.rooms.size,
+            activeUsers: this.userConnections.size,
+            queuedMessages: this.messageQueue.length,
+            messageHandlers: this.messageHandlers.size
+        };
+    }
+
+    /**
+     * Close all connections gracefully
+     */
+    shutdown() {
+        for (const [connId, connInfo] of this.connections.entries()) {
+            try {
+                connInfo.ws.close(1001, 'Server shutting down');
+            } catch (e) {
+                // Already closed
+            }
+        }
+        this.connections.clear();
+        this.rooms.clear();
+        this.userConnections.clear();
+        this.messageHandlers.clear();
+        this.messageQueue = [];
+    }
+}
+
+/**
+ * WebSocket Client Helper
+ * For use in Bun HTTP server context
+ */
+export class WebSocketClient {
+    constructor(url, userId = null) {
+        this.url = url;
+        this.userId = userId;
+        this.ws = null;
+        this.reconnectAttempts = 0;
+        this.maxReconnectAttempts = 10;
+        this.reconnectDelay = 1000; // Start at 1 second
+        this.messageHandlers = new Map();
+        this.roomSubscriptions = new Set();
+        this.isConnecting = false;
+    }
+
+    /**
+     * Connect to WebSocket server
+     */
+    connect() {
+        if (this.isConnecting || this.ws) return;
+        this.isConnecting = true;
+
+        try {
+            this.ws = new WebSocket(this.url);
+
+            this.ws.onopen = () => {
+                console.log('Connected to WebSocket server');
+                this.reconnectAttempts = 0;
+                this.reconnectDelay = 1000;
+                this.emit('connected', { userId: this.userId });
+            };
+
+            this.ws.onmessage = (event) => {
+                const data = JSON.parse(event.data);
+                this.emit(data.type, data.payload);
+            };
+
+            this.ws.onerror = (error) => {
+                console.error('WebSocket error:', error);
+                this.emit('error', error);
+            };
+
+            this.ws.onclose = () => {
+                console.log('Disconnected from WebSocket');
+                this.ws = null;
+                this.isConnecting = false;
+                this.attemptReconnect();
+            };
+        } catch (error) {
+            console.error('Failed to connect to WebSocket:', error);
+            this.isConnecting = false;
+            this.attemptReconnect();
+        }
+    }
+
+    /**
+     * Attempt to reconnect with exponential backoff
+     */
+    attemptReconnect() {
+        if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+            this.emit('reconnect:failed', {
+                attempts: this.reconnectAttempts
+            });
+            return;
+        }
+
+        this.reconnectAttempts++;
+        const delay = Math.min(this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1), 30000);
+
+        console.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})`);
+        
+        setTimeout(() => {
+            this.connect();
+        }, delay);
+    }
+
+    /**
+     * Register message handler
+     */
+    on(type, handler) {
+        if (!this.messageHandlers.has(type)) {
+            this.messageHandlers.set(type, []);
+        }
+        this.messageHandlers.get(type).push(handler);
+        return this;
+    }
+
+    /**
+     * Emit event to handlers
+     */
+    emit(type, payload) {
+        const handlers = this.messageHandlers.get(type) || [];
+        for (const handler of handlers) {
+            try {
+                handler(payload);
+            } catch (error) {
+                console.error(`Error in handler for ${type}:`, error);
+            }
+        }
+    }
+
+    /**
+     * Send message to server
+     */
+    send(type, payload) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            console.warn('WebSocket not connected');
+            return false;
+        }
+
+        try {
+            this.ws.send(JSON.stringify({
+                type,
+                payload,
+                timestamp: Date.now()
+            }));
+            return true;
+        } catch (error) {
+            console.error('Error sending message:', error);
+            return false;
+        }
+    }
+
+    /**
+     * Join a room
+     */
+    joinRoom(roomId) {
+        this.roomSubscriptions.add(roomId);
+        return this.send('join:room', {
+            roomId,
+            userId: this.userId
+        });
+    }
+
+    /**
+     * Leave a room
+     */
+    leaveRoom(roomId) {
+        this.roomSubscriptions.delete(roomId);
+        return this.send('leave:room', {
+            roomId
+        });
+    }
+
+    /**
+     * Disconnect from server
+     */
+    disconnect() {
+        if (this.ws) {
+            this.ws.close(1000, 'Client closing');
+            this.ws = null;
+        }
+    }
+}
+
+export default {
+    WebSocketServer,
+    WebSocketClient
+};