sp3-solo-1770327084/.sdlc/features/websocket-chat/spec.md

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

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