@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/websocket-patterns.md

@@ -0,0 +1,306 @@
+---
+name: websocket-patterns
+description: WebSocket patterns for connection management, heartbeat, reconnection, rooms, binary data, and scaling.
+---
+
+# WebSocket Patterns
+
+## When to Use
+
+Apply these patterns when building real-time features: chat, live dashboards,
+collaborative editing, notifications, or streaming data. Use this skill for
+managing connections reliably, implementing heartbeat/ping-pong, handling
+reconnection on the client, organizing connections into rooms, and scaling
+across multiple server instances.
+
+## How It Works
+
+### Connection Manager
+
+Track active connections in a Map keyed by user/session ID. Handle connect,
+disconnect, and broadcast operations. Clean up stale connections.
+
+```typescript
+interface Connection {
+  ws: WebSocket
+  userId: string
+  connectedAt: number
+  lastPing: number
+}
+
+class ConnectionManager {
+  private connections = new Map<string, Connection>()
+
+  add(userId: string, ws: WebSocket): void {
+    // Close existing connection for same user (prevent duplicates)
+    const existing = this.connections.get(userId)
+    if (existing) {
+      existing.ws.close(4000, 'Replaced by new connection')
+    }
+    this.connections.set(userId, {
+      ws, userId, connectedAt: Date.now(), lastPing: Date.now(),
+    })
+  }
+
+  remove(userId: string): void {
+    this.connections.delete(userId)
+  }
+
+  send(userId: string, data: unknown): boolean {
+    const conn = this.connections.get(userId)
+    if (conn && conn.ws.readyState === WebSocket.OPEN) {
+      conn.ws.send(JSON.stringify(data))
+      return true
+    }
+    return false
+  }
+
+  broadcast(data: unknown, exclude?: string): void {
+    const payload = JSON.stringify(data)
+    for (const [userId, conn] of this.connections) {
+      if (userId !== exclude && conn.ws.readyState === WebSocket.OPEN) {
+        conn.ws.send(payload)
+      }
+    }
+  }
+
+  get size(): number {
+    return this.connections.size
+  }
+}
+```
+
+### Heartbeat (Server-Side Ping/Pong)
+
+Send periodic pings to detect dead connections. Close connections that miss
+two consecutive pongs. Run the heartbeat on a fixed interval.
+
+```typescript
+class HeartbeatMonitor {
+  private interval: NodeJS.Timeout | null = null
+
+  start(manager: ConnectionManager, intervalMs = 30_000): void {
+    this.interval = setInterval(() => {
+      const now = Date.now()
+      const staleThreshold = now - intervalMs * 2
+
+      for (const [userId, conn] of manager.allConnections()) {
+        if (conn.lastPing < staleThreshold) {
+          console.log(`Closing stale connection: ${userId}`)
+          conn.ws.terminate()
+          manager.remove(userId)
+          continue
+        }
+        if (conn.ws.readyState === WebSocket.OPEN) {
+          conn.ws.ping()
+        }
+      }
+    }, intervalMs)
+  }
+
+  stop(): void {
+    if (this.interval) clearInterval(this.interval)
+  }
+}
+
+// On the WebSocket server:
+wss.on('connection', (ws, req) => {
+  const userId = authenticate(req)
+  manager.add(userId, ws)
+
+  ws.on('pong', () => {
+    manager.updatePing(userId)
+  })
+
+  ws.on('close', () => {
+    manager.remove(userId)
+  })
+})
+```
+
+### Client-Side Reconnection
+
+Implement exponential backoff with jitter. Track connection state for UI feedback.
+Re-authenticate after reconnecting.
+
+```typescript
+class ReconnectingWebSocket {
+  private ws: WebSocket | null = null
+  private attempt = 0
+  private maxAttempts = 10
+  private baseDelay = 1000
+  private maxDelay = 30_000
+
+  constructor(
+    private url: string,
+    private onMessage: (data: unknown) => void,
+    private onStateChange: (state: 'connecting' | 'open' | 'closed') => void,
+  ) {}
+
+  connect(): void {
+    this.onStateChange('connecting')
+    this.ws = new WebSocket(this.url)
+
+    this.ws.onopen = () => {
+      this.attempt = 0
+      this.onStateChange('open')
+    }
+
+    this.ws.onmessage = (event) => {
+      this.onMessage(JSON.parse(event.data))
+    }
+
+    this.ws.onclose = (event) => {
+      this.onStateChange('closed')
+      if (event.code !== 4000 && this.attempt < this.maxAttempts) {
+        this.scheduleReconnect()
+      }
+    }
+  }
+
+  private scheduleReconnect(): void {
+    const delay = Math.min(
+      this.baseDelay * Math.pow(2, this.attempt) + Math.random() * 1000,
+      this.maxDelay,
+    )
+    this.attempt++
+    setTimeout(() => this.connect(), delay)
+  }
+
+  send(data: unknown): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(data))
+    }
+  }
+
+  close(): void {
+    this.ws?.close(4000, 'Client closed')
+  }
+}
+```
+
+### Room-Based Broadcasting
+
+Group connections by topic/channel. Users can join/leave rooms. Broadcast to
+all members of a room.
+
+```typescript
+class RoomManager {
+  private rooms = new Map<string, Set<string>>() // roomId -> Set<userId>
+
+  join(roomId: string, userId: string): void {
+    if (!this.rooms.has(roomId)) {
+      this.rooms.set(roomId, new Set())
+    }
+    this.rooms.get(roomId)!.add(userId)
+  }
+
+  leave(roomId: string, userId: string): void {
+    this.rooms.get(roomId)?.delete(userId)
+    if (this.rooms.get(roomId)?.size === 0) {
+      this.rooms.delete(roomId)
+    }
+  }
+
+  leaveAll(userId: string): void {
+    for (const [roomId, members] of this.rooms) {
+      members.delete(userId)
+      if (members.size === 0) this.rooms.delete(roomId)
+    }
+  }
+
+  broadcast(roomId: string, data: unknown, connManager: ConnectionManager, exclude?: string): void {
+    const members = this.rooms.get(roomId)
+    if (!members) return
+    for (const userId of members) {
+      if (userId !== exclude) {
+        connManager.send(userId, data)
+      }
+    }
+  }
+
+  members(roomId: string): string[] {
+    return [...(this.rooms.get(roomId) ?? [])]
+  }
+}
+```
+
+### Message Protocol
+
+Define a typed message protocol. Use a `type` field for routing. Include a
+message ID for acknowledgment.
+
+```typescript
+type ClientMessage =
+  | { type: 'join'; roomId: string }
+  | { type: 'leave'; roomId: string }
+  | { type: 'chat'; roomId: string; text: string; msgId: string }
+  | { type: 'ping' }
+
+type ServerMessage =
+  | { type: 'chat'; roomId: string; text: string; userId: string; timestamp: number }
+  | { type: 'ack'; msgId: string }
+  | { type: 'error'; code: string; message: string }
+  | { type: 'members'; roomId: string; users: string[] }
+  | { type: 'pong' }
+
+function handleMessage(userId: string, raw: string): void {
+  const msg: ClientMessage = JSON.parse(raw)
+  switch (msg.type) {
+    case 'join': rooms.join(msg.roomId, userId); break
+    case 'leave': rooms.leave(msg.roomId, userId); break
+    case 'chat': handleChat(userId, msg); break
+    case 'ping': connManager.send(userId, { type: 'pong' }); break
+  }
+}
+```
+
+### Scaling with Redis Pub/Sub
+
+When running multiple server instances, use Redis pub/sub to fan out messages
+across all instances. Each instance subscribes to relevant channels.
+
+```typescript
+import Redis from 'ioredis'
+
+const pub = new Redis(REDIS_URL)
+const sub = new Redis(REDIS_URL)
+
+// Subscribe to room channels
+sub.on('message', (channel, message) => {
+  const roomId = channel.replace('room:', '')
+  const data = JSON.parse(message)
+  rooms.broadcast(roomId, data, connManager)
+})
+
+function publishToRoom(roomId: string, data: unknown): void {
+  pub.publish(`room:${roomId}`, JSON.stringify(data))
+}
+```
+
+## Examples
+
+**Pattern: Binary data with ArrayBuffer**
+```typescript
+ws.binaryType = 'arraybuffer'
+ws.onmessage = (event) => {
+  if (event.data instanceof ArrayBuffer) {
+    const view = new DataView(event.data)
+    const messageType = view.getUint8(0)
+    // handle binary protocol
+  }
+}
+```
+
+## Checklist
+
+- [ ] Connection manager tracks all active connections with metadata
+- [ ] Server-side ping/pong heartbeat detects and cleans up dead connections
+- [ ] Client reconnects with exponential backoff + jitter
+- [ ] Connections closed with meaningful close codes (4000+ for application codes)
+- [ ] Room manager for topic-based broadcasting with join/leave/leaveAll
+- [ ] Typed message protocol with `type` field for routing
+- [ ] Message acknowledgments (`ack`) for delivery confirmation
+- [ ] Redis pub/sub for multi-instance broadcasting
+- [ ] Authentication on initial connection (token in query string or first message)
+- [ ] Connection state exposed to UI (`connecting`, `open`, `closed`)