# Feature Specification: WebSocket Chat with Redis Pub/Sub

## Overview

Implement a WebSocket endpoint at `GET /ws` that upgrades HTTP connections to WebSocket for real-time chat functionality. Messages received from clients are published to Redis channels, and a Redis subscriber broadcasts incoming messages to all connected clients.

## Requirements

### Functional Requirements

1. **WebSocket Upgrade Endpoint**
   - `GET /api/chat-api/ws` upgrades HTTP to WebSocket
   - `GET /api/chat-api/ws/{room}` joins a specific room on connect
   - Support optional `?room=` query parameter for room selection

2. **Message Publishing**
   - Incoming WebSocket messages are published to Redis pub/sub channels
   - Room-specific messages go to `realtime:room:{room}` channel
   - Global messages (no room) go to `realtime:global` channel

3. **Message Broadcasting**
   - Redis subscriber receives messages from all channels
   - Messages are broadcast to all connected WebSocket clients
   - Room-targeted messages only go to clients in that room
   - Cross-pod broadcasting ensures messages reach all service instances

4. **Message Format**
   ```json
   {
     "id": "uuid",
     "type": "chat|presence|notification|system",
     "room": "room-name",
     "from": "client-id",
     "data": {},
     "timestamp": "2026-02-05T00:00:00Z"
   }
   ```

### Non-Functional Requirements

1. **Connection Management**
   - Automatic ping/pong heartbeat (60s timeout)
   - Graceful connection cleanup on disconnect
   - Maximum message size: 64KB
   - Send buffer size: 256 messages

2. **Scalability**
   - Multi-pod deployment via Redis pub/sub
   - Pod ID tracking to prevent message echo

3. **Configuration**
   - Redis URL via `REDIS_URL` environment variable
   - Auth optional via existing `AUTH_ENABLED` flag

## Acceptance Criteria

- [ ] WebSocket endpoint accessible at `/api/chat-api/ws`
- [ ] Room-based WebSocket endpoint at `/api/chat-api/ws/{room}`
- [ ] Messages published to Redis channels
- [ ] Redis subscriber broadcasts to connected clients
- [ ] Room-targeted messages only reach room members
- [ ] Global messages reach all connected clients
- [ ] Connection stats endpoint at `/api/chat-api/ws/stats`
- [ ] Graceful shutdown of WebSocket connections
- [ ] Tests cover WebSocket handler and Redis integration

## Out of Scope

- Message persistence (database storage)
- Message history retrieval
- User authentication enforcement (auth remains optional)
- Rate limiting
- Message encryption