106 lines
3.4 KiB
Markdown
106 lines
3.4 KiB
Markdown
# 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)
|