Task_Reporter/openspec/changes/archive/2025-11-17-add-realtime-messaging/tasks.md

Implementation Tasks

1. Database Schema

• 1.1 Create messages table with columns:
  • message_id (UUID, PK)
  • room_id (FK to incident_rooms)
  • sender_id (VARCHAR, user email)
  • content (TEXT)
  • message_type (ENUM: text, image_ref, file_ref, system, incident_data)
  • metadata (JSON, for structured data and mentions)
  • created_at (TIMESTAMP)
  • edited_at (TIMESTAMP, nullable)
  • deleted_at (TIMESTAMP, nullable for soft delete)
  • sequence_number (BIGSERIAL for ordering)
• 1.2 Create message_reactions table:
  • reaction_id (SERIAL, PK)
  • message_id (FK to messages)
  • user_id (VARCHAR)
  • emoji (VARCHAR(10))
  • created_at (TIMESTAMP)
  • UNIQUE constraint on (message_id, user_id, emoji)
• 1.3 Create message_edit_history table:
  • edit_id (SERIAL, PK)
  • message_id (FK to messages)
  • original_content (TEXT)
  • edited_by (VARCHAR)
  • edited_at (TIMESTAMP)
• 1.4 Create indexes:
  • Index on messages(room_id, created_at DESC)
  • Index on messages(room_id, sequence_number)
  • Full-text index on messages(content) for search
  • Index on message_reactions(message_id)
• 1.5 Create database migration using Alembic

2. WebSocket Infrastructure

2.1 Connection Management

• 2.1.1 Create app/modules/realtime/ module structure:
  • __init__.py
  • websocket_manager.py (connection pool management)
  • models.py (message models)
  • schemas.py (WebSocket message schemas)
  • handlers.py (message type handlers)
  • router.py (WebSocket endpoint)
• 2.1.2 Implement WebSocketManager class:
  • connect(websocket, room_id, user_id) - Add connection to pool
  • disconnect(websocket, room_id, user_id) - Remove and cleanup
  • broadcast_to_room(room_id, message) - Send to all in room
  • send_personal(user_id, message) - Send to specific user
  • get_room_connections(room_id) - List active connections
• 2.1.3 Implement connection authentication:
  • Extract JWT token from WebSocket headers or query params
  • Validate token using existing auth module
  • Check room membership before allowing connection
  • Reject unauthorized connections

2.2 WebSocket Endpoint

• 2.2.1 Create WebSocket route /ws/{room_id}:
  • Accept WebSocket connection
  • Authenticate user
  • Add to connection pool
  • Listen for incoming messages
  • Handle disconnection gracefully
• 2.2.2 Implement reconnection handling:
  • Track last sequence number per connection
  • Support resume from sequence number
  • Queue messages during brief disconnections
• 2.2.3 Implement heartbeat/ping-pong:
  • Send ping every 30 seconds
  • Wait for pong response
  • Terminate stale connections

3. Message Handling

3.1 Message Models and Schemas

• 3.1.1 Create SQLAlchemy models:
  • Message model
  • MessageReaction model
  • MessageEditHistory model
• 3.1.2 Create Pydantic schemas:
  • WebSocketMessage (incoming)
  • MessageBroadcast (outgoing)
  • MessageCreate (for database)
  • MessageResponse (for REST API)
  • ReactionRequest/Response
• 3.1.3 Define message type enums:
  • MessageType (text, image_ref, file_ref, system, incident_data)
  • SystemEventType (user_joined, user_left, status_changed, etc.)

3.2 Message Processing

• 3.2.1 Create message handlers for each type:
  • handle_text_message() - Process plain text
  • handle_image_reference() - Validate and store image refs
  • handle_file_reference() - Validate and store file refs
  • handle_incident_data() - Process structured data
  • handle_system_message() - Broadcast system events
• 3.2.2 Implement mention parsing:
  • Extract @mentions from content
  • Validate mentioned users exist
  • Store mentions in metadata
• 3.2.3 Implement message validation:
  • Content length limits (10KB text, 100KB structured)
  • Rate limiting (10 messages/second per user)
  • Spam detection
  • XSS prevention (sanitize HTML)

3.3 Message Operations

• 3.3.1 Implement message editing:
  • Validate edit permission (own message, within 15 mins)
  • Store original in edit history
  • Update message content
  • Broadcast edit event
• 3.3.2 Implement message deletion:
  • Soft delete (set deleted_at)
  • Validate delete permission
  • Broadcast deletion event
• 3.3.3 Implement reactions:
  • Add/remove reactions
  • Aggregate reaction counts
  • Broadcast reaction updates

4. Message Service Layer

4.1 Message Service

• 4.1.1 Create services/message_service.py:
  • create_message(db, room_id, sender_id, content, message_type)
  • get_messages(db, room_id, limit, before_timestamp)
  • edit_message(db, message_id, user_id, new_content)
  • delete_message(db, message_id, user_id)
  • search_messages(db, room_id, query, user_id)
• 4.1.2 Implement message persistence:
  • Auto-assign sequence numbers
  • Handle concurrent writes
  • Maintain message ordering
• 4.1.3 Implement message retrieval:
  • Paginated history loading
  • Filter by message type
  • Include reaction aggregates

4.2 Reaction Service

• 4.2.1 Create services/reaction_service.py:
  • add_reaction(db, message_id, user_id, emoji)
  • remove_reaction(db, message_id, user_id, emoji)
  • get_message_reactions(db, message_id)
  • get_reaction_counts(db, message_id)

5. REST API Endpoints

5.1 Message Endpoints

• 5.1.1 Implement message REST endpoints:
  • GET /api/rooms/{room_id}/messages - Get message history
  • GET /api/rooms/{room_id}/messages/{message_id} - Get single message
  • POST /api/rooms/{room_id}/messages - Send message (alternative to WS)
  • PATCH /api/messages/{message_id} - Edit message
  • DELETE /api/messages/{message_id} - Delete message
• 5.1.2 Implement search endpoint:
  • GET /api/rooms/{room_id}/messages/search?q={query}
• 5.1.3 Implement reaction endpoints:
  • POST /api/messages/{message_id}/reactions - Add reaction
  • DELETE /api/messages/{message_id}/reactions/{emoji} - Remove reaction

5.2 Presence Endpoints

• 5.2.1 Create presence tracking:
  • GET /api/rooms/{room_id}/online - Get online users
  • GET /api/rooms/{room_id}/typing - Get typing users

6. Broadcasting System

6.1 Event Broadcasting

• 6.1.1 Create broadcast service:
  • Room-level broadcasts (all members)
  • User-level broadcasts (specific user)
  • System-wide broadcasts (all connections)
• 6.1.2 Implement event types:
  • Message events (new, edit, delete)
  • User events (joined, left, typing)
  • Room events (status changed, member added)
• 6.1.3 Create event queue:
  • Queue events during processing
  • Batch broadcasts for efficiency
  • Handle failed deliveries

6.2 Typing Indicators

• 6.2.1 Implement typing state management:
  • Track typing users per room
  • Auto-expire after 3 seconds
  • Broadcast typing events
• 6.2.2 Debounce typing events:
  • Limit typing event frequency
  • Aggregate multiple typing users

7. Client Helpers

7.1 Connection Recovery

• 7.1.1 Implement reconnection logic:
  • Exponential backoff (1s, 2s, 4s, 8s, max 30s)
  • Store last sequence number
  • Request missed messages on reconnect
• 7.1.2 Implement offline queue:
  • Queue messages while disconnected
  • Send queued messages on reconnect
  • Handle conflicts

7.2 Client SDK

• 7.2.1 Create Python client example:
  • WebSocket connection wrapper
  • Auto-reconnection
  • Message sending/receiving
• 7.2.2 Create JavaScript client example:
  • WebSocket wrapper class
  • React hooks for messages
  • TypeScript types

8. Testing

8.1 Unit Tests

• 8.1.1 Test message service:
  • Message creation with validation
  • Message ordering
  • Edit/delete permissions
  • Reaction operations
• 8.1.2 Test WebSocket manager:
  • Connection pooling
  • Broadcasting logic
  • Disconnection handling

8.2 Integration Tests

• 8.2.1 Test WebSocket flow:
  • Connect → Send → Receive → Disconnect
  • Multi-user message exchange
  • Reconnection with message recovery
• 8.2.2 Test REST endpoints:
  • Message history retrieval
  • Search functionality
  • Permission enforcement

8.3 Performance Tests

• 8.3.1 Load testing:
  • 100+ concurrent WebSocket connections
  • 1000+ messages/minute throughput
  • Message broadcast latency < 100ms
• 8.3.2 Stress testing:
  • Connection/disconnection cycling
  • Large message payloads
  • Database query performance

9. Security

9.1 Authentication & Authorization

• 9.1.1 Implement WebSocket authentication:
  • JWT token validation
  • Room membership verification
  • Permission checks for operations
• 9.1.2 Implement rate limiting:
  • Per-user message rate limits
  • Connection attempt limits
  • Global room limits

9.2 Input Validation

• 9.2.1 Sanitize message content:
  • XSS prevention
  • SQL injection prevention
  • Script injection prevention
• 9.2.2 Validate message size:
  • Enforce content length limits
  • Validate JSON structure
  • Reject malformed messages

10. Monitoring & Logging

10.1 Metrics

• 10.1.1 Track WebSocket metrics:
  • Active connections count
  • Messages per second
  • Broadcast latency
  • Error rates
• 10.1.2 Track message metrics:
  • Messages per room
  • Message types distribution
  • Edit/delete rates

10.2 Logging

• 10.2.1 Log WebSocket events:
  • Connection/disconnection
  • Authentication failures
  • Message errors
• 10.2.2 Log message operations:
  • Message sent/edited/deleted
  • Search queries
  • Permission denials

11. Documentation

11.1 API Documentation

• 11.1.1 Document WebSocket protocol:
  • Connection process
  • Message formats
  • Event types
• 11.1.2 Document REST endpoints:
  • Request/response formats
  • Error codes
  • Rate limits

11.2 Integration Guide

• 11.2.1 Client integration examples:
  • Python client code
  • JavaScript/React examples
  • Error handling patterns
• 11.2.2 Server deployment guide:
  • WebSocket configuration
  • Nginx proxy setup
  • Scaling considerations