@aetherframework/websocket 1.0.0 → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present, AetherFramework Contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/examples/basic-server.js

@@ -0,0 +1,95 @@
+/**
+ * @file Basic WebSocket Server Example - Final Version
+ */
+
+import { WebSocketFactory } from '../index.js';
+
+async function main() {
+  try {
+    // Create WebSocket factory instance
+    const factory = new WebSocketFactory({
+      driver: 'http', // Use HTTP upgrade driver
+      port: process.env.WS_PORT || 8080,
+      host: process.env.WS_HOST || '0.0.0.0',
+      maxPayload: 1024 * 1024, // 1MB
+      pingInterval: 30000, // 30 seconds heartbeat
+      pingTimeout: 10000 // 10 seconds timeout
+    });
+
+    // Create server
+    const server = await factory.createServer();
+    
+    console.log('✅ WebSocket server starting...');
+    
+    // Listen for connection events
+    factory.on('connection', (connection) => {
+      console.log(`🔗 Client connected: ${connection.id} from ${connection.remoteAddress || 'unknown'}`);
+      
+      // Send welcome message
+      connection.send(JSON.stringify({
+        type: 'welcome',
+        message: 'Connected to WebSocket server',
+        connectionId: connection.id,
+        timestamp: Date.now()
+      }));
+      
+      // Listen for message events
+      connection.on('message', (data, isBinary) => {
+        const message = isBinary ? '[Binary Data]' : data.toString();
+        console.log(`📨 Received from ${connection.id}: ${message}`);
+        
+        // Echo back the message
+        connection.send(`Echo: ${message}`);
+      });
+      
+      // Listen for close events
+      connection.on('close', (code, reason) => {
+        console.log(`❌ Client disconnected: ${connection.id}, code: ${code}, reason: ${reason}`);
+      });
+      
+      // Listen for error events
+      connection.on('error', (error) => {
+        console.error(`⚠️ Connection error for ${connection.id}:`, error);
+      });
+    });
+    
+    // Listen for server listening event
+    factory.on('server:listening', (address) => {
+      console.log(`🚀 Server listening on ws://${address.host}:${address.port}`);
+      console.log('📡 Waiting for connections...');
+      console.log('🛑 Press Ctrl+C to stop the server');
+    });
+    
+    // Listen for server error events
+    factory.on('error', (error) => {
+      console.error('💥 Server error:', error);
+    });
+    
+    // Graceful shutdown handling
+    process.on('SIGINT', async () => {
+      console.log('\n🔄 Shutting down WebSocket server...');
+      try {
+        await factory.close();
+        console.log('✅ Server closed successfully');
+        process.exit(0);
+      } catch (error) {
+        console.error('❌ Error closing server:', error);
+        process.exit(1);
+      }
+    });
+    
+    // Keep process running
+    process.on('SIGTERM', async () => {
+      console.log('\n🔄 Received SIGTERM, shutting down...');
+      await factory.close();
+      process.exit(0);
+    });
+    
+  } catch (error) {
+    console.error('❌ Failed to start server:', error);
+    process.exit(1);
+  }
+}
+
+// Start the server
+main();

package/examples/chat-server.js

@@ -0,0 +1,416 @@
+/**
+ * @file Chat Server Example using Rooms
+ * @description Complete chat server with room-based broadcasting with event fixes
+ */
+
+import { WebSocketFactory } from '../index.js';
+import BroadcastManager from '../src/middleware/broadcast-manager.js';
+
+async function main() {
+  try {
+    console.log('🚀 Starting chat server...');
+    console.log(`📡 Port: ${process.env.WS_PORT || 3000}`);
+    console.log(`🏠 Host: ${process.env.WS_HOST || '0.0.0.0'}`);
+    
+    // Create WebSocket factory instance
+    const factory = new WebSocketFactory({
+      driver: 'http',
+      port: process.env.WS_PORT || 3000,
+      host: process.env.WS_HOST || '0.0.0.0',
+      maxPayload: 1024 * 1024,
+      pingInterval: 30000,
+      pingTimeout: 10000
+    });
+
+    // Create broadcast manager
+    const broadcastMgr = new BroadcastManager();
+    
+    // Track if server:listening event has been fired
+    let serverListeningEventFired = false;
+    
+    // Listen for server listening event
+    factory.on('server:listening', (address) => {
+      serverListeningEventFired = true;
+      console.log(`\n🎉 ============================================`);
+      console.log(`🚀 Chat server listening on ws://${address.host}:${address.port}`);
+      console.log(`💬 Room-based chat server ready for connections`);
+      console.log(`🛑 Press Ctrl+C to stop the server`);
+      console.log(`============================================\n`);
+    });
+    
+    // Listen for driver initialization (with duplicate prevention)
+    let driverInitialized = false;
+    factory.on('driver:initialized', (info) => {
+      if (!driverInitialized) {
+        driverInitialized = true;
+        console.log(`🔧 Driver initialized: ${info.driver}`);
+        if (factory.connectionManager) {
+          console.log('🔗 Connection manager initialized');
+        }
+      }
+    });
+    
+    // Listen for connection events
+    factory.on('connection', (connection) => {
+      console.log(`👤 User connected: ${connection.id}`);
+      
+      // Apply broadcast manager middleware
+      broadcastMgr.middleware()(connection, () => {
+        console.log(`✅ Broadcast middleware applied for ${connection.id}`);
+      });
+      
+      // Send welcome message
+      connection.send(JSON.stringify({
+        type: 'system',
+        message: 'Welcome to Chat Server!',
+        commands: {
+          join: 'Send {"type":"join","room":"room-name"} to join a room',
+          chat: 'Send {"type":"chat","room":"room-name","message":"your message"} to send message',
+          leave: 'Send {"type":"leave","room":"room-name"} to leave a room',
+          list: 'Send {"type":"list"} to list all rooms'
+        },
+        connectionId: connection.id,
+        timestamp: Date.now()
+      }));
+      
+      // Listen for message events
+      connection.on('message', (data, isBinary) => {
+        if (isBinary) {
+          connection.send(JSON.stringify({
+            type: 'error',
+            message: 'Binary messages not supported in chat'
+          }));
+          return;
+        }
+        
+        try {
+          const message = JSON.parse(data.toString());
+          console.log(`📨 Message from ${connection.id}:`, message);
+          
+          switch (message.type) {
+            case 'join':
+              handleJoinRoom(connection, message);
+              break;
+              
+            case 'leave':
+              handleLeaveRoom(connection, message);
+              break;
+              
+            case 'chat':
+              handleChatMessage(connection, message);
+              break;
+              
+            case 'list':
+              handleListRooms(connection);
+              break;
+              
+            case 'users':
+              handleListUsers(connection, message);
+              break;
+              
+            default:
+              connection.send(JSON.stringify({
+                type: 'error',
+                message: 'Unknown message type',
+                validTypes: ['join', 'leave', 'chat', 'list', 'users']
+              }));
+          }
+        } catch (error) {
+          console.error(`❌ JSON parse error from ${connection.id}:`, error.message);
+          connection.send(JSON.stringify({
+            type: 'error',
+            message: 'Invalid JSON format',
+            example: '{"type":"join","room":"general"}'
+          }));
+        }
+      });
+      
+      // Listen for close events
+      connection.on('close', (code, reason) => {
+        console.log(`👋 User disconnected: ${connection.id}, code: ${code}, reason: ${reason}`);
+        
+        // Leave all rooms when user disconnects
+        const userRooms = connection.rooms ? connection.rooms() : [];
+        userRooms.forEach(room => {
+          connection.leave(room);
+          broadcastToRoom(room, {
+            type: 'system',
+            message: `User ${connection.id.substring(0, 8)} left the room`,
+            timestamp: Date.now()
+          });
+        });
+      });
+      
+      // Listen for error events
+      connection.on('error', (error) => {
+        console.error(`⚠️ Connection error for ${connection.id}:`, error);
+      });
+    });
+    
+    // Listen for server error events
+    factory.on('error', (error) => {
+      console.error('💥 Server error:', error);
+    });
+    
+    // Create server
+    console.log('🔄 Creating server...');
+    const server = await factory.createServer();
+    console.log('✅ Server instance created:', server);
+    
+    // Fallback: If server:listening event doesn't fire within 500ms, show server info manually
+    setTimeout(() => {
+      if (!serverListeningEventFired) {
+        console.log('\n⚠️  Server:listening event was not fired, checking server status manually...');
+        
+        // Try to get server address directly
+        if (server && server.address) {
+          const address = typeof server.address === 'function' ? server.address() : server.address;
+          if (address && address.port) {
+            console.log(`🎉 ============================================`);
+            console.log(`🚀 Chat server listening on ws://${address.address || '0.0.0.0'}:${address.port}`);
+            console.log(`💬 Room-based chat server ready for connections`);
+            console.log(`🛑 Press Ctrl+C to stop the server`);
+            console.log(`============================================\n`);
+          } else {
+            console.log(`🌐 Server should be available at: ws://${process.env.WS_HOST || '0.0.0.0'}:${process.env.WS_PORT || 3000}`);
+          }
+        } else {
+          console.log(`🌐 Server should be available at: ws://${process.env.WS_HOST || '0.0.0.0'}:${process.env.WS_PORT || 3000}`);
+        }
+      }
+    }, 500);
+    
+    // Display connection instructions
+    console.log('\n📋 How to connect:');
+    console.log('1. Open browser developer tools (F12)');
+    console.log('2. In Console tab, run:');
+    console.log(`
+const ws = new WebSocket('ws://localhost:${process.env.WS_PORT || 3000}');
+ws.onopen = () => {
+  console.log('Connected!');
+  ws.send(JSON.stringify({type:"join",room:"general"}));
+  ws.send(JSON.stringify({type:"chat",room:"general",message:"Hello!"}));
+};
+ws.onmessage = (e) => console.log('Server:', JSON.parse(e.data));
+    `);
+    
+    // Room handling functions
+    function handleJoinRoom(connection, message) {
+      if (!message.room) {
+        connection.send(JSON.stringify({
+          type: 'error',
+          message: 'Room name is required',
+          example: '{"type":"join","room":"general"}'
+        }));
+        return;
+      }
+      
+      const roomName = message.room.trim();
+      if (roomName.length === 0) {
+        connection.send(JSON.stringify({
+          type: 'error',
+          message: 'Room name cannot be empty'
+        }));
+        return;
+      }
+      
+      // Join room
+      connection.join(roomName);
+      
+      console.log(`📥 ${connection.id} joined room: ${roomName}`);
+      
+      // Send confirmation message
+      connection.send(JSON.stringify({
+        type: 'system',
+        message: `Joined room: ${roomName}`,
+        room: roomName,
+        timestamp: Date.now()
+      }));
+      
+      // Broadcast to other users in the room
+      broadcastToRoom(roomName, {
+        type: 'system',
+        message: `New user ${connection.id.substring(0, 8)} joined the room`,
+        userCount: getRoomUserCount(roomName),
+        timestamp: Date.now()
+      }, connection.id); // Exclude self
+    }
+    
+    function handleLeaveRoom(connection, message) {
+      if (!message.room) {
+        connection.send(JSON.stringify({
+          type: 'error',
+          message: 'Room name is required',
+          example: '{"type":"leave","room":"general"}'
+        }));
+        return;
+      }
+      
+      const roomName = message.room.trim();
+      connection.leave(roomName);
+      
+      console.log(`📤 ${connection.id} left room: ${roomName}`);
+      
+      connection.send(JSON.stringify({
+        type: 'system',
+        message: `Left room: ${roomName}`,
+        room: roomName,
+        timestamp: Date.now()
+      }));
+      
+      // Notify other users in the room
+      broadcastToRoom(roomName, {
+        type: 'system',
+        message: `User ${connection.id.substring(0, 8)} left the room`,
+        userCount: getRoomUserCount(roomName),
+        timestamp: Date.now()
+      });
+    }
+    
+    function handleChatMessage(connection, message) {
+      if (!message.room || !message.message) {
+        connection.send(JSON.stringify({
+          type: 'error',
+          message: 'Room and message are required',
+          example: '{"type":"chat","room":"general","message":"Hello!"}'
+        }));
+        return;
+      }
+      
+      const roomName = message.room.trim();
+      const chatMessage = message.message.trim();
+      
+      // Check if user is in the room
+      const userRooms = connection.rooms ? connection.rooms() : [];
+      if (!userRooms.includes(roomName)) {
+        connection.send(JSON.stringify({
+          type: 'error',
+          message: `You are not in room: ${roomName}`,
+          suggestion: 'Send {"type":"join","room":"room-name"} first'
+        }));
+        return;
+      }
+      
+      console.log(`💬 ${connection.id} -> ${roomName}: ${chatMessage}`);
+      
+      // Broadcast message to room
+      broadcastToRoom(roomName, {
+        type: 'chat',
+        from: connection.id.substring(0, 8),
+        room: roomName,
+        message: chatMessage,
+        timestamp: Date.now()
+      }, connection.id); // Exclude sender
+      
+      // Send confirmation to sender
+      connection.send(JSON.stringify({
+        type: 'sent',
+        room: roomName,
+        message: chatMessage,
+        timestamp: Date.now()
+      }));
+    }
+    
+    function handleListRooms(connection) {
+      // Get all rooms (simplified implementation)
+      const roomInfo = {
+        type: 'rooms',
+        count: 0,
+        rooms: [],
+        timestamp: Date.now()
+      };
+      
+      connection.send(JSON.stringify(roomInfo));
+    }
+    
+    function handleListUsers(connection, message) {
+      if (!message.room) {
+        connection.send(JSON.stringify({
+          type: 'error',
+          message: 'Room name is required',
+          example: '{"type":"users","room":"general"}'
+        }));
+        return;
+      }
+      
+      const roomName = message.room.trim();
+      const userInfo = {
+        type: 'users',
+        room: roomName,
+        count: 0,
+        users: [],
+        timestamp: Date.now()
+      };
+      
+      connection.send(JSON.stringify(userInfo));
+    }
+    
+    function broadcastToRoom(roomName, message, excludeConnectionId = null) {
+      // Simplified broadcast implementation
+      console.log(`📢 Broadcasting to room ${roomName}:`, message);
+      
+      // In a real implementation, use broadcast manager's room functionality
+      // For now, we'll use factory.broadcast with filtering
+      if (factory.broadcast) {
+        factory.broadcast(JSON.stringify(message), (conn) => {
+          // Exclude specific connection
+          if (excludeConnectionId && conn.id === excludeConnectionId) {
+            return false;
+          }
+          
+          // Check if connection is in the room
+          const userRooms = conn.rooms ? conn.rooms() : [];
+          return userRooms.includes(roomName);
+        });
+      }
+    }
+    
+    function getRoomUserCount(roomName) {
+      // Simplified implementation
+      return 1;
+    }
+    
+    // Graceful shutdown handling
+    process.on('SIGINT', async () => {
+      console.log('\n🔄 Shutting down chat server...');
+      try {
+        // Notify all users about server shutdown
+        if (factory.broadcast) {
+          factory.broadcast(JSON.stringify({
+            type: 'system',
+            message: 'Server is shutting down. Goodbye!',
+            timestamp: Date.now()
+          }));
+        }
+        
+        await factory.close();
+        console.log('✅ Chat server closed successfully');
+        process.exit(0);
+      } catch (error) {
+        console.error('❌ Error closing server:', error);
+        process.exit(1);
+      }
+    });
+    
+    process.on('SIGTERM', async () => {
+      console.log('\n🔄 Received SIGTERM, shutting down...');
+      await factory.close();
+      process.exit(0);
+    });
+    
+    // Keep the process running
+    console.log('⏳ Server is running and waiting for connections...');
+    
+  } catch (error) {
+    console.error('❌ Failed to start chat server:', error);
+    console.error('💡 Possible solutions:');
+    console.error('1. Check if port 3000 is already in use');
+    console.error('2. Try running as administrator (if using port < 1024)');
+    console.error('3. Check firewall settings');
+    console.error('4. Verify WebSocketFactory implementation');
+    process.exit(1);
+  }
+}
+
+// Start the chat server
+main();

package/examples/client-test.js

@@ -0,0 +1,58 @@
+/**
+ * @file client-test.js - Native WebSocket Stress Test Client
+ * @description Uses Node.js built-in WebSocket (no 'ws' package required)
+ */
+
+// No import needed! Node.js 18+ has global WebSocket
+const URL = 'ws://localhost:8081';
+
+console.log('🚀 Starting stress test client using native WebSocket...');
+
+const ws = new WebSocket(URL);
+
+ws.onopen = () => {
+  console.log('✅ Connected to server!');
+  
+  // 1. Request initial stats
+  ws.send(JSON.stringify({ type: 'stats_request' }));
+  
+  // 2. Start stress test sequence
+  // Sending 1000 messages with 512 bytes payload, no delay
+  console.log('📤 Sending stress test command (1000 iterations)...');
+  ws.send(JSON.stringify({
+    type: 'stress_test',
+    iterations: 1000,
+    delay: 0,
+    payloadSize: 512
+  }));
+};
+
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  
+  if (data.type === 'stats_response') {
+    console.log('📊 Server Stats Received:', {
+      activeConnections: data.stats.connections.active,
+      totalMessages: data.stats.messages.received
+    });
+  } 
+  else if (data.type === 'stress_test_complete') {
+    console.log('\n🏁 ===== STRESS TEST COMPLETE =====');
+    console.log(`⚡ Speed: ${data.messagesPerSecond} msgs/sec`);
+    console.log(`⏱️ Duration: ${data.duration} ms`);
+    console.log(`📦 Total Iterations: ${data.iterations}`);
+    console.log('==================================\n');
+    
+    // Close connection after test
+    ws.close();
+  }
+};
+
+ws.onerror = (error) => {
+  console.error('❌ WebSocket Error:', error.message);
+};
+
+ws.onclose = () => {
+  console.log('🔌 Connection closed.');
+  process.exit(0);
+};

package/examples/realtime-api.js

@@ -0,0 +1,98 @@
+/**
+ * @file Realtime API Example with Auth and Rate Limiting
+ */
+
+import { WebSocketFactory } from '../index.js';
+import AuthMiddleware from '../src/middleware/auth-middleware.js';
+import RateLimiter from '../src/middleware/rate-limiter.js';
+
+async function main() {
+  // Create WebSocket factory instance with HTTP driver
+  const factory = new WebSocketFactory({
+    driver: 'http',
+    port: 4000
+  });
+
+  // Create authentication middleware instance
+  const auth = new AuthMiddleware({
+    verify: async (token) => {
+      // Mock token verification logic
+      // In production, replace with actual JWT or OAuth verification
+      return token === 'secret-token' ? { userId: 'user_123' } : null;
+    }
+  });
+
+  // Create rate limiter middleware instance
+  const limiter = new RateLimiter({
+    windowMs: 10000, // Time window in milliseconds (10 seconds)
+    max: 50 // Maximum requests per window
+  });
+
+  // Create WebSocket server
+  const server = await factory.createServer();
+
+  // Listen for connection events
+  factory.on('connection', (ws) => {
+    // Chain middlewares: auth -> rate limiter -> connection handler
+    auth.middleware()(ws, () => {
+      limiter.middleware()(ws, () => {
+        console.log(`Authenticated user connected: ${ws.user?.userId}`);
+        
+        // Listen for message events
+        ws.on('message', (data) => {
+          // Echo back with status confirmation
+          ws.send(JSON.stringify({ 
+            status: 'ok', 
+            received: data,
+            timestamp: Date.now()
+          }));
+        });
+
+        // Listen for close events
+        ws.on('close', (code, reason) => {
+          console.log(`User ${ws.user?.userId} disconnected: ${code} - ${reason}`);
+        });
+
+        // Listen for error events
+        ws.on('error', (error) => {
+          console.error(`Connection error for user ${ws.user?.userId}:`, error);
+        });
+      });
+    });
+  });
+
+  // Listen for server listening event
+  factory.on('server:listening', (address) => {
+    console.log(`Secure Realtime API listening on ws://${address.host}:${address.port}`);
+    console.log('🔒 Authentication required: Send token in connection header');
+    console.log('⏱️ Rate limiting: 50 requests per 10 seconds');
+    console.log('🛑 Press Ctrl+C to stop the server');
+  });
+
+  // Listen for server error events
+  factory.on('error', (error) => {
+    console.error('Server error:', error);
+  });
+
+  // Graceful shutdown handling
+  process.on('SIGINT', async () => {
+    console.log('\nShutting down Realtime API server...');
+    try {
+      await factory.close();
+      console.log('Server closed successfully');
+      process.exit(0);
+    } catch (error) {
+      console.error('Error closing server:', error);
+      process.exit(1);
+    }
+  });
+
+  process.on('SIGTERM', async () => {
+    console.log('\nReceived SIGTERM, shutting down...');
+    await factory.close();
+    process.exit(0);
+  });
+}
+
+// Start the server
+main().catch(console.error);

package/examples//342/200/214stress-test-server.js

@@ -0,0 +1,495 @@
+/**
+ * @file WebSocket Stress Test Server
+ * @description A WebSocket server designed for load testing and performance benchmarking
+ */
+
+import { WebSocketFactory } from '../index.js';
+import FrameEncoder from '../src/utils/frame-encoder.js'; // 添加这行导入
+
+// Configuration for stress testing
+const STRESS_TEST_CONFIG = {
+  driver: 'http',
+  port: process.env.STRESS_TEST_PORT || 8081,
+  host: process.env.STRESS_TEST_HOST || '0.0.0.0',
+  maxPayload: 10 * 1024 * 1024, // 10MB for large message testing
+  pingInterval: 60000, // 60 seconds (reduced for stress testing)
+  pingTimeout: 30000, // 30 seconds timeout
+  maxConnections: 100000, // High connection limit for stress testing
+  socketTimeout: 0 // No timeout for long-running connections
+};
+
+// Statistics tracking
+const stats = {
+  connections: {
+    total: 0,
+    active: 0,
+    peak: 0
+  },
+  messages: {
+    received: 0,
+    sent: 0,
+    bytesReceived: 0,
+    bytesSent: 0
+  },
+  errors: {
+    connection: 0,
+    message: 0,
+    other: 0
+  },
+  startTime: Date.now()
+};
+
+// Store active connections for message handling
+const activeConnections = new Map();
+
+async function main() {
+  try {
+    console.log('⚡ Starting WebSocket Stress Test Server...');
+    console.log(`📊 Port: ${STRESS_TEST_CONFIG.port}`);
+    console.log(`🏠 Host: ${STRESS_TEST_CONFIG.host}`);
+    console.log(`🔧 Max Connections: ${STRESS_TEST_CONFIG.maxConnections}`);
+    console.log(`📦 Max Payload: ${STRESS_TEST_CONFIG.maxPayload / 1024 / 1024}MB`);
+    
+    // Create WebSocket factory instance with stress test configuration
+    const factory = new WebSocketFactory(STRESS_TEST_CONFIG);
+
+    // Create server
+    const server = await factory.createServer();
+    
+    // Listen for server listening event
+    factory.on('server:listening', (address) => {
+      console.log(`\n🎯 ============================================`);
+      console.log(`⚡ Stress Test Server listening on ws://${address.host}:${address.port}`);
+      console.log(`📈 Ready for load testing and performance benchmarking`);
+      console.log(`🛑 Press Ctrl+C to stop the server`);
+      console.log(`============================================\n`);
+      
+      // Start statistics logging
+      startStatisticsLogging();
+    });
+    
+    // Listen for connection events
+    factory.on('connection', (connection) => {
+      // Update connection statistics
+      stats.connections.total++;
+      stats.connections.active++;
+      stats.connections.peak = Math.max(stats.connections.peak, stats.connections.active);
+      
+      const connectionId = connection.id || `conn_${stats.connections.total}`;
+      const remoteAddress = connection.remoteAddress || 'unknown';
+      
+      // Store connection for later use
+      activeConnections.set(connectionId, connection);
+      
+      console.log(`🔗 Client connected: ${connectionId} from ${remoteAddress}`);
+      console.log(`📊 Active connections: ${stats.connections.active}/${stats.connections.total}`);
+      
+      // Log connection object structure for debugging
+      console.log(`🔍 Connection object type: ${typeof connection}`);
+      console.log(`🔍 Connection object keys:`, Object.keys(connection));
+      
+      // Send connection acknowledgment with server info
+      const ackMessage = JSON.stringify({
+        type: 'connection_ack',
+        connectionId: connectionId,
+        serverTime: Date.now(),
+        stats: {
+          activeConnections: stats.connections.active,
+          uptime: Date.now() - stats.startTime
+        }
+      });
+      
+      // Send message through driver's socket
+      if (connection.socket && typeof connection.socket.write === 'function') {
+        try {
+          // Create WebSocket frame for the message
+          const frame = createWebSocketFrame(ackMessage);
+          connection.socket.write(frame);
+          stats.messages.sent++;
+          stats.messages.bytesSent += Buffer.byteLength(ackMessage);
+        } catch (error) {
+          console.error(`❌ Error sending acknowledgment to ${connectionId}:`, error.message);
+        }
+      } else {
+        console.error(`❌ No socket available for connection ${connectionId}`);
+      }
+    });
+    
+    // Listen for message events from factory (not from connection object)
+    factory.on('message', (connection, data, isBinary) => {
+      const connectionId = connection.id || 'unknown';
+      const messageSize = Buffer.byteLength(data);
+      stats.messages.received++;
+      stats.messages.bytesReceived += messageSize;
+      
+      // Log message statistics periodically
+      if (stats.messages.received % 1000 === 0) {
+        console.log(`📨 Received ${stats.messages.received} messages (${formatBytes(stats.messages.bytesReceived)})`);
+      }
+      
+      // Process different types of stress test messages
+      try {
+        if (isBinary) {
+          // Handle binary data (for binary stress testing)
+          handleBinaryMessage(connection, data, messageSize);
+        } else {
+          // Handle text data
+          const message = data.toString();
+          handleTextMessage(connection, message, messageSize);
+        }
+      } catch (error) {
+        stats.errors.message++;
+        console.error(`❌ Message processing error for ${connectionId}:`, error.message);
+      }
+    });
+    
+    // Listen for close events from factory
+    factory.on('close', (connection, code, reason) => {
+      const connectionId = connection.id || 'unknown';
+      stats.connections.active--;
+      console.log(`👋 Client disconnected: ${connectionId}, code: ${code}, reason: ${reason}`);
+      console.log(`📊 Active connections: ${stats.connections.active}/${stats.connections.total}`);
+      
+      // Remove from active connections
+      activeConnections.delete(connectionId);
+    });
+    
+    // Listen for error events from factory
+    factory.on('error', (error) => {
+      stats.errors.other++;
+      console.error('💥 Server error:', error);
+    });
+    
+    // Handle different types of stress test messages
+    function handleTextMessage(connection, message, messageSize) {
+      const connectionId = connection.id || 'unknown';
+      
+      try {
+        const parsed = JSON.parse(message);
+        
+        switch (parsed.type) {
+          case 'echo':
+            // Echo back the message (basic echo test)
+            const echoResponse = {
+              type: 'echo_response',
+              original: parsed.data,
+              timestamp: Date.now(),
+              messageSize: messageSize
+            };
+            sendToConnection(connection, JSON.stringify(echoResponse));
+            stats.messages.sent++;
+            stats.messages.bytesSent += Buffer.byteLength(JSON.stringify(echoResponse));
+            break;
+            
+          case 'broadcast':
+            // Broadcast message to all connections (broadcast stress test)
+            const broadcastMessage = JSON.stringify({
+              type: 'broadcast',
+              from: connectionId,
+              data: parsed.data,
+              timestamp: Date.now()
+            });
+            
+            // Broadcast to all active connections
+            broadcastToAll(broadcastMessage, connectionId);
+            break;
+            
+          case 'stats_request':
+            // Return server statistics
+            const statsResponse = {
+              type: 'stats_response',
+              stats: getCurrentStats(),
+              timestamp: Date.now()
+            };
+            sendToConnection(connection, JSON.stringify(statsResponse));
+            stats.messages.sent++;
+            break;
+            
+          case 'large_payload':
+            // Test large payload handling
+            const largeResponse = {
+              type: 'large_payload_response',
+              size: parsed.size || 1024,
+              data: 'x'.repeat(parsed.size || 1024),
+              timestamp: Date.now()
+            };
+            sendToConnection(connection, JSON.stringify(largeResponse));
+            stats.messages.sent++;
+            stats.messages.bytesSent += Buffer.byteLength(JSON.stringify(largeResponse));
+            break;
+            
+          case 'stress_test':
+            // Run a stress test sequence
+            runStressTestSequence(connection, parsed);
+            break;
+            
+          default:
+            // Default echo response
+            const defaultResponse = {
+              type: 'default_response',
+              received: parsed,
+              timestamp: Date.now()
+            };
+            sendToConnection(connection, JSON.stringify(defaultResponse));
+            stats.messages.sent++;
+        }
+      } catch (error) {
+        // If JSON parsing fails, echo back as text
+        const echoText = `Echo: ${message}`;
+        sendToConnection(connection, echoText);
+        stats.messages.sent++;
+        stats.messages.bytesSent += Buffer.byteLength(echoText);
+      }
+    }
+    
+    function handleBinaryMessage(connection, data, messageSize) {
+      // For binary stress testing, echo back the binary data
+      sendToConnection(connection, data, true);
+      stats.messages.sent++;
+      stats.messages.bytesSent += messageSize;
+      
+      // Log binary message statistics
+      if (stats.messages.received % 100 === 0) {
+        console.log(`🔢 Binary message: ${formatBytes(messageSize)} from ${connection.id || 'unknown'}`);
+      }
+    }
+    
+    function sendToConnection(connection, data, isBinary = false) {
+      try {
+        if (connection.socket && typeof connection.socket.write === 'function') {
+          // Create WebSocket frame
+          const frame = createWebSocketFrame(data, isBinary);
+          return connection.socket.write(frame);
+        } else {
+          console.error(`❌ No socket available for connection ${connection.id || 'unknown'}`);
+          return false;
+        }
+      } catch (error) {
+        console.error(`❌ Error sending to connection ${connection.id || 'unknown'}:`, error.message);
+        return false;
+      }
+    }
+    
+  function createWebSocketFrame(data, isBinary = false) {
+  try {
+    // 使用 FrameEncoder 创建正确的 WebSocket 帧
+    const opcode = isBinary ? 0x2 : 0x1; // 0x1 = TEXT, 0x2 = BINARY
+    return FrameEncoder.encode(opcode, data, true, false); // fin=true, mask=false (服务器到客户端不需要掩码)
+  } catch (error) {
+    console.error('❌ Error creating WebSocket frame:', error.message);
+    
+    // 回退到简单实现
+    const payload = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
+    const payloadLength = payload.length;
+    
+    let frame;
+    if (payloadLength <= 125) {
+      frame = Buffer.alloc(2 + payloadLength);
+      frame = isBinary ? 0x82 : 0x81; // FIN + opcode
+      frame = payloadLength; // No mask
+      payload.copy(frame, 2);
+    } else if (payloadLength <= 65535) {
+      frame = Buffer.alloc(4 + payloadLength);
+      frame = isBinary ? 0x82 : 0x81;
+      frame = 126; // Extended payload length
+      frame.writeUInt16BE(payloadLength, 2);
+      payload.copy(frame, 4);
+    } else {
+      frame = Buffer.alloc(10 + payloadLength);
+      frame = isBinary ? 0x82 : 0x81;
+      frame = 127; // 64-bit payload length
+      frame.writeBigUInt64BE(BigInt(payloadLength), 2);
+      payload.copy(frame, 10);
+    }
+    
+    return frame;
+  }
+}
+    
+    function broadcastToAll(message, excludeConnectionId = null) {
+      let sentCount = 0;
+      
+      activeConnections.forEach((connection, id) => {
+        if (excludeConnectionId && id === excludeConnectionId) {
+          return; // Skip excluded connection
+        }
+        
+        if (sendToConnection(connection, message)) {
+          sentCount++;
+        }
+      });
+      
+      stats.messages.sent += sentCount;
+      return sentCount;
+    }
+    
+    function runStressTestSequence(connection, testConfig) {
+      const { iterations = 100, delay = 10, payloadSize = 1024 } = testConfig;
+      const connectionId = connection.id || 'unknown';
+      
+      console.log(`🧪 Starting stress test for ${connectionId}: ${iterations} iterations`);
+      
+      let completed = 0;
+      const testStartTime = Date.now();
+      
+      function sendTestMessage(index) {
+        if (index >= iterations) {
+          // Test complete
+          const testDuration = Date.now() - testStartTime;
+          const messagesPerSecond = iterations / (testDuration / 1000);
+          
+          const completionMessage = JSON.stringify({
+            type: 'stress_test_complete',
+            iterations: iterations,
+            duration: testDuration,
+            messagesPerSecond: messagesPerSecond.toFixed(2),
+            timestamp: Date.now()
+          });
+          
+          sendToConnection(connection, completionMessage);
+          
+          console.log(`✅ Stress test completed for ${connectionId}: ${messagesPerSecond.toFixed(2)} msg/sec`);
+          return;
+        }
+        
+        const testMessage = {
+          type: 'stress_test_message',
+          index: index,
+          payload: 'x'.repeat(payloadSize),
+          timestamp: Date.now()
+        };
+        
+        if (sendToConnection(connection, JSON.stringify(testMessage))) {
+          stats.messages.sent++;
+          stats.messages.bytesSent += Buffer.byteLength(JSON.stringify(testMessage));
+        }
+        
+        setTimeout(() => sendTestMessage(index + 1), delay);
+      }
+      
+      sendTestMessage(0);
+    }
+    
+    function getCurrentStats() {
+      const uptime = Date.now() - stats.startTime;
+      const hours = Math.floor(uptime / 3600000);
+      const minutes = Math.floor((uptime % 3600000) / 60000);
+      const seconds = Math.floor((uptime % 60000) / 1000);
+      
+      return {
+        connections: {
+          total: stats.connections.total,
+          active: stats.connections.active,
+          peak: stats.connections.peak
+        },
+        messages: {
+          received: stats.messages.received,
+          sent: stats.messages.sent,
+          bytesReceived: formatBytes(stats.messages.bytesReceived),
+          bytesSent: formatBytes(stats.messages.bytesSent),
+          receiveRate: (stats.messages.received / (uptime / 1000)).toFixed(2),
+          sendRate: (stats.messages.sent / (uptime / 1000)).toFixed(2)
+        },
+        errors: stats.errors,
+        uptime: `${hours}h ${minutes}m ${seconds}s`,
+        memory: process.memoryUsage()
+      };
+    }
+    
+    function formatBytes(bytes) {
+      if (bytes === 0) return '0 Bytes';
+      const k = 1024;
+      const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+      const i = Math.floor(Math.log(bytes) / Math.log(k));
+      return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+    }
+    
+    function startStatisticsLogging() {
+      // Log statistics every 30 seconds
+      setInterval(() => {
+        const currentStats = getCurrentStats();
+        console.log('\n📈 ========== SERVER STATISTICS ==========');
+        console.log(`⏱️  Uptime: ${currentStats.uptime}`);
+        console.log(`👥 Connections: ${currentStats.connections.active} active / ${currentStats.connections.total} total (Peak: ${currentStats.connections.peak})`);
+        console.log(`📨 Messages: ${currentStats.messages.received} received, ${currentStats.messages.sent} sent`);
+        console.log(`📊 Data: ${currentStats.messages.bytesReceived} received, ${currentStats.messages.bytesSent} sent`);
+        console.log(`⚡ Rates: ${currentStats.messages.receiveRate} msg/sec received, ${currentStats.messages.sendRate} msg/sec sent`);
+        console.log(`❌ Errors: ${currentStats.errors.connection} connection, ${currentStats.errors.message} message, ${currentStats.errors.other} other`);
+        console.log(`💾 Memory: ${formatBytes(currentStats.memory.rss)} RSS, ${formatBytes(currentStats.memory.heapUsed)} heap used`);
+        console.log(`========================================\n`);
+      }, 30000);
+    }
+    
+    // Graceful shutdown handling
+    process.on('SIGINT', async () => {
+      console.log('\n🔄 Shutting down stress test server...');
+      console.log('📊 Final statistics:');
+      console.log(JSON.stringify(getCurrentStats(), null, 2));
+      
+      try {
+        await factory.close();
+        console.log('✅ Stress test server closed successfully');
+        process.exit(0);
+      } catch (error) {
+        console.error('❌ Error closing server:', error);
+        process.exit(1);
+      }
+    });
+    
+    process.on('SIGTERM', async () => {
+      console.log('\n🔄 Received SIGTERM, shutting down...');
+      await factory.close();
+      process.exit(0);
+    });
+    
+    // Display test client instructions
+    console.log('\n🧪 ========== STRESS TEST CLIENT EXAMPLES ==========');
+    console.log('1. Basic Echo Test:');
+    console.log(`
+const ws = new WebSocket('ws://localhost:${STRESS_TEST_CONFIG.port}');
+ws.onopen = () => {
+  for(let i = 0; i < 1000; i++) {
+    ws.send(JSON.stringify({type: 'echo', data: 'Test message ' + i}));
+  }
+};
+    `);
+    
+    console.log('\n2. Large Payload Test:');
+    console.log(`
+const ws = new WebSocket('ws://localhost:${STRESS_TEST_CONFIG.port}');
+ws.onopen = () => {
+  ws.send(JSON.stringify({type: 'large_payload', size: 1000000}));
+};
+    `);
+    
+    console.log('\n3. Stress Test Sequence:');
+    console.log(`
+const ws = new WebSocket('ws://localhost:${STRESS_TEST_CONFIG.port}');
+ws.onopen = () => {
+  ws.send(JSON.stringify({
+    type: 'stress_test',
+    iterations: 1000,
+    delay: 0,
+    payloadSize: 1024
+  }));
+};
+    `);
+    
+    console.log('\n4. Request Statistics:');
+    console.log(`
+const ws = new WebSocket('ws://localhost:${STRESS_TEST_CONFIG.port}');
+ws.onopen = () => {
+  ws.send(JSON.stringify({type: 'stats_request'}));
+  ws.onmessage = (e) => console.log('Stats:', JSON.parse(e.data));
+};
+    `);
+    console.log('==================================================\n');
+    
+  } catch (error) {
+    console.error('❌ Failed to start stress test server:', error);
+    process.exit(1);
+  }
+}
+
+// Start the stress test server
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aetherframework/websocket",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "Zero-dependency WebSocket server implementation for AetherJS",
   "main": "index.js",
   "types": "index.d.ts",
@@ -43,7 +43,8 @@
   "files": [
     "index.js",
     "server.js",
-    "src/", 
+    "src",
+    "examples",
     "connection.js",
     "README.md",
     "LICENSE"