@aetherframework/websocket 1.0.1 → 1.0.3

package/src/core/ConnectionManager.js

@@ -0,0 +1,213 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/src/core/ConnectionManager
+ */
+
+class ConnectionManager {
+  constructor() {
+    this.connections = new Map();
+    this.groups = new Map();
+    this.stats = {
+      totalConnections: 0,
+      activeConnections: 0,
+      messagesSent: 0,
+      messagesReceived: 0,
+      bytesSent: 0,
+      bytesReceived: 0
+    };
+  }
+  
+  /**
+   * Add a new connection
+   * @param {Object} connection - Connection object
+   * @returns {Object} Enhanced connection object
+   */
+  add(connection) {
+    const enhancedConnection = {
+      ...connection,
+      groups: new Set(),
+      metadata: {},
+      createdAt: Date.now(),
+      lastActivity: Date.now(),
+      
+      // Enhanced send method with statistics
+      send: (data, options = {}) => {
+        const result = connection.send(data, options);
+        if (result) {
+          this.stats.messagesSent++;
+          this.stats.bytesSent += Buffer.byteLength(data);
+          connection.lastActivity = Date.now();
+        }
+        return result;
+      },
+      
+      // Enhanced close method
+      close: (code = 1000, reason = '') => {
+        this.remove(connection.id);
+        return connection.close(code, reason);
+      },
+      
+      // Join a group
+      join: (groupName) => {
+        if (!this.groups.has(groupName)) {
+          this.groups.set(groupName, new Set());
+        }
+        this.groups.get(groupName).add(connection.id);
+        enhancedConnection.groups.add(groupName);
+        return true;
+      },
+      
+      // Leave a group
+      leave: (groupName) => {
+        const group = this.groups.get(groupName);
+        if (group) {
+          group.delete(connection.id);
+          enhancedConnection.groups.delete(groupName);
+          return true;
+        }
+        return false;
+      },
+      
+      // Get connection statistics
+      getStats: () => ({
+        id: connection.id,
+        readyState: connection.readyState,
+        uptime: Date.now() - enhancedConnection.createdAt,
+        lastActivity: enhancedConnection.lastActivity,
+        groups: Array.from(enhancedConnection.groups),
+        metadata: enhancedConnection.metadata,
+        remoteAddress: connection.remoteAddress,
+        remotePort: connection.remotePort
+      })
+    };
+    
+    this.connections.set(connection.id, enhancedConnection);
+    this.stats.totalConnections++;
+    this.stats.activeConnections++;
+    
+    // Set up cleanup on close
+    connection.on('close', () => {
+      this.remove(connection.id);
+    });
+    
+    return enhancedConnection;
+  }
+  
+  /**
+   * Remove a connection
+   * @param {string} connectionId - Connection ID
+   * @returns {boolean} Success status
+   */
+  remove(connectionId) {
+    const connection = this.connections.get(connectionId);
+    if (connection) {
+      // Remove from all groups
+      connection.groups.forEach(groupName => {
+        const group = this.groups.get(groupName);
+        if (group) {
+          group.delete(connectionId);
+          if (group.size === 0) {
+            this.groups.delete(groupName);
+          }
+        }
+      });
+      
+      this.connections.delete(connectionId);
+      this.stats.activeConnections--;
+      return true;
+    }
+    return false;
+  }
+  
+  /**
+   * Get connection by ID
+   * @param {string} connectionId - Connection ID
+   * @returns {Object|null} Connection object or null
+   */
+  get(connectionId) {
+    return this.connections.get(connectionId) || null;
+  }
+  
+  /**
+   * Get all connections
+   * @returns {Array} Array of connection objects
+   */
+  getAll() {
+    return Array.from(this.connections.values());
+  }
+  
+  /**
+   * Get connections by group
+   * @param {string} groupName - Group name
+   * @returns {Array} Array of connections in the group
+   */
+  getGroup(groupName) {
+    const group = this.groups.get(groupName);
+    if (!group) return [];
+    
+    return Array.from(group)
+      .map(id => this.get(id))
+      .filter(conn => conn !== null && conn.readyState === 1);
+  }
+  
+  /**
+   * Broadcast to a specific group
+   * @param {string} groupName - Group name
+   * @param {string|Buffer} message - Message to send
+   * @returns {number} Number of connections that received the message
+   */
+  broadcastToGroup(groupName, message) {
+    const connections = this.getGroup(groupName);
+    let successCount = 0;
+    
+    connections.forEach(connection => {
+      if (connection.send(message)) {
+        successCount++;
+      }
+    });
+    
+    return successCount;
+  }
+  
+  /**
+   * Filter connections based on criteria
+   * @param {Function} filterFn - Filter function
+   * @returns {Array} Filtered connections
+   */
+  filter(filterFn) {
+    return this.getAll().filter(filterFn);
+  }
+  
+  /**
+   * Get connection statistics
+   * @returns {Object} Statistics object
+   */
+  getStats() {
+    return {
+      ...this.stats,
+      groups: this.groups.size,
+      timestamp: Date.now()
+    };
+  }
+  
+  /**
+   * Clear all connections
+   */
+  clear() {
+    this.connections.clear();
+    this.groups.clear();
+    this.stats.activeConnections = 0;
+  }
+  
+  /**
+   * Get connection count
+   * @returns {number} Number of connections
+   */
+  count() {
+    return this.connections.size;
+  }
+}
+
+export default ConnectionManager;

package/src/core/FrameParser.js

@@ -0,0 +1,115 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/src/core/FrameParser
+ */
+
+class FrameParser {
+  /**
+   * Parse raw buffer data into WebSocket frames
+   * @param {Buffer} buffer - Raw incoming data
+   * @param {number} maxPayload - Maximum allowed payload size
+   * @returns {Object} { frames: Array, remaining: Buffer }
+   */
+  static parse(buffer, maxPayload = 1024 * 1024) {
+    const frames = [];
+    let offset = 0;
+
+    while (offset < buffer.length) {
+      // Need at least 2 bytes for basic header
+      if (buffer.length - offset < 2) break;
+
+      const byte1 = buffer[offset];
+      const byte2 = buffer[offset + 1];
+
+      const fin = (byte1 & 0x80) !== 0;
+      const opcode = byte1 & 0x0F;
+      const mask = (byte2 & 0x80) !== 0;
+      let payloadLength = byte2 & 0x7F;
+
+      let headerSize = 2;
+      let payloadOffset = offset + 2;
+
+      // Handle extended payload length
+      if (payloadLength === 126) {
+        if (buffer.length - offset < 4) break;
+        payloadLength = buffer.readUInt16BE(offset + 2);
+        headerSize += 2;
+        payloadOffset += 2;
+      } else if (payloadLength === 127) {
+        if (buffer.length - offset < 10) break;
+        // JavaScript numbers are safe up to 2^53, but WS spec says 2^63
+        // We use BigInt for safety then convert if safe, or throw if too large
+        const bigLen = buffer.readBigUInt64BE(offset + 2);
+        if (bigLen > BigInt(Number.MAX_SAFE_INTEGER)) {
+          throw new Error('Payload too large');
+        }
+        payloadLength = Number(bigLen);
+        headerSize += 8;
+        payloadOffset += 8;
+      }
+
+      // Check payload size limit
+      if (payloadLength > maxPayload) {
+        throw new Error(`Payload exceeds maximum size: ${payloadLength} > ${maxPayload}`);
+      }
+
+      // Handle masking key
+      let maskingKey = null;
+      if (mask) {
+        if (buffer.length - offset < headerSize + 4) break;
+        maskingKey = buffer.slice(offset + headerSize, offset + headerSize + 4);
+        headerSize += 4;
+        payloadOffset += 4;
+      }
+
+      // Check if full payload is available
+      if (buffer.length - offset < headerSize + payloadLength) break;
+
+      // Extract payload
+      let payload = buffer.slice(payloadOffset, payloadOffset + payloadLength);
+
+      // Unmask if necessary
+      if (mask && maskingKey) {
+        payload = this._unmask(payload, maskingKey);
+      }
+
+      frames.push({
+        fin,
+        opcode,
+        mask,
+        payloadLength,
+        payload
+      });
+
+      offset += headerSize + payloadLength;
+    }
+
+    return {
+      frames,
+      remaining: buffer.slice(offset)
+    };
+  }
+
+  /**
+   * Unmask payload using XOR operation
+   * @param {Buffer} payload 
+   * @param {Buffer} maskingKey 
+   * @returns {Buffer} Unmasked payload
+   * @private
+   */
+  static _unmask(payload, maskingKey) {
+    const len = payload.length;
+    const unmasked = Buffer.allocUnsafe(len);
+    
+    // Optimized loop for unmasking
+    for (let i = 0; i < len; i++) {
+      unmasked[i] = payload[i] ^ maskingKey[i % 4];
+    }
+    
+    return unmasked;
+  }
+}
+
+export default FrameParser;

package/src/core/HandshakeHandler.js

@@ -0,0 +1,93 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/src/core/HandshakeHandler
+ */
+
+
+import crypto from 'crypto';
+
+class HandshakeHandler {
+  static GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+
+  /**
+   * Parse HTTP headers from raw buffer
+   * @param {Buffer} buffer 
+   * @returns {Object|null} Parsed request or null if incomplete
+   */
+  static parseRequest(buffer) {
+    const str = buffer.toString('utf8');
+    const endOfHeaders = str.indexOf('\r\n\r\n');
+    
+    if (endOfHeaders === -1) return null;
+
+    const lines = str.slice(0, endOfHeaders).split('\r\n');
+    const requestLine = lines;
+    const headers = {};
+
+    // Parse method and path
+    const [method, path] = requestLine.split(' ');
+    
+    // Parse headers
+    for (let i = 1; i < lines.length; i++) {
+      const index = lines[i].indexOf(':');
+      if (index > 0) {
+        const key = lines[i].slice(0, index).trim().toLowerCase();
+        const value = lines[i].slice(index + 1).trim();
+        headers[key] = value;
+      }
+    }
+
+    return {
+      method,
+      path,
+      headers,
+      rawHeaderSize: endOfHeaders + 4
+    };
+  }
+
+  /**
+   * Validate WebSocket upgrade request
+   * @param {Object} request 
+   * @returns {boolean}
+   */
+  static isValidUpgrade(request) {
+    return (
+      request.method === 'GET' &&
+      request.headers['upgrade']?.toLowerCase() === 'websocket' &&
+      request.headers['connection']?.toLowerCase().includes('upgrade') &&
+      request.headers['sec-websocket-key'] &&
+      request.headers['sec-websocket-version'] === '13'
+    );
+  }
+
+  /**
+   * Generate handshake response headers
+   * @param {string} key - Sec-WebSocket-Key from client
+   * @param {string} protocol - Optional subprotocol
+   * @returns {Buffer} Response headers
+   */
+  static createResponse(key, protocol = null) {
+    const accept = crypto
+      .createHash('sha1')
+      .update(key + this.GUID)
+      .digest('base64');
+
+    let response = [
+      'HTTP/1.1 101 Switching Protocols',
+      'Upgrade: websocket',
+      'Connection: Upgrade',
+      `Sec-WebSocket-Accept: ${accept}`
+    ];
+
+    if (protocol) {
+      response.push(`Sec-WebSocket-Protocol: ${protocol}`);
+    }
+
+    response.push('', ''); // Empty line to end headers
+    return Buffer.from(response.join('\r\n'), 'utf8');
+  }
+}
+
+export default HandshakeHandler;

package/src/core/ProtocolHandler.js

@@ -0,0 +1,186 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/src/core/ProtocolHandler
+ */
+
+
+class ProtocolHandler {
+  constructor(options = {}) {
+    this.options = {
+      supportedProtocols: options.supportedProtocols || [],
+      maxMessageSize: options.maxMessageSize || 1024 * 1024, // 1MB
+      autoPing: options.autoPing !== false,
+      pingInterval: options.pingInterval || 30000,
+      pingTimeout: options.pingTimeout || 10000,
+      ...options
+    };
+    
+    this.messageHandlers = new Map();
+    this.protocols = new Set(this.options.supportedProtocols);
+  }
+  
+  /**
+   * Handle WebSocket handshake protocol negotiation
+   * @param {Object} request - HTTP request object
+   * @returns {string|null} Selected protocol or null
+   */
+  negotiateProtocol(request) {
+    const clientProtocols = request.headers['sec-websocket-protocol'];
+    if (!clientProtocols) return null;
+    
+    const requestedProtocols = clientProtocols.split(',').map(p => p.trim());
+    
+    // Find first matching protocol
+    for (const protocol of requestedProtocols) {
+      if (this.protocols.has(protocol)) {
+        return protocol;
+      }
+    }
+    
+    return null;
+  }
+  
+  /**
+   * Register message handler for specific protocol
+   * @param {string} protocol - Protocol name
+   * @param {Function} handler - Message handler function
+   */
+  registerHandler(protocol, handler) {
+    this.messageHandlers.set(protocol, handler);
+  }
+  
+  /**
+   * Process incoming WebSocket message
+   * @param {Object} connection - WebSocket connection
+   * @param {Buffer|string} message - Raw message
+   * @param {boolean} isBinary - Whether message is binary
+   * @returns {Promise<any>} Processing result
+   */
+  async processMessage(connection, message, isBinary = false) {
+    const protocol = connection.protocol;
+    const handler = this.messageHandlers.get(protocol) || this.messageHandlers.get('*');
+    
+    if (!handler) {
+      throw new Error(`No handler registered for protocol: ${protocol}`);
+    }
+    
+    // Validate message size
+    const messageSize = isBinary ? message.length : Buffer.byteLength(message);
+    if (messageSize > this.options.maxMessageSize) {
+      throw new Error(`Message size ${messageSize} exceeds maximum ${this.options.maxMessageSize}`);
+    }
+    
+    // Parse message based on protocol
+    let parsedMessage;
+    if (protocol === 'json') {
+      try {
+        parsedMessage = JSON.parse(message.toString());
+      } catch (error) {
+        throw new Error(`Invalid JSON: ${error.message}`);
+      }
+    } else if (protocol === 'binary') {
+      parsedMessage = message;
+    } else {
+      parsedMessage = message.toString();
+    }
+    
+    // Execute handler
+    return await handler(connection, parsedMessage, isBinary);
+  }
+  
+  /**
+   * Handle ping/pong heartbeat
+   * @param {Object} connection - WebSocket connection
+   * @param {Buffer} data - Ping data
+   * @returns {Buffer} Pong response
+   */
+  handlePing(connection, data) {
+    connection.lastPingTime = Date.now();
+    return data; // Echo back the same data for pong
+  }
+  
+  /**
+   * Handle pong response
+   * @param {Object} connection - WebSocket connection
+   * @param {Buffer} data - Pong data
+   */
+  handlePong(connection, data) {
+    connection.lastPongTime = Date.now();
+    connection.isAlive = true;
+  }
+  
+  /**
+   * Handle close frame
+   * @param {Object} connection - WebSocket connection
+   * @param {number} code - Close code
+   * @param {string} reason - Close reason
+   * @returns {Object} Close response
+   */
+  handleClose(connection, code, reason) {
+    const validCodes = [
+      1000, 1001, 1002, 1003, 1007, 1008, 1009, 1010, 1011,
+      3000, 3999, 4000, 4999
+    ];
+    
+    if (!validCodes.includes(code)) {
+      code = 1002; // Protocol error
+    }
+    
+    return {
+      code,
+      reason: reason || this.getCloseReason(code)
+    };
+  }
+  
+  /**
+   * Get human-readable close reason
+   * @param {number} code - Close code
+   * @returns {string} Reason description
+   */
+  getCloseReason(code) {
+    const reasons = {
+      1000: 'Normal closure',
+      1001: 'Going away',
+      1002: 'Protocol error',
+      1003: 'Unsupported data',
+      1007: 'Invalid frame payload data',
+      1008: 'Policy violation',
+      1009: 'Message too big',
+      1010: 'Mandatory extension',
+      1011: 'Internal server error',
+      3000: 'Custom code start',
+      3999: 'Custom code end',
+      4000: 'Reserved'
+    };
+    
+    return reasons[code] || 'Unknown reason';
+  }
+  
+  /**
+   * Validate WebSocket version
+   * @param {string} version - WebSocket version
+   * @returns {boolean} Whether version is supported
+   */
+  validateVersion(version) {
+    return version === '13'; // RFC 6455
+  }
+  
+  /**
+   * Get protocol statistics
+   * @returns {Object} Statistics object
+   */
+  getStats() {
+    return {
+      supportedProtocols: Array.from(this.protocols),
+      registeredHandlers: this.messageHandlers.size,
+      maxMessageSize: this.options.maxMessageSize,
+      autoPing: this.options.autoPing,
+      pingInterval: this.options.pingInterval,
+      pingTimeout: this.options.pingTimeout
+    };
+  }
+}
+
+export default ProtocolHandler;