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

WebSocket Endpoint: GET /ws upgrades HTTP connections to WebSocket
Message Publication: Incoming messages from clients are published to a Redis channel
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:

{
  "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

WebSocket connections can be established at /api/chat-api/ws
Messages sent by one client are received by all other connected clients
Room-based messaging isolates conversations
Multi-pod deployment correctly distributes messages via Redis
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)

3.4 KiB Raw Blame History