@aetherframework/websocket 1.0.1 → 1.0.3

package/src/drivers/tls-driver.js

@@ -0,0 +1,502 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/src/drivers/tls-driver
+ */
+
+import tls from 'tls';
+import crypto from 'crypto';
+import EventEmitter from 'events';
+import FrameEncoder from '../utils/frame-encoder.js';
+import HandshakeHandler from '../core/HandshakeHandler.js';
+
+class TLSDriver extends EventEmitter {
+  constructor(config = {}) {
+    super();
+    this.config = {
+      port: 443,
+      host: '0.0.0.0',
+      tlsOptions: {
+        key: null,
+        cert: null,
+        ca: null,
+        rejectUnauthorized: false,
+        requestCert: false,
+        ...config.tlsOptions
+      },
+      maxPayload: config.maxPayload || 1024 * 1024,
+      ...config
+    };
+    
+    this.server = null;
+    this.connections = new Map();
+  }
+  
+  /**
+   * Create a TLS WebSocket server
+   * @param {Object} options - Server options
+   * @returns {Promise<Object>} Server instance
+   */
+  async createServer(options = {}) {
+    return new Promise((resolve, reject) => {
+      try {
+        const tlsOptions = {
+          ...this.config.tlsOptions,
+          ...options.tlsOptions
+        };
+        
+        // Validate TLS options
+        if (!tlsOptions.key || !tlsOptions.cert) {
+          throw new Error('TLS requires key and certificate');
+        }
+        
+        this.server = tls.createServer(tlsOptions, (socket) => {
+          this._handleConnection(socket);
+        });
+        
+        const serverOptions = {
+          host: options.host || this.config.host,
+          port: options.port || this.config.port,
+          ...options
+        };
+        
+        this.server.listen(serverOptions, () => {
+          const address = this.server.address();
+          this.emit('server:listening', {
+            host: address.address,
+            port: address.port,
+            family: address.family,
+            secure: true
+          });
+          resolve({
+            type: 'tls',
+            address: address,
+            close: () => this.closeServer()
+          });
+        });
+        
+        this.server.on('error', (error) => {
+          this.emit('error', {
+            type: 'server_error',
+            message: 'TLS server error',
+            error
+          });
+          reject(error);
+        });
+        
+        this.server.on('secureConnection', (socket) => {
+          const cipher = socket.getCipher();
+          this.emit('secure:connection', {
+            cipher: cipher.name,
+            version: cipher.version,
+            authorized: socket.authorized
+          });
+        });
+        
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+  
+  /**
+   * Handle new TLS connection
+   * @param {tls.TLSSocket} socket - TLS socket
+   * @private
+   */
+  _handleConnection(socket) {
+    const connectionId = crypto.randomUUID();
+    let buffer = Buffer.alloc(0);
+    let handshakeComplete = false;
+    
+    // Set socket options
+    socket.setNoDelay(true);
+    socket.setKeepAlive(true, 10000);
+    socket.setTimeout(this.config.socketTimeout || 30000);
+    
+    // Handle incoming data
+    socket.on('data', (chunk) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      
+      if (!handshakeComplete) {
+        this._handleHandshake(socket, buffer, connectionId)
+          .then((handshakeResult) => {
+            if (handshakeResult.success) {
+              handshakeComplete = true;
+              buffer = buffer.slice(handshakeResult.bytesRead);
+              this._setupWebSocketConnection(socket, connectionId, handshakeResult);
+            }
+          })
+          .catch((error) => {
+            this.emit('error', {
+              type: 'handshake_error',
+              message: 'TLS handshake failed',
+              error,
+              connectionId
+            });
+            socket.end();
+          });
+      } else {
+        this._handleWebSocketData(socket, buffer, connectionId);
+      }
+    });
+    
+    // Handle socket events
+    socket.on('close', () => {
+      this.emit('close', this.connections.get(connectionId), 1006, 'Connection closed');
+      this._removeConnection(connectionId);
+    });
+    
+    socket.on('error', (error) => {
+      this.emit('error', {
+        type: 'socket_error',
+        message: 'TLS socket error',
+        error,
+        connectionId
+      });
+      this._removeConnection(connectionId);
+    });
+    
+    socket.on('timeout', () => {
+      socket.end();
+      this._removeConnection(connectionId);
+    });
+  }
+  
+  /**
+   * Handle WebSocket handshake over TLS
+   * @param {tls.TLSSocket} socket - TLS socket
+   * @param {Buffer} buffer - Received data
+   * @param {string} connectionId - Connection ID
+   * @returns {Promise<Object>} Handshake result
+   * @private
+   */
+  async _handleHandshake(socket, buffer, connectionId) {
+    const request = HandshakeHandler.parseRequest(buffer);
+    if (!request) {
+      return { success: false, bytesRead: 0 };
+    }
+    
+    if (!HandshakeHandler.isValidUpgrade(request)) {
+      socket.write('HTTP/1.1 400 Bad Request\r\n\r\n');
+      socket.end();
+      return { success: false, bytesRead: buffer.length };
+    }
+    
+    const selectedProtocol = this._negotiateProtocol(request.headers);
+    const response = HandshakeHandler.createResponse(
+      request.headers['sec-websocket-key'],
+      selectedProtocol
+    );
+    
+    socket.write(response);
+    
+    const connection = {
+      id: connectionId,
+      socket: socket,
+      readyState: 1,
+      protocol: selectedProtocol,
+      remoteAddress: socket.remoteAddress,
+      remotePort: socket.remotePort,
+      cipher: socket.getCipher(),
+      authorized: socket.authorized,
+      headers: request.headers
+    };
+    
+    this.connections.set(connectionId, connection);
+    
+    return {
+      success: true,
+      bytesRead: request.rawHeaderSize,
+      connection: connection
+    };
+  }
+  
+  /**
+   * Negotiate subprotocol
+   * @param {Object} headers - HTTP headers
+   * @returns {string|null} Selected protocol
+   * @private
+   */
+  _negotiateProtocol(headers) {
+    const clientProtocols = headers['sec-websocket-protocol'];
+    if (!clientProtocols) return null;
+    
+    const supportedProtocols = this.config.supportedProtocols || [];
+    const requestedProtocols = clientProtocols.split(',').map(p => p.trim());
+    
+    for (const protocol of requestedProtocols) {
+      if (supportedProtocols.includes(protocol)) {
+        return protocol;
+      }
+    }
+    
+    return null;
+  }
+  
+  /**
+   * Set up WebSocket connection after handshake
+   * @param {tls.TLSSocket} socket - TLS socket
+   * @param {string} connectionId - Connection ID
+   * @param {Object} handshakeResult - Handshake result
+   * @private
+   */
+  _setupWebSocketConnection(socket, connectionId, handshakeResult) {
+    const connection = handshakeResult.connection;
+    
+    // Emit connection event
+    this.emit('connection', connection);
+    
+    // Set up ping/pong heartbeat
+    if (this.config.pingInterval) {
+      const pingInterval = setInterval(() => {
+        if (connection.readyState === 1) {
+          this._sendPing(socket);
+        } else {
+          clearInterval(pingInterval);
+        }
+      }, this.config.pingInterval);
+      
+      connection.pingInterval = pingInterval;
+    }
+  }
+  
+  /**
+   * Handle WebSocket data frames
+   * @param {tls.TLSSocket} socket - TLS socket
+   * @param {Buffer} buffer - Data buffer
+   * @param {string} connectionId - Connection ID
+   * @private
+   */
+  _handleWebSocketData(socket, buffer, connectionId) {
+    const connection = this.connections.get(connectionId);
+    if (!connection) return;
+    
+    try {
+      // Parse frames using FrameEncoder (assuming it has parse method)
+      const frames = FrameEncoder.parse(buffer, this.config.maxPayload);
+      
+      for (const frame of frames) {
+        switch (frame.opcode) {
+          case 0x1: // Text frame
+            const text = frame.payload.toString('utf8');
+            this.emit('message', connection, text, false);
+            break;
+            
+          case 0x2: // Binary frame
+            this.emit('message', connection, frame.payload, true);
+            break;
+            
+          case 0x8: // Close frame
+            const code = frame.payload.length >= 2 ? 
+              frame.payload.readUInt16BE(0) : 1000;
+            const reason = frame.payload.length > 2 ? 
+              frame.payload.slice(2).toString('utf8') : '';
+            this._sendCloseFrame(socket, code, reason);
+            connection.readyState = 3;
+            this.emit('close', connection, code, reason);
+            socket.end();
+            break;
+            
+          case 0x9: // Ping frame
+            this._sendPong(socket, frame.payload);
+            break;
+            
+          case 0xA: // Pong frame
+            this.emit('pong', connection);
+            break;
+        }
+      }
+    } catch (error) {
+      this.emit('error', {
+        type: 'frame_parse_error',
+        message: 'Failed to parse WebSocket frame',
+        error,
+        connectionId
+      });
+      this._sendCloseFrame(socket, 1002, 'Protocol error');
+      socket.end();
+    }
+  }
+  
+  /**
+   * Send ping frame
+   * @param {tls.TLSSocket} socket - TLS socket
+   * @private
+   */
+  _sendPing(socket) {
+    const pingFrame = FrameEncoder.createPingFrame();
+    socket.write(pingFrame);
+  }
+  
+  /**
+   * Send pong frame
+   * @param {tls.TLSSocket} socket - TLS socket
+   * @param {Buffer} payload - Ping payload to echo back
+   * @private
+   */
+  _sendPong(socket, payload) {
+    const pongFrame = FrameEncoder.createPongFrame(payload);
+    socket.write(pongFrame);
+  }
+  
+  /**
+   * Send close frame
+   * @param {tls.TLSSocket} socket - TLS socket
+   * @param {number} code - Close code
+   * @param {string} reason - Close reason
+   * @private
+   */
+  _sendCloseFrame(socket, code, reason) {
+    const closeFrame = FrameEncoder.createCloseFrame(code, reason);
+    socket.write(closeFrame);
+  }
+  
+  /**
+   * Remove connection
+   * @param {string} connectionId - Connection ID
+   * @private
+   */
+  _removeConnection(connectionId) {
+    const connection = this.connections.get(connectionId);
+    if (connection) {
+      if (connection.pingInterval) {
+        clearInterval(connection.pingInterval);
+      }
+      this.connections.delete(connectionId);
+    }
+  }
+  
+  /**
+   * Create a secure WebSocket client
+   * @param {string} url - WebSocket URL (wss://)
+   * @param {Object} options - Client options
+   * @returns {Promise<Object>} Client connection
+   */
+  async createClient(url, options = {}) {
+    const urlObj = new URL(url);
+    const host = urlObj.hostname;
+    const port = parseInt(urlObj.port) || 443;
+    const path = urlObj.pathname + urlObj.search;
+    
+    const tlsOptions = {
+      host,
+      port,
+      rejectUnauthorized: false,
+      ...options.tlsOptions
+    };
+    
+    return new Promise((resolve, reject) => {
+      const socket = tls.connect(tlsOptions, () => {
+        // Send WebSocket handshake
+        const key = crypto.randomBytes(16).toString('base64');
+        const handshake = [
+          `GET ${path} HTTP/1.1`,
+          `Host: ${host}:${port}`,
+          'Upgrade: websocket',
+          'Connection: Upgrade',
+          `Sec-WebSocket-Key: ${key}`,
+          'Sec-WebSocket-Version: 13',
+          'Sec-WebSocket-Protocol: tls'
+        ].join('\r\n') + '\r\n\r\n';
+        
+        socket.write(handshake);
+        
+        let buffer = Buffer.alloc(0);
+        
+        const onData = (chunk) => {
+          buffer = Buffer.concat([buffer, chunk]);
+          
+          const response = buffer.toString('utf8');
+          if (response.includes('\r\n\r\n')) {
+            socket.removeListener('data', onData);
+            
+            if (response.includes('101 Switching Protocols')) {
+              const connection = {
+                id: crypto.randomUUID(),
+                socket: socket,
+                readyState: 1,
+                send: (data) => this._sendData(socket, data),
+                close: (code, reason) => {
+                  this._sendCloseFrame(socket, code, reason);
+                  socket.end();
+                }
+              };
+              
+              socket.on('data', (data) => {
+                this._handleWebSocketData(socket, data, connection.id);
+              });
+              
+              resolve(connection);
+            } else {
+              reject(new Error('TLS handshake failed'));
+            }
+          }
+        };
+        
+        socket.on('data', onData);
+      });
+      
+      socket.on('error', reject);
+      socket.on('timeout', () => reject(new Error('TLS connection timeout')));
+    });
+  }
+  
+  /**
+   * Send data through TLS socket
+   * @param {tls.TLSSocket} socket - TLS socket
+   * @param {string|Buffer} data - Data to send
+   * @private
+   */
+  _sendData(socket, data) {
+    const frame = FrameEncoder.encode(
+      0x1, // Text frame opcode
+      Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8')
+    );
+    socket.write(frame);
+  }
+  
+  /**
+   * Close the TLS server
+   * @returns {Promise<void>}
+   */
+  async closeServer() {
+    return new Promise((resolve) => {
+      if (this.server) {
+        // Close all connections
+        this.connections.forEach((connection) => {
+          if (connection.readyState === 1) {
+            this._sendCloseFrame(connection.socket, 1001, 'Server going away');
+            connection.socket.end();
+          }
+        });
+        
+        this.server.close(() => {
+          this.connections.clear();
+          resolve();
+        });
+      } else {
+        resolve();
+      }
+    });
+  }
+  
+  /**
+   * Get server statistics
+   * @returns {Object} Statistics object
+   */
+  getStats() {
+    return {
+      connections: this.connections.size,
+      uptime: this.server ? Date.now() - this.server.startTime : 0,
+      host: this.config.host,
+      port: this.config.port,
+      driver: 'tls',
+      secure: true,
+      cipherSuites: this.config.tlsOptions.ciphers || 'DEFAULT'
+    };
+  }
+}
+
+export default TLSDriver;

package/src/middleware/auth-middleware.js

@@ -0,0 +1,37 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/src/middleware/auth-middleware
+ */
+
+/**
+ * Create auth middleware
+ * @param {Function} verifyFn - Async function to verify token
+ * @returns {Function} Middleware function
+ */
+export function createAuthMiddleware(verifyFn) {
+  return async (connection, next) => {
+    const token = connection.headers['sec-websocket-protocol'] || 
+                  connection.url?.searchParams?.get('token');
+    
+    if (!token) {
+      connection.close(4001, 'Authentication required');
+      return;
+    }
+
+    try {
+      const user = await verifyFn(token);
+      if (!user) {
+        connection.close(4003, 'Invalid token');
+        return;
+      }
+      connection.user = user;
+      next();
+    } catch (error) {
+      connection.close(4002, 'Auth error');
+    }
+  };
+}
+
+export default createAuthMiddleware;

package/src/middleware/broadcast-manager.js

@@ -0,0 +1,173 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/src/middleware/broadcast-manager
+ */
+
+
+class BroadcastManager {
+  constructor(options = {}) {
+    this.options = {
+      maxRooms: options.maxRooms || 10000,
+      batchSize: options.batchSize || 100, // Process sends in batches to avoid event loop blocking
+      ...options
+    };
+    
+    // Map<roomName, Set<connectionId>>
+    this.rooms = new Map();
+    // Map<connectionId, Set<roomName>> - for quick lookup of which rooms a conn belongs to
+    this.connRooms = new Map();
+    
+    this.stats = {
+      broadcasts: 0,
+      messagesSent: 0
+    };
+  }
+
+  /**
+   * Middleware factory
+   */
+  middleware() {
+    return (connection, next) => {
+      // Attach room methods to connection object
+      connection.join = (room) => this.addToRoom(connection.id, room);
+      connection.leave = (room) => this.removeFromRoom(connection.id, room);
+      connection.rooms = () => this.getConnRooms(connection.id);
+      
+      // Cleanup on close
+      const originalClose = connection.close.bind(connection);
+      connection.close = (code, reason) => {
+        this.removeAllFromRooms(connection.id);
+        return originalClose(code, reason);
+      };
+
+      next();
+    };
+  }
+
+  /**
+   * Add connection to a room
+   * @param {string} connId 
+   * @param {string} room 
+   */
+  addToRoom(connId, room) {
+    if (!this.rooms.has(room)) {
+      if (this.rooms.size >= this.options.maxRooms) {
+        throw new Error(`Max rooms limit (${this.options.maxRooms}) reached`);
+      }
+      this.rooms.set(room, new Set());
+    }
+    this.rooms.get(room).add(connId);
+
+    if (!this.connRooms.has(connId)) {
+      this.connRooms.set(connId, new Set());
+    }
+    this.connRooms.get(connId).add(room);
+  }
+
+  /**
+   * Remove connection from a room
+   * @param {string} connId 
+   * @param {string} room 
+   */
+  removeFromRoom(connId, room) {
+    const roomSet = this.rooms.get(room);
+    if (roomSet) {
+      roomSet.delete(connId);
+      if (roomSet.size === 0) {
+        this.rooms.delete(room);
+      }
+    }
+
+    const userRooms = this.connRooms.get(connId);
+    if (userRooms) {
+      userRooms.delete(room);
+      if (userRooms.size === 0) {
+        this.connRooms.delete(connId);
+      }
+    }
+  }
+
+  /**
+   * Remove connection from all rooms
+   * @param {string} connId 
+   */
+  removeAllFromRooms(connId) {
+    const userRooms = this.connRooms.get(connId);
+    if (userRooms) {
+      for (const room of userRooms) {
+        this.removeFromRoom(connId, room);
+      }
+    }
+  }
+
+  /**
+   * Get rooms for a connection
+   * @param {string} connId 
+   * @returns {Array<string>}
+   */
+  getConnRooms(connId) {
+    const rooms = this.connRooms.get(connId);
+    return rooms ? Array.from(rooms) : [];
+  }
+
+  /**
+   * Broadcast message to a specific room
+   * @param {string} room 
+   * @param {string|Buffer} data 
+   * @param {Object} connectionManager - Instance to get active connections
+   */
+  broadcastToRoom(room, data, connectionManager) {
+    const roomSet = this.rooms.get(room);
+    if (!roomSet || roomSet.size === 0) return;
+
+    this.stats.broadcasts++;
+    let sentCount = 0;
+
+    // Convert to buffer once if string to optimize memory
+    const payload = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
+
+    for (const connId of roomSet) {
+      const conn = connectionManager.getConnection(connId);
+      if (conn && conn.readyState === 1) { // OPEN
+        conn.sendBinary ? conn.sendBinary(payload) : conn.send(payload);
+        sentCount++;
+      }
+    }
+    
+    this.stats.messagesSent += sentCount;
+  }
+
+  /**
+   * Broadcast to all connected clients
+   * @param {string|Buffer} data 
+   * @param {Object} connectionManager 
+   */
+  broadcastAll(data, connectionManager) {
+    const allConns = connectionManager.getAllConnections();
+    this.stats.broadcasts++;
+    let sentCount = 0;
+    
+    const payload = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
+
+    for (const conn of allConns) {
+      if (conn.readyState === 1) {
+        conn.sendBinary ? conn.sendBinary(payload) : conn.send(payload);
+        sentCount++;
+      }
+    }
+    
+    this.stats.messagesSent += sentCount;
+  }
+
+  getStats() {
+    return {
+      ...this.stats,
+      activeRooms: this.rooms.size,
+      totalMappings: this.connRooms.size
+    };
+  }
+}
+
+export default BroadcastManager;