# Feature Specification: WebSocket Chat

## Overview

Add real-time WebSocket chat capability to the chat-api service. This feature enables bidirectional communication between clients and the server, with message distribution via Redis pub/sub for horizontal scaling across multiple pods.

## Requirements

### Core Requirements

1. **WebSocket Endpoint**: `GET /ws` upgrades HTTP connections to WebSocket
2. **Message Publication**: Incoming messages from clients are published to a Redis channel
3. **Message Broadcasting**: A Redis subscriber broadcasts received messages to all connected clients

### Functional Requirements

| ID | Requirement | Priority |
|----|-------------|----------|
| FR-1 | WebSocket endpoint at `GET /api/chat-api/ws` upgrades HTTP to WebSocket | Must |
| FR-2 | WebSocket endpoint at `GET /api/chat-api/ws/{room}` allows joining specific rooms | Must |
| FR-3 | Incoming chat messages are published to Redis pub/sub channel | Must |
| FR-4 | Redis subscriber receives messages and broadcasts to all connected clients in the room | Must |
| FR-5 | Messages without a room are broadcast to all connected clients (global) | Must |
| FR-6 | Automatic ping/pong heartbeat maintains connection health | Must |
| FR-7 | Graceful connection lifecycle with proper cleanup on disconnect | Must |

### Non-Functional Requirements

| ID | Requirement | Priority |
|----|-------------|----------|
| NFR-1 | Connection supports 64KB max message size | Must |
| NFR-2 | 60-second pong timeout for dead connection detection | Must |
| NFR-3 | 256-message send buffer per connection | Must |
| NFR-4 | Multi-pod support via Redis pub/sub | Must |
| NFR-5 | Graceful shutdown closes all connections cleanly | Must |

## Message Format

Messages follow the standard `realtime.Message` structure:

```json
{
  "id": "uuid",
  "type": "chat",
  "room": "room-name",
  "from": "client-id",
  "data": { "content": "message text" },
  "timestamp": "2024-01-15T10:30:00Z"
}
```

### Message Types

- `chat` - User chat messages
- `presence` - Online/offline status changes
- `notification` - Server notifications
- `system` - System messages
- `error` - Error messages
- `ping`/`pong` - Client-initiated heartbeat

## API Endpoints

### WebSocket Connection

```
GET /api/chat-api/ws
GET /api/chat-api/ws/{room}
GET /api/chat-api/ws?room={room}
```

**Upgrade Headers:**
- `Connection: Upgrade`
- `Upgrade: websocket`

**Response:** 101 Switching Protocols (on success)

## Configuration

| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `REDIS_URL` | Redis connection URL | `redis://localhost:6379` |
| `AUTH_ENABLED` | Require authentication for WebSocket | `false` |

## Out of Scope

- Message persistence/history
- Typing indicators
- Read receipts
- User presence tracking (beyond connection events)
- Rate limiting (future enhancement)

## Success Criteria

1. WebSocket connections can be established at `/api/chat-api/ws`
2. Messages sent by one client are received by all other connected clients
3. Room-based messaging isolates conversations
4. Multi-pod deployment correctly distributes messages via Redis
5. Connection cleanup occurs properly on disconnect

## Dependencies

- Existing `pkg/realtime` package (WebSocket handling, hub, Redis broadcaster)
- Redis server for pub/sub
- `github.com/gorilla/websocket` (already in go.mod)
- `github.com/redis/go-redis/v9` (already in go.mod)