@devo-bmad-custom/agent-orchestration 1.0.0

package/src/.agents/skills/websocket-engineer/references/alternatives.md

@@ -0,0 +1,391 @@
+# Real-Time Communication Alternatives
+
+## Technology Comparison
+
+| Feature | WebSocket | SSE | Long Polling | HTTP/2 Push | WebRTC |
+|---------|-----------|-----|--------------|-------------|--------|
+| Bidirectional | Yes | No | Yes | No | Yes |
+| Real-time | Yes | Yes | Near | Yes | Yes |
+| Browser Support | Excellent | Good | Universal | Good | Good |
+| Proxy Issues | Some | Rare | Rare | Some | Some |
+| Overhead | Low | Low | High | Medium | Medium |
+| Use Case | Chat, games | Feeds, updates | Legacy | Assets | Audio/video |
+
+## Server-Sent Events (SSE)
+
+### When to Use SSE
+
+- One-way server-to-client communication
+- Live feeds, notifications, stock tickers
+- Automatic reconnection needed
+- Simpler than WebSockets
+- Better firewall/proxy compatibility
+
+### SSE Server (Node.js)
+
+```javascript
+const express = require('express');
+const app = express();
+
+app.get('/events', (req, res) => {
+  // Set SSE headers
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+  res.setHeader('Access-Control-Allow-Origin', '*');
+
+  // Send initial connection message
+  res.write('data: {"message": "Connected"}\n\n');
+
+  // Send updates every 5 seconds
+  const intervalId = setInterval(() => {
+    const data = {
+      timestamp: Date.now(),
+      value: Math.random()
+    };
+
+    res.write(`data: ${JSON.stringify(data)}\n\n`);
+  }, 5000);
+
+  // Cleanup on client disconnect
+  req.on('close', () => {
+    clearInterval(intervalId);
+    res.end();
+  });
+});
+
+app.listen(3000);
+```
+
+### SSE Client
+
+```javascript
+const eventSource = new EventSource('http://localhost:3000/events');
+
+eventSource.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  console.log('Received:', data);
+};
+
+eventSource.onerror = (error) => {
+  console.error('SSE error:', error);
+  // Automatically reconnects
+};
+
+// Named events
+eventSource.addEventListener('update', (event) => {
+  console.log('Update:', event.data);
+});
+
+// Close connection
+eventSource.close();
+```
+
+### SSE with Express
+
+```javascript
+const express = require('express');
+const app = express();
+
+class SSEManager {
+  constructor() {
+    this.clients = new Set();
+  }
+
+  addClient(res) {
+    this.clients.add(res);
+  }
+
+  removeClient(res) {
+    this.clients.delete(res);
+  }
+
+  broadcast(event, data) {
+    const message = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+
+    this.clients.forEach(client => {
+      client.write(message);
+    });
+  }
+}
+
+const sseManager = new SSEManager();
+
+app.get('/events', (req, res) => {
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+
+  sseManager.addClient(res);
+
+  req.on('close', () => {
+    sseManager.removeClient(res);
+  });
+});
+
+// Broadcast to all clients
+setInterval(() => {
+  sseManager.broadcast('update', {
+    timestamp: Date.now(),
+    activeClients: sseManager.clients.size
+  });
+}, 10000);
+
+app.listen(3000);
+```
+
+## Long Polling
+
+### When to Use Long Polling
+
+- Legacy browser support needed
+- Firewall/proxy blocks WebSockets
+- Very infrequent updates
+- Fallback mechanism
+
+### Long Polling Server
+
+```javascript
+const express = require('express');
+const app = express();
+
+const pendingRequests = new Map();
+const messages = [];
+
+app.get('/poll', (req, res) => {
+  const clientId = req.query.clientId;
+
+  // If messages available, send immediately
+  if (messages.length > 0) {
+    res.json({ messages });
+    messages.length = 0; // Clear messages
+    return;
+  }
+
+  // Hold request until timeout or new message
+  const timeout = setTimeout(() => {
+    pendingRequests.delete(clientId);
+    res.json({ messages: [] });
+  }, 30000); // 30 second timeout
+
+  pendingRequests.set(clientId, { res, timeout });
+
+  req.on('close', () => {
+    clearTimeout(timeout);
+    pendingRequests.delete(clientId);
+  });
+});
+
+app.post('/send', express.json(), (req, res) => {
+  messages.push(req.body.message);
+
+  // Respond to all pending requests
+  pendingRequests.forEach(({ res, timeout }, clientId) => {
+    clearTimeout(timeout);
+    res.json({ messages });
+    pendingRequests.delete(clientId);
+  });
+
+  messages.length = 0; // Clear messages
+  res.json({ success: true });
+});
+
+app.listen(3000);
+```
+
+### Long Polling Client
+
+```javascript
+const clientId = Math.random().toString(36);
+
+async function poll() {
+  try {
+    const response = await fetch(
+      `http://localhost:3000/poll?clientId=${clientId}`,
+      { signal: AbortSignal.timeout(35000) }
+    );
+
+    const data = await response.json();
+
+    if (data.messages.length > 0) {
+      console.log('Received messages:', data.messages);
+    }
+
+    // Immediately poll again
+    poll();
+  } catch (error) {
+    console.error('Polling error:', error);
+    // Retry after delay
+    setTimeout(poll, 5000);
+  }
+}
+
+poll();
+```
+
+## HTTP/2 Server Push (Deprecated)
+
+Note: HTTP/2 Server Push is deprecated and removed from Chrome. Use 103 Early Hints instead.
+
+```javascript
+// Example for historical context only
+const http2 = require('http2');
+const fs = require('fs');
+
+const server = http2.createSecureServer({
+  key: fs.readFileSync('server.key'),
+  cert: fs.readFileSync('server.crt')
+});
+
+server.on('stream', (stream, headers) => {
+  if (headers[':path'] === '/') {
+    // Push assets before HTML response
+    stream.pushStream({ ':path': '/style.css' }, (err, pushStream) => {
+      if (!err) {
+        pushStream.respondWithFile('style.css');
+      }
+    });
+
+    stream.respondWithFile('index.html');
+  }
+});
+
+server.listen(3000);
+```
+
+## Decision Matrix
+
+### Choose WebSocket When:
+
+- Bidirectional communication needed
+- Low latency critical (< 50ms)
+- High message frequency (> 1 msg/sec)
+- Gaming, chat, collaborative editing
+- Binary data transfer
+- Custom protocol needed
+
+### Choose SSE When:
+
+- One-way server-to-client only
+- Stock tickers, live feeds
+- News/notifications
+- Simpler implementation preferred
+- Better proxy compatibility needed
+- Automatic reconnection important
+
+### Choose Long Polling When:
+
+- Legacy browser support required (IE8/9)
+- WebSocket blocked by firewall
+- Very infrequent updates
+- Fallback mechanism only
+
+### Choose HTTP Streaming When:
+
+- Large data transfers
+- File uploads with progress
+- Video/audio streaming
+- One-way data flow
+
+### Choose WebRTC When:
+
+- Peer-to-peer communication
+- Audio/video calls
+- Screen sharing
+- File transfer between peers
+- Low latency P2P needed
+
+## Hybrid Approach
+
+```javascript
+// Socket.IO with automatic fallback
+const io = require('socket.io')(3000, {
+  transports: ['websocket', 'polling'], // Try WebSocket first
+  upgrade: true,
+  allowUpgrades: true
+});
+
+io.on('connection', (socket) => {
+  console.log('Connected via:', socket.conn.transport.name);
+
+  socket.conn.on('upgrade', () => {
+    console.log('Upgraded to:', socket.conn.transport.name);
+  });
+});
+```
+
+## Performance Characteristics
+
+### Latency (p99)
+
+- WebSocket: 5-20ms
+- SSE: 10-50ms
+- Long Polling: 100-500ms
+- HTTP/2: 20-100ms
+
+### Throughput (messages/sec)
+
+- WebSocket: 10,000+ per connection
+- SSE: 1,000+ per connection
+- Long Polling: 1-10 per connection
+
+### Connection Limits (per server)
+
+- WebSocket: 50,000-100,000
+- SSE: 50,000-100,000
+- Long Polling: 10,000-20,000
+
+### Overhead (per message)
+
+- WebSocket: 2-6 bytes
+- SSE: ~20 bytes
+- Long Polling: 500-2000 bytes (HTTP headers)
+
+## Migration Path
+
+### From Polling to WebSocket
+
+```javascript
+// Step 1: Support both
+app.get('/api/messages', (req, res) => {
+  // Legacy polling endpoint
+  res.json({ messages: getRecentMessages() });
+});
+
+io.on('connection', (socket) => {
+  // New WebSocket endpoint
+  socket.on('subscribe', (channel) => {
+    socket.join(channel);
+  });
+});
+
+// Step 2: Gradually migrate clients
+// Step 3: Deprecate polling endpoint
+```
+
+### From SSE to WebSocket
+
+```javascript
+// SSE provides read-only, add WebSocket for writes
+app.get('/events', sseHandler);  // Keep for reads
+
+io.on('connection', (socket) => {
+  socket.on('action', (data) => {
+    // Handle writes via WebSocket
+    processAction(data);
+  });
+});
+
+// Eventually migrate reads to WebSocket too
+```
+
+## Best Practices
+
+1. Start with simplest solution (SSE for one-way)
+2. Use Socket.IO for automatic fallbacks
+3. Monitor actual requirements before over-engineering
+4. Consider mobile/network constraints
+5. Implement graceful degradation
+6. Load test before production
+7. Have fallback strategy
+8. Monitor connection success rates