@aetherframework/websocket 1.0.0

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;

package/src/core/WebSocketFactory.js

@@ -0,0 +1,293 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/src/core/WebSocketFactory
+ */
+
+import EventEmitter from 'events';
+import ConnectionManager from './ConnectionManager.js';
+import FrameParser from './FrameParser.js';
+import ProtocolHandler from './ProtocolHandler.js';
+import ConfigLoader from '../utils/config-loader.js';
+
+class WebSocketFactory extends EventEmitter {
+  /**
+   * Create a new WebSocketFactory instance
+   * @param {Object} options - Configuration options
+   */
+  constructor(options = {}) {
+    super();
+    
+    // Load configuration from environment and options
+    this.config = ConfigLoader.load({
+      // Default configuration
+      driver: 'tcp',
+      port: 8080,
+      host: '0.0.0.0',
+      maxPayload: 1024 * 1024, // 1MB
+      pingInterval: 30000, // 30 seconds
+      pingTimeout: 10000, // 10 seconds
+      compression: false,
+      tls: false,
+      tlsOptions: {},
+      // Merge with user options
+      ...options
+    });
+    
+    this.connectionManager = new ConnectionManager();
+    this.frameParser = new FrameParser(this.config);
+    this.protocolHandler = new ProtocolHandler(this.config);
+    this.driver = null;
+    this.server = null;
+    this.middleware = [];
+    
+    // Initialize driver
+    this._initializeDriver();
+  }
+  
+  /**
+   * Initialize the selected transport driver
+   * @private
+   */
+  async _initializeDriver() {
+    try {
+      const driverName = this.config.driver || 'tcp';
+      const driverModule = await import(`../drivers/${driverName}-driver.js`);
+      this.driver = new driverModule.default(this.config);
+      
+      // Set up driver event forwarding
+      this._setupDriverEvents();
+      
+      this.emit('driver:initialized', { driver: driverName });
+    } catch (error) {
+      this.emit('error', {
+        type: 'driver_initialization',
+        message: `Failed to initialize driver: ${error.message}`,
+        error
+      });
+      throw error;
+    }
+  }
+  
+  /**
+   * Set up event forwarding from driver to factory
+   * @private
+   */
+  _setupDriverEvents() {
+    if (!this.driver) return;
+    
+    // Forward all driver events to factory
+    const eventsToForward = [
+      'server:listening',
+      'server:closed',
+      'server:error',
+      'connection',
+      'message',
+      'close',
+      'error',
+      'ping',
+      'pong'
+    ];
+    
+    eventsToForward.forEach(event => {
+      this.driver.on(event, (...args) => {
+        this.emit(event, ...args);
+      });
+    });
+  }
+  
+  /**
+   * Create a WebSocket server
+   * @param {Object} options - Server-specific options
+   * @returns {Promise<Object>} Server instance
+   */
+  async createServer(options = {}) {
+    if (!this.driver) {
+      await this._initializeDriver();
+    }
+    
+    const serverOptions = {
+      ...this.config,
+      ...options
+    };
+    
+    try {
+      this.server = await this.driver.createServer(serverOptions);
+      
+      // CRITICAL FIX: Ensure server:listening event is emitted
+      // Get server address information
+      let addressInfo;
+      if (this.server.address && typeof this.server.address === 'function') {
+        addressInfo = this.server.address();
+      } else if (this.server.address) {
+        addressInfo = this.server.address;
+      } else {
+        addressInfo = {
+          address: serverOptions.host || '0.0.0.0',
+          port: serverOptions.port || 8080,
+          family: 'IPv4'
+        };
+      }
+      
+      // Emit server:listening event with address information
+      // Use setTimeout to ensure event listeners are registered
+      setTimeout(() => {
+        this.emit('server:listening', {
+          host: addressInfo.address,
+          port: addressInfo.port,
+          family: addressInfo.family || 'IPv4'
+        });
+      }, 0);
+      
+      this.emit('server:created', this.server);
+      return this.server;
+    } catch (error) {
+      this.emit('error', {
+        type: 'server_creation',
+        message: `Failed to create server: ${error.message}`,
+        error
+      });
+      throw error;
+    }
+  }
+  
+  /**
+   * Create a WebSocket client connection
+   * @param {string} url - WebSocket URL (ws:// or wss://)
+   * @param {Object} options - Client options
+   * @returns {Promise<Object>} Client connection
+   */
+  async createClient(url, options = {}) {
+    if (!this.driver) {
+      await this._initializeDriver();
+    }
+    
+    const clientOptions = {
+      ...this.config,
+      ...options
+    };
+    
+    try {
+      const client = await this.driver.createClient(url, clientOptions);
+      this.emit('client:created', client);
+      return client;
+    } catch (error) {
+      this.emit('error', {
+        type: 'client_creation',
+        message: `Failed to create client: ${error.message}`,
+        error
+      });
+      throw error;
+    }
+  }
+  
+  /**
+   * Add middleware to the WebSocket pipeline
+   * @param {Function} middleware - Middleware function
+   */
+  use(middleware) {
+    this.middleware.push(middleware);
+  }
+  
+  /**
+   * Broadcast message to all connected clients
+   * @param {string|Buffer} message - Message to broadcast
+   * @param {Function} filter - Optional filter function
+   */
+  broadcast(message, filter = null) {
+    const connections = this.connectionManager.getAll();
+    
+    connections.forEach(connection => {
+      if (!filter || filter(connection)) {
+        try {
+          connection.send(message);
+        } catch (error) {
+          this.emit('error', {
+            type: 'broadcast',
+            message: `Failed to broadcast to connection ${connection.id}`,
+            error,
+            connection
+          });
+        }
+      }
+    });
+  }
+  
+  /**
+   * Send message to specific connection
+   * @param {string} connectionId - Connection ID
+   * @param {string|Buffer} message - Message to send
+   * @returns {boolean} Success status
+   */
+  sendTo(connectionId, message) {
+    const connection = this.connectionManager.get(connectionId);
+    if (connection && connection.readyState === 1) { // OPEN
+      return connection.send(message);
+    }
+    return false;
+  }
+  
+  /**
+   * Get connection by ID
+   * @param {string} connectionId - Connection ID
+   * @returns {Object|null} Connection object or null
+   */
+  getConnection(connectionId) {
+    return this.connectionManager.get(connectionId);
+  }
+  
+  /**
+   * Get all connections
+   * @returns {Array} Array of connection objects
+   */
+  getConnections() {
+    return this.connectionManager.getAll();
+  }
+  
+  /**
+   * Get connection statistics
+   * @returns {Object} Statistics object
+   */
+  getStats() {
+    const connections = this.connectionManager.getAll();
+    
+    return {
+      totalConnections: connections.length,
+      activeConnections: connections.filter(c => c.readyState === 1).length,
+      driver: this.config.driver,
+      uptime: this.server ? Date.now() - this.server.startTime : 0,
+      memoryUsage: process.memoryUsage(),
+      config: {
+        maxPayload: this.config.maxPayload,
+        pingInterval: this.config.pingInterval,
+        pingTimeout: this.config.pingTimeout,
+        compression: this.config.compression
+      }
+    };
+  }
+  
+  /**
+   * Close the WebSocket server
+   * @returns {Promise<void>}
+   */
+  async close() {
+    if (this.server) {
+      await this.driver.closeServer(this.server);
+      this.emit('server:closed');
+    }
+    
+    // Close all connections
+    const connections = this.connectionManager.getAll();
+    connections.forEach(connection => {
+      if (connection.readyState === 1) {
+        connection.close(1000, 'Server shutting down');
+      }
+    });
+    
+    this.connectionManager.clear();
+    this.emit('closed');
+  }
+}
+
+export default WebSocketFactory;