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

Implementation Tasks: WebSocket Chat with Redis Pub/Sub

Task 1: Add Redis Configuration

ID: redis-config Scope: Add Redis URL to service configuration

Files:

• services/chat-api/internal/config/config.go
• services/chat-api/.env.example

Changes:

1. Add RedisURL string field to Config struct
2. Read from REDIS_URL environment variable
3. Add REDIS_URL to .env.example with comment

Acceptance:

• Config struct has RedisURL field
• Load() reads REDIS_URL from environment
• .env.example documents the configuration

---

Task 2: Initialize Hub and Broadcaster

ID: hub-init Blocked By: redis-config Scope: Initialize realtime components in main.go

Files:

• services/chat-api/cmd/server/main.go

Changes:

1. Add context with cancel for graceful shutdown
2. Create LocalHub and start event loop
3. Create RedisBroadcaster if RedisURL configured
4. Update RegisterRoutes call to pass hub and broadcaster
5. Register shutdown hook to cancel context

Acceptance:

• Hub event loop runs in goroutine
• Redis broadcaster runs if configured
• Context cancelled on shutdown
• Service starts without errors

---

Task 3: Mount WebSocket Handler

ID: ws-routes Blocked By: hub-init Scope: Register WebSocket routes in routes.go

Files:

• services/chat-api/internal/api/routes.go

Changes:

1. Update RegisterRoutes signature to accept Hub and Broadcaster
2. Create realtime.Handler with configuration
3. Mount handler at /ws path under /api/chat-api
4. Add stats endpoint at /ws/stats

Acceptance:

• WebSocket upgrade works at /api/chat-api/ws
• Room-based endpoint at /api/chat-api/ws/{room}
• Stats endpoint returns connection count
• Auth middleware applied when AUTH_ENABLED=true

---

Task 4: Add WebSocket OpenAPI Documentation

ID: ws-openapi Blocked By: ws-routes Scope: Document WebSocket endpoints in OpenAPI spec

Files:

• services/chat-api/internal/api/spec.go

Changes:

1. Add /ws endpoint documentation (upgrade endpoint)
2. Add /ws/{room} endpoint documentation
3. Add /ws/stats endpoint with response schema
4. Document WebSocket message format in schemas

Acceptance:

• OpenAPI spec includes WebSocket endpoints
• Stats endpoint has proper response schema
• Message format documented

---

Task 5: Create WebSocket Integration Tests

ID: ws-tests Blocked By: ws-routes Scope: Test WebSocket handler functionality

Files:

• services/chat-api/internal/api/handlers/ws_test.go

Tests:

1. WebSocket connection upgrade succeeds
2. Room join via URL parameter works
3. Room join via query parameter works
4. Message broadcast to room members
5. Global message broadcast to all clients
6. Stats endpoint returns correct counts
7. Connection cleanup on disconnect

Acceptance:

• All tests pass
• Coverage includes happy path and error cases
• Tests use httptest for server simulation

---

Task Summary

ID	Task	Blocked By	Status
redis-config	Add Redis Configuration	-	pending
hub-init	Initialize Hub and Broadcaster	redis-config	pending
ws-routes	Mount WebSocket Handler	hub-init	pending
ws-openapi	Add WebSocket OpenAPI Documentation	ws-routes	pending
ws-tests	Create WebSocket Integration Tests	ws-routes	pending

Dependency Graph

redis-config
     │
     ▼
  hub-init
     │
     ▼
  ws-routes
     │
     ├─────────┐
     ▼         ▼
ws-openapi  ws-tests