@aetherframework/websocket 1.0.0

package/README.md

@@ -0,0 +1,213 @@
+Aether WebSocket API 🚀
+
+High-Performance, Zero-Dependency WebSocket Server & Client for Node.js
+
+Aether is a lightweight, robust, and highly efficient WebSocket implementation built from the ground up for Node.js. Unlike heavy frameworks that bundle unnecessary features, Aether focuses on raw speed, memory efficiency, and strict RFC 6455 compliance.
+
+✨ Why Choose Aether?
+
+1. ⚡ Blazing Fast Performance
+Built with a custom binary frame parser (`FrameParser`) and encoder (`FrameEncoder`), Aether minimizes garbage collection pressure and maximizes throughput. It handles thousands of concurrent connections with minimal CPU overhead.
+
+2. 🪶 Zero Dependencies
+Aether relies only on Node.js built-in modules (`net`, `http`, `crypto`, `events`). No `npm install` bloat, no security vulnerabilities from third-party packages, and a tiny footprint ideal for microservices and serverless environments.
+
+3. 🛡️ Robust & Secure
+- Strict Protocol Compliance: Fully adheres to RFC 6455.
+- Memory Safety: Built-in protection against memory leaks via efficient buffer management.
+- Error Resilience: Graceful handling of malformed frames, unexpected disconnections, and protocol errors.
+
+
+> Best For: Developers who need a reliable, lightweight, and transparent WebSocket solution without the baggage of large frameworks.
+
+---
+
+📦 Installation
+
+Install Aether WebSocket via npm:
+
+```bash
+npm install aetherframework-websocket
+```
+
+---
+
+🚀 Quick Start
+
+1. Create a WebSocket Server
+
+```javascript
+import { createWebSocketFactory } from 'aetherframework-websocket';
+
+// Create a WebSocket factory instance
+const factory = createWebSocketFactory({
+  port: 8080,
+  host: '0.0.0.0',
+  maxPayload: 1024 * 1024, // 1MB max message size
+  pingInterval: 30000,     // Send ping every 30s
+});
+
+// Handle new connections
+factory.on('connection', (connection) => {
+  console.log(`✅ New connection: ${connection.id}`);
+
+  // Send a welcome message
+  connection.socket.write(factory._encodeFrame(0x1, Buffer.from('Welcome to Aether!')));
+
+  // Handle incoming messages
+  factory.on('message', (conn, data, isBinary) => {
+    console.log(`📨 Received from ${conn.id}:`, data.toString());
+    
+    // Echo back
+    conn.socket.write(factory._encodeFrame(0x1, Buffer.from('Echo: ' + data)));
+  });
+
+  // Handle disconnection
+  factory.on('close', (conn, code, reason) => {
+    console.log(`❌ Disconnected: ${conn.id} (Code: ${code})`);
+  });
+});
+
+// Start the server
+async function start() {
+  try {
+    const server = await factory.createServer();
+    console.log(`🚀 Aether Server running on ws://${server.address.address}:${server.address.port}`);
+  } catch (error) {
+    console.error('Failed to start server:', error);
+  }
+}
+
+start();
+```
+
+2. Create a WebSocket Client
+
+```javascript
+import { createWebSocketFactory } from 'aetherframework-websocket';
+
+const factory = createWebSocketFactory();
+
+async function connect() {
+  try {
+    const client = await factory.createClient('ws://localhost:8080');
+    
+    console.log('✅ Connected to server');
+
+    // Listen for messages
+    factory.on('message', (conn, data, isBinary) => {
+      console.log('📨 Server says:', data.toString());
+      
+      // Close connection after receiving
+      client.close(1000, 'Goodbye');
+    });
+
+    // Send a message
+    client.send('Hello Aether!');
+
+  } catch (error) {
+    console.error('Connection failed:', error);
+  }
+}
+
+connect();
+```
+
+---
+
+📚 API Reference
+
+`createWebSocketFactory` Function
+
+```javascript
+createWebSocketFactory(config)
+```
+- `config.port` (number): Server port (default: `80`).
+- `config.host` (string): Server host (default: `'0.0.0.0'`).
+- `config.maxPayload` (number): Max message size in bytes (default: `1048576`).
+- `config.pingInterval` (number): Milliseconds between pings (default: `null`).
+
+Available Methods
+
+| Method | Description | Returns |
+| :--- | :--- | :--- |
+| `createServer(options)` | Starts the HTTP/WebSocket server. | `Promise<{ type, address, close }>` |
+| `createClient(url, options)` | Creates a WebSocket client connection. | `Promise<{ id, socket, send, close }>` |
+| `closeServer()` | Gracefully shuts down the server. | `Promise<void>` |
+| `getStats()` | Returns current server statistics. | `Object` |
+
+Events
+
+| Event | Callback Arguments | Description |
+| :--- | :--- | :--- |
+| `connection` | `(connection)` | Fired when a new client connects. |
+| `message` | `(connection, data, isBinary)` | Fired when a message is received. |
+| `close` | `(connection, code, reason)` | Fired when a connection closes. |
+| `error` | `(errorObj)` | Fired on parsing or socket errors. |
+| `ping` | `(connection, payload)` | Fired when a ping is received. |
+| `pong` | `(connection, payload)` | Fired when a pong is received. |
+
+---
+
+🛠️ Advanced Configuration
+
+Handling Binary Data
+Aether seamlessly handles both text and binary frames.
+
+```javascript
+factory.on('message', (conn, data, isBinary) => {
+  if (isBinary) {
+    console.log('Received binary data:', data.length, 'bytes');
+    // Process Buffer directly
+  } else {
+    console.log('Received text:', data.toString());
+  }
+});
+```
+
+Custom Heartbeat Logic
+If you disable `pingInterval` in config, you can implement custom health checks:
+
+```javascript
+factory.on('connection', (conn) => {
+  conn.isAlive = true;
+  
+  const interval = setInterval(() => {
+    if (!conn.isAlive) {
+      console.log('Terminating inactive connection');
+      conn.socket.destroy();
+      return clearInterval(interval);
+    }
+    conn.isAlive = false;
+    factory._sendPing(conn.socket);
+  }, 30000);
+
+  factory.on('pong', () => {
+    conn.isAlive = true;
+  });
+});
+```
+
+---
+
+📊 Statistics & Monitoring
+
+Use `getStats()` to monitor server health in real-time:
+
+```javascript
+setInterval(() => {
+  const stats = factory.getStats();
+  console.log(`Active Connections: ${stats.connections}`);
+  console.log(`Uptime: ${stats.uptime}ms`);
+  console.log(`Memory RSS: ${stats.memory.rss} bytes`);
+}, 10000);
+```
+---
+
+📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+Made with ❤️ by the Aether Team

package/index.js

@@ -0,0 +1,59 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/index
+ */
+
+
+import WebSocketFactory from './src/core/WebSocketFactory.js';
+import ConfigLoader from './src/utils/config-loader.js';
+
+/**
+ * Create a WebSocket factory instance
+ * @param {Object} options - Configuration options
+ * @returns {WebSocketFactory} Factory instance
+ */
+export function createWebSocketFactory(options = {}) {
+  // Load environment configuration
+  const config = ConfigLoader.load(options);
+  return new WebSocketFactory(config);
+}
+
+/**
+ * Create a WebSocket server
+ * @param {Object} options - Server options
+ * @returns {Promise<Object>} WebSocket server instance
+ */
+export async function createServer(options = {}) {
+  const factory = createWebSocketFactory(options);
+  return await factory.createServer();
+}
+
+/**
+ * Create a WebSocket client
+ * @param {string} url - WebSocket URL
+ * @param {Object} options - Client options
+ * @returns {Promise<Object>} WebSocket client instance
+ */
+export async function createClient(url, options = {}) {
+  const factory = createWebSocketFactory(options);
+  return await factory.createClient(url);
+}
+
+// Export core components
+export { default as WebSocketFactory } from './src/core/WebSocketFactory.js';
+export { default as ConnectionManager } from './src/core/ConnectionManager.js';
+export { default as FrameParser } from './src/core/FrameParser.js';
+export { default as ProtocolHandler } from './src/core/ProtocolHandler.js';
+
+// Export middleware
+export { default as AuthMiddleware } from './src/middleware/auth-middleware.js';
+export { default as RateLimiter } from './src/middleware/rate-limiter.js';
+export { default as Compression } from './src/middleware/compression.js';
+
+// Export utilities
+export { default as ConfigLoader } from './src/utils/config-loader.js';
+export { default as HeartbeatManager } from './src/utils/heartbeat-manager.js';
+
+export default createWebSocketFactory;

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@aetherframework/websocket",
+  "version": "1.0.0",
+  "description": "Zero-dependency WebSocket server implementation for AetherJS",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "type": "module",
+  "scripts": {
+    "start:basic": "node examples/basic-server.js",
+    "start:chat": "node examples/chat-server.js",
+    "start:api": "node examples/realtime-api.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "websocket",
+    "factory-pattern",
+    "zero-dependency",
+    "high-performance",
+    "esm"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "dotenv": "^16.6.1",
+    "eslint": "^8.0.0",
+    "jest": "^29.0.0",
+    "jsdoc": "^4.0.0",
+    "prettier": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+ "author": "Aether Framework Team",
+   "license": "MIT",
+   "repository": {
+      "type": "git",
+      "url": "https://github.com/aetherjs/aetherframework-websocket.git"
+   },
+   "bugs": {
+      "url": "https://github.com/aetherjs/aetherframework-websocket/issues",
+      "email": "support@aetherjs.org"
+   },
+   "homepage": "https://www.aetherjs.org",
+  "files": [
+    "index.js",
+    "server.js",
+    "src/", 
+    "connection.js",
+    "README.md",
+    "LICENSE"
+  ]
+}

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;