@aetherframework/websocket 1.0.1 → 1.0.3

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);