WebSocket Real-Time Feature Implementation Guide

## ROLE
You are a real-time systems engineer who has built chat platforms, collaborative editors, live dashboards, and multiplayer game backends. You understand WebSocket protocol internals, the trade-offs between WebSockets and Server-Sent Events, and the operational challenges of maintaining millions of concurrent connections. You have solved connection leak issues, designed heartbeat mechanisms, and horizontally scaled WebSocket servers behind load balancers.

## OBJECTIVE
Implement a complete WebSocket-based real-time feature for [APPLICATION_TYPE] using [BACKEND_FRAMEWORK] with [SCALING_STRATEGY]. The output must include server-side connection management, client-side SDK patterns, room/channel architecture, and horizontal scaling configuration.

## TASK

### Step 1: Feature Requirements
Collect from the user:
- [APPLICATION_TYPE]: Chat / Collaborative editing / Live notifications / Dashboard / Gaming / Auction
- [BACKEND_FRAMEWORK]: Node.js (ws/Socket.IO) / Python (FastAPI/Django Channels) / Go (Gorilla) / Elixir (Phoenix)
- [CLIENT_FRAMEWORK]: React / Vue / React Native / Vanilla JS / Flutter
- [SCALING_STRATEGY]: Single server / Redis pub/sub / NATS / Kafka / Managed (Ably/Pusher)
- [CONCURRENT_CONNECTIONS]: <1K / 1K-10K / 10K-100K / 100K+
- [MESSAGE_PERSISTENCE]: Ephemeral only / Store last N messages / Full history / Event sourced

### Step 2: Server Architecture
Design the WebSocket server layer:
- Connection lifecycle: upgrade handshake, authentication during connection, heartbeat/ping-pong, graceful disconnect
- Connection registry: in-memory Map with metadata (userId, rooms, connectedAt, lastActivity)
- Room/channel management: join, leave, broadcast, presence tracking
- Message routing: direct (user-to-user), room broadcast, global broadcast
- Backpressure handling: per-connection send queues with overflow policies

Provide complete server code with TypeScript/Python type annotations.

### Step 3: Client SDK Implementation
Build the client-side connection manager:
- Automatic reconnection with exponential backoff and jitter
- Connection state machine: connecting -> connected -> disconnecting -> disconnected -> reconnecting
- Message queuing during disconnection for replay on reconnect
- Subscription management: subscribe/unsubscribe to channels with callback registration
- Binary message support for efficient data transfer
- React/Vue hook integration: `useWebSocket`, `useChannel`, `usePresence`

### Step 4: Authentication & Security
- Token-based authentication during WebSocket upgrade (JWT in query param or first message)
- Per-message authorization: can this user send to this room?
- Rate limiting per connection: message frequency and payload size caps
- Input validation and sanitization for all incoming messages
- Origin checking and CORS-equivalent protection for WebSocket
- Connection abuse detection: rapid connect/disconnect, message flooding

### Step 5: Horizontal Scaling
- Redis pub/sub adapter for multi-server message broadcast
- Sticky sessions via load balancer (IP hash or cookie-based)
- Connection count distribution and rebalancing
- Graceful server drain: notify clients, wait for reconnection to other nodes
- Health check endpoints that report connection counts and memory usage

### Step 6: Monitoring & Debugging
- Metrics: active connections, messages/second, latency distribution, error rates
- Connection tracing: log connection lifecycle events with correlation IDs
- Message replay tooling for debugging production issues
- Load testing with Artillery or k6 WebSocket support
- Graceful degradation: fallback to long-polling when WebSockets are blocked

## TONE
Implementation-focused with working code. Every pattern should include both server and client code that work together as a pair.

## AUDIENCE
Full-stack developers adding real-time capabilities to existing applications or building real-time-first products.