Speckit.event Realtime

🎯 Mission

Design and implement ultra-reliable real-time communications and event-driven distributed architectures. Ensure zero message loss, strictly managed connection states, idempotent consumers, and resilient reconnection strategies across WebSockets, SSE, and Message Brokers.

📥 Required Inputs

• .agents/specs/[feature]/spec.md, plan.md, and tasks.md
• Target transport (WebSocket, Server-Sent Events, Webhooks, Message Broker)
• Event schemas, ordering guarantees, and throughput requirements

📋 Protocol

1. WebSocket Architecture (Multi-Node Scaling)

• Stateless Server Nodes: Distribute WebSocket connections across multiple server instances using Redis Pub/Sub, Redis Streams, or RabbitMQ as the central message bus backplane.
• Connection Heartbeat: Implement ping/pong heartbeat every 30 seconds. Disconnect and clean up dead sockets automatically after missed heartbeats.
• Client Resilient Reconnection: Client MUST implement Exponential Backoff with Jitter for reconnects (delay = min(max_delay, initial_delay * 2^attempt) + jitter).
• Channel / Room Scoping: Authorize channel subscriptions server-side on connection and message dispatch.

2. Server-Sent Events (SSE) for Unidirectional Streams

• Use Cases: Live LLM token streaming, notification feeds, progress dashboards.
• Headers: Set Content-Type: text/event-stream, Cache-Control: no-cache, Connection: keep-alive, X-Accel-Buffering: no (for Nginx proxy).
• Event Resumption: Track Last-Event-ID header to resume stream without data gaps during temporary client disconnection.

3. Transactional Outbox Pattern (Zero Message Loss)

• Problem Solved: Dual-write hazard where database commit succeeds but message broker publish fails (or vice versa).
• Pattern:
  1. Write domain data mutation AND outbox event record within the SAME database transaction.
  2. Dedicated asynchronous Outbox Poller / Debezium CDC worker reads unhandled events from the outbox table.
  3. Worker publishes events to Broker (RabbitMQ, Kafka, Redis Streams) and marks record as PROCESSED.

4. Idempotent Consumer & Dead Letter Queue (DLQ)

• At-Least-Once Delivery Handling: Every consumer must implement message deduplication using a unique message_id stored in Redis/DB with a TTL.
• Retry with Backoff: Failed message processing retries with progressive delay (e.g., 5s, 30s, 5m).
• Dead Letter Queue (DLQ): After maximum retry attempts (e.g. 5 failures), route the poisoned message to a DLQ and trigger an SRE alert. Never discard unprocessable messages silently.

📤 Outputs

• WebSocket gateway & Redis adapter configuration.
• SSE stream handlers with Last-Event-ID recovery.
• Transactional Outbox schema, worker daemon, and publisher services.
• Idempotent consumer workers with DLQ handling.

🚫 Guard Rails

• FORBIDDEN: Storing WebSocket room state exclusively in server memory in multi-replica deployments.
• FORBIDDEN: Publishing messages to broker outside a database transaction without an Outbox pattern when data consistency is required.
• FORBIDDEN: Discarding failed queue messages without DLQ routing.
• FORBIDDEN: Sending unauthenticated or unverified WebSocket event broadcasts.