@aetherframework/websocket 1.0.1 → 1.0.3

package/src/middleware/compression.js

@@ -0,0 +1,194 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/src/middleware/compression
+ */
+
+import { createDeflate, createInflate, constants } from 'zlib';
+
+class Compression {
+  constructor(options = {}) {
+    this.options = {
+      level: options.level || constants.Z_DEFAULT_COMPRESSION,
+      memLevel: options.memLevel || 8,
+      chunkSize: options.chunkSize || 1024 * 16,
+      windowBits: options.windowBits || 15,
+      threshold: options.threshold || 1024, // Minimum size to compress
+      ...options
+    };
+    
+    this.compressionEnabled = new Map(); // connectionId -> boolean
+  }
+  
+  /**
+   * Compression middleware function
+   * @returns {Function} Middleware function
+   */
+  middleware() {
+    return async (connection, next) => {
+      // Check if compression is supported and enabled
+      const extensions = connection.headers['sec-websocket-extensions'];
+      if (extensions && extensions.includes('permessage-deflate')) {
+        this.compressionEnabled.set(connection.id, true);
+        connection.supportsCompression = true;
+      }
+      
+      // Override send method to add compression
+      const originalSend = connection.send;
+      connection.send = (data, options = {}) => {
+        return this._sendCompressed(connection, data, options, originalSend);
+      };
+      
+      // Override binary send method
+      const originalSendBinary = connection.sendBinary;
+      if (originalSendBinary) {
+        connection.sendBinary = (data) => {
+          return this._sendCompressed(connection, data, { binary: true }, originalSendBinary);
+        };
+      }
+      
+      next();
+    };
+  }
+  
+  /**
+   * Send compressed data
+   * @param {Object} connection - WebSocket connection
+   * @param {string|Buffer} data - Data to send
+   * @param {Object} options - Send options
+   * @param {Function} originalSend - Original send function
+   * @returns {boolean} Success status
+   * @private
+   */
+  _sendCompressed(connection, data, options, originalSend) {
+    // Check if compression should be used
+    if (!this.compressionEnabled.get(connection.id) || 
+        (typeof data === 'string' && data.length < this.options.threshold) ||
+        (Buffer.isBuffer(data) && data.length < this.options.threshold)) {
+      return originalSend.call(connection, data, options);
+    }
+    
+    try {
+      const isBinary = options.binary || Buffer.isBuffer(data);
+      const input = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
+      
+      // Compress the data
+      const compressed = this._compress(input);
+      
+      // Send with compression flag
+      return originalSend.call(connection, compressed, {
+        ...options,
+        compressed: true,
+        originalSize: input.length,
+        compressedSize: compressed.length
+      });
+    } catch (error) {
+      // Fall back to uncompressed
+      console.warn('Compression failed, falling back to uncompressed:', error.message);
+      return originalSend.call(connection, data, options);
+    }
+  }
+  
+  /**
+   * Compress data using DEFLATE
+   * @param {Buffer} data - Data to compress
+   * @returns {Buffer} Compressed data
+   * @private
+   */
+  _compress(data) {
+    return new Promise((resolve, reject) => {
+      const deflate = createDeflate({
+        level: this.options.level,
+        memLevel: this.options.memLevel,
+        chunkSize: this.options.chunkSize,
+        windowBits: this.options.windowBits
+      });
+      
+      const chunks = [];
+      deflate.on('data', (chunk) => chunks.push(chunk));
+      deflate.on('end', () => resolve(Buffer.concat(chunks)));
+      deflate.on('error', reject);
+      
+      deflate.write(data);
+      deflate.end();
+    });
+  }
+  
+  /**
+   * Decompress data
+   * @param {Buffer} data - Compressed data
+   * @returns {Buffer} Decompressed data
+   * @private
+   */
+  _decompress(data) {
+    return new Promise((resolve, reject) => {
+      const inflate = createInflate({
+        chunkSize: this.options.chunkSize,
+        windowBits: this.options.windowBits
+      });
+      
+      const chunks = [];
+      inflate.on('data', (chunk) => chunks.push(chunk));
+      inflate.on('end', () => resolve(Buffer.concat(chunks)));
+      inflate.on('error', reject);
+      
+      inflate.write(data);
+      inflate.end();
+    });
+  }
+  
+  /**
+   * Handle incoming compressed message
+   * @param {Object} connection - WebSocket connection
+   * @param {Buffer} data - Compressed data
+   * @param {boolean} isBinary - Whether data is binary
+   * @returns {Promise<Buffer|string>} Decompressed data
+   */
+  async handleIncoming(connection, data, isBinary) {
+    if (!this.compressionEnabled.get(connection.id)) {
+      return isBinary ? data : data.toString('utf8');
+    }
+    
+    try {
+      const decompressed = await this._decompress(data);
+      return isBinary ? decompressed : decompressed.toString('utf8');
+    } catch (error) {
+      console.warn('Decompression failed:', error.message);
+      return isBinary ? data : data.toString('utf8');
+    }
+  }
+  
+  /**
+   * Enable compression for a connection
+   * @param {string} connectionId - Connection ID
+   */
+  enableForConnection(connectionId) {
+    this.compressionEnabled.set(connectionId, true);
+  }
+  
+  /**
+   * Disable compression for a connection
+   * @param {string} connectionId - Connection ID
+   */
+  disableForConnection(connectionId) {
+    this.compressionEnabled.set(connectionId, false);
+  }
+  
+  /**
+   * Get compression statistics
+   * @returns {Object} Compression statistics
+   */
+  getStats() {
+    const enabledConnections = Array.from(this.compressionEnabled.values())
+      .filter(enabled => enabled).length;
+    
+    return {
+      enabledConnections,
+      totalConnections: this.compressionEnabled.size,
+      options: this.options
+    };
+  }
+}
+
+export default Compression;

package/src/middleware/message-logger.js

@@ -0,0 +1,322 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/src/middleware/message-logger
+ */
+
+class MessageLogger {
+  constructor(options = {}) {
+    this.options = {
+      level: options.level || 'info', // 'debug', 'info', 'warn', 'error'
+      format: options.format || 'json', // 'json', 'text', 'simple'
+      maxMessageLength: options.maxMessageLength || 1000,
+      logConnect: options.logConnect !== false,
+      logDisconnect: options.logDisconnect !== false,
+      logMessages: options.logMessages !== false,
+      logErrors: options.logErrors !== false,
+      excludeMessages: options.excludeMessages || [],
+      includeMessages: options.includeMessages || null,
+      timestamp: options.timestamp !== false,
+      ...options
+    };
+    
+    this.loggers = {
+      debug: console.debug || console.log,
+      info: console.info || console.log,
+      warn: console.warn || console.log,
+      error: console.error || console.log
+    };
+  }
+  
+  /**
+   * Message logging middleware function
+   * @returns {Function} Middleware function
+   */
+  middleware() {
+    return async (connection, next) => {
+      const connectionId = connection.id;
+      const remoteAddress = connection.remoteAddress || 'unknown';
+      const timestamp = new Date().toISOString();
+      
+      // Log connection
+      if (this.options.logConnect) {
+        this._log('info', {
+          type: 'connect',
+          connectionId,
+          remoteAddress,
+          timestamp,
+          protocol: connection.protocol,
+          headers: this._sanitizeHeaders(connection.headers)
+        });
+      }
+      
+      // Override send to log outgoing messages
+      const originalSend = connection.send;
+      connection.send = (data, options = {}) => {
+        const result = originalSend.call(connection, data, options);
+        
+        if (result && this.options.logMessages && this._shouldLogMessage(data, 'outgoing')) {
+          this._logMessage('outgoing', connectionId, data, options);
+        }
+        
+        return result;
+      };
+      
+      // Listen for incoming messages
+      connection.on('message', (message, isBinary) => {
+        if (this.options.logMessages && this._shouldLogMessage(message, 'incoming')) {
+          this._logMessage('incoming', connectionId, message, { isBinary });
+        }
+      });
+      
+      // Listen for errors
+      connection.on('error', (error) => {
+        if (this.options.logErrors) {
+          this._log('error', {
+            type: 'error',
+            connectionId,
+            remoteAddress,
+            timestamp: new Date().toISOString(),
+            error: error.message || String(error),
+            stack: error.stack
+          });
+        }
+      });
+      
+      // Listen for disconnection
+      connection.on('close', (code, reason) => {
+        if (this.options.logDisconnect) {
+          this._log('info', {
+            type: 'disconnect',
+            connectionId,
+            remoteAddress,
+            timestamp: new Date().toISOString(),
+            code,
+            reason,
+            duration: Date.now() - connection.createdAt
+          });
+        }
+      });
+      
+      next();
+    };
+  }
+  
+  /**
+   * Log a message
+   * @param {string} direction - 'incoming' or 'outgoing'
+   * @param {string} connectionId - Connection ID
+   * @param {any} message - Message content
+   * @param {Object} metadata - Additional metadata
+   * @private
+   */
+  _logMessage(direction, connectionId, message, metadata = {}) {
+    const logEntry = {
+      type: 'message',
+      direction,
+      connectionId,
+      timestamp: new Date().toISOString(),
+      message: this._formatMessage(message),
+      size: this._getMessageSize(message),
+      ...metadata
+    };
+    
+    this._log('debug', logEntry);
+  }
+  
+  /**
+   * Format message for logging
+   * @param {any} message - Message to format
+   * @returns {any} Formatted message
+   * @private
+   */
+  _formatMessage(message) {
+    if (Buffer.isBuffer(message)) {
+      return `<Buffer ${message.length} bytes>`;
+    }
+    
+    if (typeof message === 'string') {
+      if (message.length > this.options.maxMessageLength) {
+        return message.substring(0, this.options.maxMessageLength) + '...';
+      }
+      return message;
+    }
+    
+    if (typeof message === 'object') {
+      try {
+        const str = JSON.stringify(message);
+        if (str.length > this.options.maxMessageLength) {
+          return str.substring(0, this.options.maxMessageLength) + '...';
+        }
+        return JSON.parse(str); // Return parsed to maintain object structure
+      } catch {
+        return '[Circular or non-serializable object]';
+      }
+    }
+    
+    return String(message);
+  }
+  
+  /**
+   * Get message size in bytes
+   * @param {any} message - Message
+   * @returns {number} Size in bytes
+   * @private
+   */
+  _getMessageSize(message) {
+    if (Buffer.isBuffer(message)) {
+      return message.length;
+    }
+    
+    if (typeof message === 'string') {
+      return Buffer.byteLength(message, 'utf8');
+    }
+    
+    if (typeof message === 'object') {
+      try {
+        return Buffer.byteLength(JSON.stringify(message), 'utf8');
+      } catch {
+        return 0;
+      }
+    }
+    
+    return Buffer.byteLength(String(message), 'utf8');
+  }
+  
+  /**
+   * Check if a message should be logged
+   * @param {any} message - Message content
+   * @param {string} direction - Message direction
+   * @returns {boolean} Whether to log the message
+   * @private
+   */
+  _shouldLogMessage(message, direction) {
+    // Check exclude list
+    if (this.options.excludeMessages.length > 0) {
+      const messageStr = typeof message === 'string' ? message : JSON.stringify(message);
+      for (const pattern of this.options.excludeMessages) {
+        if (typeof pattern === 'string' && messageStr.includes(pattern)) {
+          return false;
+        }
+        if (pattern instanceof RegExp && pattern.test(messageStr)) {
+          return false;
+        }
+      }
+    }
+    
+    // Check include list (if specified)
+    if (this.options.includeMessages && this.options.includeMessages.length > 0) {
+      const messageStr = typeof message === 'string' ? message : JSON.stringify(message);
+      for (const pattern of this.options.includeMessages) {
+        if (typeof pattern === 'string' && messageStr.includes(pattern)) {
+          return true;
+        }
+        if (pattern instanceof RegExp && pattern.test(messageStr)) {
+          return true;
+        }
+      }
+      return false;
+    }
+    
+    return true;
+  }
+  
+  /**
+   * Sanitize headers for logging
+   * @param {Object} headers - HTTP headers
+   * @returns {Object} Sanitized headers
+   * @private
+   */
+  _sanitizeHeaders(headers) {
+    if (!headers) return {};
+    
+    const sanitized = { ...headers };
+    
+    // Remove sensitive headers
+    const sensitiveHeaders = [
+      'authorization',
+      'cookie',
+      'set-cookie',
+      'proxy-authorization',
+      'x-api-key',
+      'x-auth-token'
+    ];
+    
+    sensitiveHeaders.forEach(header => {
+      if (sanitized[header]) {
+        sanitized[header] = '[REDACTED]';
+      }
+      if (sanitized[header.toLowerCase()]) {
+        sanitized[header.toLowerCase()] = '[REDACTED]';
+      }
+    });
+    
+    return sanitized;
+  }
+  
+  /**
+   * Log with specified level
+   * @param {string} level - Log level
+   * @param {Object} data - Log data
+   * @private
+   */
+  _log(level, data) {
+    const logger = this.loggers[level];
+    if (!logger || !this._shouldLogLevel(level)) return;
+    
+    const formatted = this._formatLogEntry(data);
+    logger(formatted);
+  }
+  
+  /**
+   * Format log entry based on format option
+   * @param {Object} data - Log data
+   * @returns {string} Formatted log entry
+   * @private
+   */
+  _formatLogEntry(data) {
+    switch (this.options.format) {
+      case 'json':
+        return JSON.stringify(data, null, 2);
+      
+      case 'text':
+        const timestamp = this.options.timestamp ? `[${data.timestamp || new Date().toISOString()}] ` : '';
+        const type = data.type ? `[${data.type.toUpperCase()}] ` : '';
+        const connection = data.connectionId ? `[${data.connectionId.substring(0, 8)}] ` : '';
+        const message = data.message ? `: ${typeof data.message === 'object' ? JSON.stringify(data.message) : data.message}` : '';
+        return `${timestamp}${type}${connection}${message}`;
+      
+      case 'simple':
+      default:
+        return `${data.type || 'log'}: ${data.message || JSON.stringify(data)}`;
+    }
+  }
+  
+  /**
+   * Check if level should be logged
+   * @param {string} level - Log level to check
+   * @returns {boolean} Whether to log at this level
+   * @private
+   */
+  _shouldLogLevel(level) {
+    const levels = ['debug', 'info', 'warn', 'error'];
+    const currentLevelIndex = levels.indexOf(this.options.level);
+    const checkLevelIndex = levels.indexOf(level);
+    
+    return checkLevelIndex >= currentLevelIndex;
+  }
+  
+  /**
+   * Get logging statistics
+   * @returns {Object} Logging statistics
+   */
+  getStats() {
+    return {
+      options: this.options,
+      timestamp: new Date().toISOString()
+    };
+  }
+}
+
+export default MessageLogger;

package/src/middleware/rate-limiter.js

@@ -0,0 +1,142 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/src/middleware/rate-limiter
+ */
+
+class RateLimiter {
+  constructor(options = {}) {
+    this.options = {
+      windowMs: options.windowMs || 60000, // 1 minute window
+      max: options.max || 100, // Max requests per window
+      message: options.message || 'Rate limit exceeded',
+      statusCode: options.statusCode || 429,
+      skipFailedRequests: options.skipFailedRequests || false,
+      skipSuccessfulRequests: options.skipSuccessfulRequests || false,
+      keyGenerator: options.keyGenerator || ((connection) => connection.id),
+      skip: options.skip || (() => false),
+      ...options
+    };
+    
+    this.store = new Map(); // key -> { count: number, resetTime: number }
+    this.cleanupInterval = setInterval(() => this._cleanup(), this.options.windowMs);
+  }
+  
+  /**
+   * Rate limiting middleware function
+   * @returns {Function} Middleware function
+   */
+  middleware() {
+    return async (connection, next) => {
+      // Skip if configured
+      if (this.options.skip(connection)) {
+        return next();
+      }
+      
+      const key = this.options.keyGenerator(connection);
+      const now = Date.now();
+      
+      // Get or create rate limit info
+      let info = this.store.get(key);
+      if (!info || info.resetTime < now) {
+        info = {
+          count: 0,
+          resetTime: now + this.options.windowMs
+        };
+        this.store.set(key, info);
+      }
+      
+      // Check rate limit
+      if (info.count >= this.options.max) {
+        const retryAfter = Math.ceil((info.resetTime - now) / 1000);
+        
+        connection.sendJSON({
+          type: 'error',
+          code: this.options.statusCode,
+          message: this.options.message,
+          retryAfter
+        });
+        
+        if (this.options.statusCode === 429) {
+          connection.close(1008, 'Rate limit exceeded');
+        }
+        
+        return; // Stop further processing
+      }
+      
+      // Increment counter
+      info.count++;
+      
+      // Add rate limit headers to response
+      connection.rateLimit = {
+        limit: this.options.max,
+        remaining: this.options.max - info.count,
+        reset: info.resetTime
+      };
+      
+      next();
+    };
+  }
+  
+  /**
+   * Clean up expired rate limit records
+   * @private
+   */
+  _cleanup() {
+    const now = Date.now();
+    for (const [key, info] of this.store.entries()) {
+      if (info.resetTime < now) {
+        this.store.delete(key);
+      }
+    }
+  }
+  
+  /**
+   * Reset rate limit for a specific key
+   * @param {string} key - Rate limit key
+   */
+  resetKey(key) {
+    this.store.delete(key);
+  }
+  
+  /**
+   * Reset all rate limits
+   */
+  resetAll() {
+    this.store.clear();
+  }
+  
+  /**
+   * Get rate limit info for a key
+   * @param {string} key - Rate limit key
+   * @returns {Object|null} Rate limit information
+   */
+  getInfo(key) {
+    const info = this.store.get(key);
+    if (!info) return null;
+    
+    const now = Date.now();
+    if (info.resetTime < now) return null;
+    
+    return {
+      limit: this.options.max,
+      remaining: this.options.max - info.count,
+      reset: info.resetTime,
+      windowMs: this.options.windowMs
+    };
+  }
+  
+  /**
+   * Destroy the rate limiter
+   */
+  destroy() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.store.clear();
+  }
+}
+
+export default RateLimiter;