@aetherframework/websocket 1.0.0 → 1.0.1

package/src/utils/config-loader.js

@@ -1,183 +0,0 @@
-/**
- * @license MIT
- * Copyright (c) 2026-present AetherFramework Contributors.
- * SPDX-License-Identifier: MIT
- * @module @aetherframework/src/utils/config-loader
- */
-
-import { readFileSync } from 'fs';
-import { resolve } from 'path';
-
-class ConfigLoader {
-  constructor(defaults = {}) {
-    this.defaults = defaults;
-    this.config = { ...defaults };
-  }
-
-  /**
-   * Load config from .env file (simple parser, no deps)
-   * @param {string} path - Path to .env file
-   */
-  loadEnvFile(path = '.env') {
-    try {
-      const content = readFileSync(resolve(process.cwd(), path), 'utf8');
-      const lines = content.split('\n');
-      
-      for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith('#')) continue;
-        
-        const eqIndex = trimmed.indexOf('=');
-        if (eqIndex === -1) continue;
-        
-        const key = trimmed.substring(0, eqIndex).trim();
-        let value = trimmed.substring(eqIndex + 1).trim();
-        
-        // Remove quotes if present
-        if ((value.startsWith('"') && value.endsWith('"')) || 
-            (value.startsWith("'") && value.endsWith("'"))) {
-          value = value.substring(1, value.length - 1);
-        }
-        
-        // Only set if not already set by process.env (priority: Env Var > .env > Default)
-        if (process.env[key] === undefined) {
-          process.env[key] = value;
-        }
-      }
-    } catch (e) {
-      // Ignore if file not found, rely on process.env or defaults
-    }
-  }
-
-  /**
-   * Get a configuration value
-   * @param {string} key - Dot notation key e.g., 'server.port'
-   * @param {any} defaultValue - Fallback value
-   * @returns {any}
-   */
-  get(key, defaultValue) {
-    // Check process.env first (flattened keys usually UPPER_SNAKE_CASE)
-    const envKey = key.replace(/\./g, '_').toUpperCase();
-    
-    if (process.env[envKey] !== undefined) {
-      return this._parseValue(process.env[envKey]);
-    }
-
-    // Check nested defaults
-    const keys = key.split('.');
-    let val = this.defaults;
-    for (const k of keys) {
-      if (val === undefined || val === null) return defaultValue;
-      val = val[k];
-    }
-
-    return val !== undefined ? val : defaultValue;
-  }
-
-  /**
-   * Get number config
-   */
-  getNumber(key, defaultValue) {
-    const val = this.get(key, defaultValue);
-    const num = Number(val);
-    return isNaN(num) ? defaultValue : num;
-  }
-
-  /**
-   * Get boolean config
-   */
-  getBoolean(key, defaultValue) {
-    const val = this.get(key, defaultValue);
-    if (typeof val === 'boolean') return val;
-    if (typeof val === 'string') {
-      return ['true', '1', 'yes'].includes(val.toLowerCase());
-    }
-    return !!val;
-  }
-
-  _parseValue(val) {
-    if (val === 'true') return true;
-    if (val === 'false') return false;
-    if (val === 'null') return null;
-    if (!isNaN(val) && val !== '') return Number(val);
-    return val;
-  }
-
-  /**
-   * Static method to load configuration
-   * @param {Object} userConfig - User-provided configuration
-   * @returns {Object} Merged configuration
-   */
-  static load(userConfig = {}) {
-    // Default configuration
-    const defaults = {
-      driver: process.env.WS_DRIVER || 'tcp',
-      port: parseInt(process.env.WS_PORT) || 8080,
-      host: process.env.WS_HOST || '0.0.0.0',
-      maxPayload: parseInt(process.env.WS_MAX_PAYLOAD) || 1024 * 1024,
-      pingInterval: parseInt(process.env.WS_PING_INTERVAL) || 30000,
-      pingTimeout: parseInt(process.env.WS_PING_TIMEOUT) || 10000,
-      compression: process.env.WS_COMPRESSION === 'true',
-      tls: process.env.WS_TLS === 'true',
-      tlsOptions: {
-        key: process.env.WS_TLS_KEY || null,
-        cert: process.env.WS_TLS_CERT || null,
-        ca: process.env.WS_TLS_CA || null
-      },
-      socketTimeout: parseInt(process.env.WS_SOCKET_TIMEOUT) || 30000,
-      maxConnections: parseInt(process.env.WS_MAX_CONNECTIONS) || 10000,
-      enableStats: process.env.WS_ENABLE_STATS !== 'false'
-    };
-    
-    // Merge configurations (user config overrides env, env overrides defaults)
-    const config = { ...defaults, ...userConfig };
-    
-    // Validate configuration
-    this._validateConfig(config);
-    
-    return config;
-  }
-
-  /**
-   * Validate configuration
-   * @param {Object} config - Configuration to validate
-   * @throws {Error} If configuration is invalid
-   * @private
-   */
-  static _validateConfig(config) {
-    // Validate port
-    if (config.port < 1 || config.port > 65535) {
-      throw new Error(`Invalid port: ${config.port}. Must be between 1 and 65535`);
-    }
-    
-    // Validate maxPayload
-    if (config.maxPayload < 1 || config.maxPayload > 100 * 1024 * 1024) {
-      throw new Error(`Invalid maxPayload: ${config.maxPayload}. Must be between 1 and 100MB`);
-    }
-    
-    // Validate pingInterval
-    if (config.pingInterval < 1000) {
-      throw new Error(`Invalid pingInterval: ${config.pingInterval}. Must be at least 1000ms`);
-    }
-    
-    // Validate pingTimeout
-    if (config.pingTimeout < 1000) {
-      throw new Error(`Invalid pingTimeout: ${config.pingTimeout}. Must be at least 1000ms`);
-    }
-    
-    // Validate driver
-    const validDrivers = ['tcp', 'tls', 'http', 'memory'];
-    if (!validDrivers.includes(config.driver)) {
-      throw new Error(`Invalid driver: ${config.driver}. Must be one of: ${validDrivers.join(', ')}`);
-    }
-    
-    // Validate TLS options if TLS is enabled
-    if (config.tls && config.driver === 'tls') {
-      if (!config.tlsOptions.key || !config.tlsOptions.cert) {
-        throw new Error('TLS requires both key and certificate');
-      }
-    }
-  }
-}
-
-export default ConfigLoader;

package/src/utils/connection-pool.js

@@ -1,110 +0,0 @@
-/**
- * @license MIT
- * Copyright (c) 2026-present AetherFramework Contributors.
- * SPDX-License-Identifier: MIT
- * @module @aetherframework/src/utils/connection-pool
- */
-
-
-class ConnectionPool {
-  constructor(factory, options = {}) {
-    this.factory = factory; // Function to create new connections
-    this.maxSize = options.maxSize || 10;
-    this.acquireTimeout = options.acquireTimeout || 5000;
-    
-    this.available = [];
-    this.inUse = new Set();
-    this.waitingQueue = [];
-  }
-
-  /**
-   * Acquire a connection from the pool
-   * @returns {Promise<Object>}
-   */
-  async acquire() {
-    // Try to get an available healthy connection
-    while (this.available.length > 0) {
-      const conn = this.available.pop();
-      if (conn.readyState === 1) {
-        this.inUse.add(conn);
-        return conn;
-      }
-      // If dead, just discard and try next
-    }
-
-    // If pool not full, create new
-    if (this.inUse.size + this.available.length < this.maxSize) {
-      const conn = await this.factory();
-      this.inUse.add(conn);
-      return conn;
-    }
-
-    // Wait for a connection to be released
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        reject(new Error('Connection pool acquisition timeout'));
-      }, this.acquireTimeout);
-
-      this.waitingQueue.push({ resolve, reject, timeout });
-    });
-  }
-
-  /**
-   * Release a connection back to the pool
-   * @param {Object} conn 
-   */
-  release(conn) {
-    this.inUse.delete(conn);
-
-    // If there are waiters, give it to them
-    if (this.waitingQueue.length > 0) {
-      const { resolve, timeout } = this.waitingQueue.shift();
-      clearTimeout(timeout);
-      this.inUse.add(conn);
-      resolve(conn);
-      return;
-    }
-
-    // Otherwise put back in available if healthy
-    if (conn.readyState === 1) {
-      this.available.push(conn);
-    }
-  }
-
-  /**
-   * Close all connections
-   */
-  async drain() {
-    const closePromises = [];
-    
-    for (const conn of this.available) {
-      closePromises.push(conn.close());
-    }
-    for (const conn of this.inUse) {
-      closePromises.push(conn.close());
-    }
-    
-    this.available = [];
-    this.inUse.clear();
-    
-    // Reject all waiters
-    for (const { reject, timeout } of this.waitingQueue) {
-      clearTimeout(timeout);
-      reject(new Error('Pool drained'));
-    }
-    this.waitingQueue = [];
-
-    await Promise.all(closePromises);
-  }
-  
-  getStats() {
-    return {
-      available: this.available.length,
-      inUse: this.inUse.size,
-      waiting: this.waitingQueue.length,
-      maxSize: this.maxSize
-    };
-  }
-}
-
-export default ConnectionPool;

package/src/utils/error-handler.js

@@ -1,59 +0,0 @@
-/**
- * @license MIT
- * Copyright (c) 2026-present AetherFramework Contributors.
- * SPDX-License-Identifier: MIT
- * @module @aetherframework/src/utils/error-handler
- */
-
-
-class WebSocketError extends Error {
-  constructor(message, code = 1011, isOperational = true) {
-    super(message);
-    this.name = 'WebSocketError';
-    this.code = code;
-    this.isOperational = isOperational; // True if expected (e.g., validation fail), False if bug
-    Error.captureStackTrace(this, this.constructor);
-  }
-}
-
-class ErrorHandler {
-  constructor(logger = console) {
-    this.logger = logger;
-  }
-
-  /**
-   * Handle error in async context
-   * @param {Error} err 
-   * @param {Object} connection - Optional connection to close
-   */
-  handle(err, connection = null) {
-    if (err instanceof WebSocketError) {
-      this.logger.warn(`Operational Error [${err.code}]: ${err.message}`);
-      if (connection && connection.readyState === 1) {
-        connection.close(err.code, err.message);
-      }
-    } else {
-      this.logger.error(`Unexpected Error: ${err.message}\n${err.stack}`);
-      if (connection && connection.readyState === 1) {
-        // 1011 Internal Error
-        connection.close(1011, 'Internal Server Error');
-      }
-      // In a real app, you might want to restart the process here for non-operational errors
-    }
-  }
-
-  /**
-   * Create a standardized error response object
-   */
-  createErrorResponse(message, code = 400) {
-    return {
-      type: 'error',
-      code,
-      message,
-      timestamp: Date.now()
-    };
-  }
-}
-
-export { WebSocketError, ErrorHandler };
-export default ErrorHandler;

package/src/utils/frame-encoder.js

@@ -1,211 +0,0 @@
-/**
- * @license MIT
- * Copyright (c) 2026-present AetherFramework Contributors.
- * SPDX-License-Identifier: MIT
- * @module @aetherframework/src/utils/frame-encoder
- */
-
-
-class FrameEncoder {
-  /**
-   * Create a WebSocket frame
-   * @param {number} opcode - Operation code (1=text, 2=binary, 8=close, 9=ping, 10=pong)
-   * @param {Buffer|string} data - Payload data
-   * @param {boolean} fin - FIN bit (default true)
-   * @param {boolean} mask - Mask bit (default false for server->client)
-   * @returns {Buffer} Encoded frame
-   */
-  /**
- * Parse a WebSocket frame from buffer
- * @param {Buffer} buffer - Raw WebSocket frame buffer
- * @param {number} maxPayload - Maximum allowed payload size
- * @returns {Object} Parsed frame object
- */
-static parse(buffer, maxPayload = 1024 * 1024) {
-  if (!Buffer.isBuffer(buffer) || buffer.length < 2) {
-    throw new Error('Invalid WebSocket frame: buffer too short or not a buffer');
-  }
-
-  let offset = 0;
-  
-  // Byte 1: FIN + RSV1-3 + Opcode
-  const firstByte = buffer[offset++];
-  const fin = (firstByte & 0x80) !== 0;
-  const rsv1 = (firstByte & 0x40) !== 0;
-  const rsv2 = (firstByte & 0x20) !== 0;
-  const rsv3 = (firstByte & 0x10) !== 0;
-  const opcode = firstByte & 0x0F;
-
-  // Byte 2: Mask + Payload Length
-  const secondByte = buffer[offset++];
-  const masked = (secondByte & 0x80) !== 0;
-  let payloadLength = secondByte & 0x7F;
-
-  // Extended payload length
-  if (payloadLength === 126) {
-    if (buffer.length < offset + 2) {
-      throw new Error('Invalid WebSocket frame: insufficient data for extended length');
-    }
-    payloadLength = buffer.readUInt16BE(offset);
-    offset += 2;
-  } else if (payloadLength === 127) {
-    if (buffer.length < offset + 8) {
-      throw new Error('Invalid WebSocket frame: insufficient data for 64-bit length');
-    }
-    const bigLength = buffer.readBigUInt64BE(offset);
-    if (bigLength > Number.MAX_SAFE_INTEGER) {
-      throw new Error('WebSocket frame too large for JavaScript safe integer');
-    }
-    payloadLength = Number(bigLength);
-    offset += 8;
-  }
-
-  // Check payload size limit
-  if (payloadLength > maxPayload) {
-    throw new Error(`Payload exceeds maximum size: ${payloadLength} > ${maxPayload}`);
-  }
-
-  // Masking Key
-  let maskingKey = null;
-  if (masked) {
-    if (buffer.length < offset + 4) {
-      throw new Error('Invalid WebSocket frame: insufficient data for masking key');
-    }
-    maskingKey = buffer.slice(offset, offset + 4);
-    offset += 4;
-  }
-
-  // Payload
-  if (buffer.length < offset + payloadLength) {
-    throw new Error('Invalid WebSocket frame: insufficient data for payload');
-  }
-
-  let payload = buffer.slice(offset, offset + payloadLength);
-
-  // Unmask payload if masked
-  if (masked && maskingKey) {
-    for (let i = 0; i < payload.length; i++) {
-      payload[i] = payload[i]^ maskingKey[i % 4];
-    }
-  }
-
-  return {
-    fin,
-    rsv1,
-    rsv2,
-    rsv3,
-    opcode,
-    masked,
-    payloadLength,
-    maskingKey,
-    payload,
-    totalLength: offset + payloadLength
-  };
-}
-
-  static encode(opcode, data, fin = true, mask = false) {
-    let payload;
-    if (typeof data === 'string') {
-      payload = Buffer.from(data, 'utf8');
-    } else if (Buffer.isBuffer(data)) {
-      payload = data;
-    } else {
-      payload = Buffer.from(String(data));
-    }
-
-    const payloadLength = payload.length;
-    let headerLength = 2;
-
-    if (payloadLength <= 125) {
-      // No extra length bytes
-    } else if (payloadLength <= 65535) {
-      headerLength += 2;
-    } else {
-      headerLength += 8;
-    }
-
-    if (mask) {
-      headerLength += 4;
-    }
-
-    const frame = Buffer.allocUnsafe(headerLength + payloadLength);
-    let offset = 0;
-
-    // Byte 1: FIN + Opcode
-    frame[offset++] = (fin ? 0x80 : 0) | (opcode & 0x0F);
-
-    // Byte 2: Mask + Payload Length
-    let lengthByte = mask ? 0x80 : 0;
-    if (payloadLength <= 125) {
-      lengthByte |= payloadLength;
-      frame[offset++] = lengthByte;
-    } else if (payloadLength <= 65535) {
-      lengthByte |= 126;
-      frame[offset++] = lengthByte;
-      frame.writeUInt16BE(payloadLength, offset);
-      offset += 2;
-    } else {
-      lengthByte |= 127;
-      frame[offset++] = lengthByte;
-      // Write 64-bit length (only lower 53 bits safely used in JS usually, but spec allows 64)
-      frame.writeBigUInt64BE(BigInt(payloadLength), offset);
-      offset += 8;
-    }
-
-    // Masking Key (if masked)
-    if (mask) {
-      const maskingKey = crypto.randomBytes(4);
-      frame.set(maskingKey, offset);
-      offset += 4;
-
-      // Mask payload
-      for (let i = 0; i < payloadLength; i++) {
-        frame[offset + i] = payload[i]^ maskingKey[i % 4];
-      }
-    } else {
-      // Copy payload directly
-      payload.copy(frame, offset);
-    }
-
-    return frame;
-  }
-
-  /**
-   * Create a Close frame
-   * @param {number} code - Status code
-   * @param {string} reason - Reason string
-   * @returns {Buffer}
-   */
-  static createCloseFrame(code = 1000, reason = '') {
-    const reasonBuf = Buffer.from(reason, 'utf8');
-    const payload = Buffer.allocUnsafe(2 + reasonBuf.length);
-    payload.writeUInt16BE(code, 0);
-    if (reasonBuf.length > 0) {
-      reasonBuf.copy(payload, 2);
-    }
-    return this.encode(0x8, payload);
-  }
-
-  /**
-   * Create a Ping frame
-   * @param {Buffer} data - Optional ping data
-   * @returns {Buffer}
-   */
-  static createPingFrame(data = Buffer.alloc(0)) {
-    return this.encode(0x9, data);
-  }
-
-  /**
-   * Create a Pong frame
-   * @param {Buffer} data - Pong data (usually echo of ping)
-   * @returns {Buffer}
-   */
-  static createPongFrame(data = Buffer.alloc(0)) {
-    return this.encode(0xA, data);
-  }
-}
-
-// Import crypto dynamically to avoid circular deps if needed, but top-level is fine here
-import crypto from 'crypto';
-
-export default FrameEncoder;

package/src/utils/heartbeat-manager.js

@@ -1,91 +0,0 @@
-/**
- * @license MIT
- * Copyright (c) 2026-present AetherFramework Contributors.
- * SPDX-License-Identifier: MIT
- * @module @aetherframework/src/utils/heartbeat-manager
- */
-
-class HeartbeatManager {
-  constructor(options = {}) {
-    this.interval = options.interval || 30000; // ms
-    this.timeout = options.timeout || 5000; // ms to wait for pong
-    this.timers = new Map(); // connId -> timerId
-    this.isRunning = false;
-  }
-
-  /**
-   * Start monitoring a connection
-   * @param {Object} connection 
-   */
-  monitor(connection) {
-    if (this.timers.has(connection.id)) return;
-
-    const timer = setInterval(() => {
-      if (connection.readyState !== 1) {
-        this.stop(connection.id);
-        return;
-      }
-
-      // If we are waiting for a pong and didn't get it
-      if (connection.isWaitingForPong) {
-        connection.terminate();
-        this.stop(connection.id);
-        return;
-      }
-
-      // Send Ping
-      connection.isWaitingForPong = true;
-      connection.ping();
-      
-      // Set timeout for Pong
-      const timeoutTimer = setTimeout(() => {
-        if (connection.isWaitingForPong) {
-          connection.terminate();
-          this.stop(connection.id);
-        }
-      }, this.timeout);
-      
-      // Store timeout ID to clear it when pong arrives
-      connection.pongTimeout = timeoutTimer;
-
-    }, this.interval);
-
-    this.timers.set(connection.id, timer);
-  }
-
-  /**
-   * Handle Pong received
-   * @param {Object} connection 
-   */
-  acknowledge(connection) {
-    connection.isWaitingForPong = false;
-    if (connection.pongTimeout) {
-      clearTimeout(connection.pongTimeout);
-      connection.pongTimeout = null;
-    }
-  }
-
-  /**
-   * Stop monitoring
-   * @param {string} connId 
-   */
-  stop(connId) {
-    const timer = this.timers.get(connId);
-    if (timer) {
-      clearInterval(timer);
-      this.timers.delete(connId);
-    }
-  }
-
-  /**
-   * Cleanup all
-   */
-  shutdown() {
-    for (const timer of this.timers.values()) {
-      clearInterval(timer);
-    }
-    this.timers.clear();
-  }
-}
-
-export default HeartbeatManager;