Status: Accepted Date: 2026-04-13
Context: Clients need real-time notifications for state changes (project clone progress, session state transitions). The event stream is unidirectional (server → client) with typed events.
Decision: Use Server-Sent Events (SSE) on GET /api/v1/events for real-time event delivery.
Alternatives considered:
- WebSocket — bidirectional, but events are server-to-client only. WebSocket requires a custom protocol for typed events, reconnect logic, and Last-Event-ID replay. More complex for a unidirectional stream.
- gRPC server streaming — typed messages via protobuf, but requires a gRPC client. SSE works with any HTTP client, including browsers and
curl. - Long polling — simpler but higher latency, more connections, no built-in event ordering.
Consequences:
- SSE is native HTTP — works with browsers,
curl, and any HTTP client - Built-in
Last-Event-IDheader for reconnect replay - Named events (
event: project_state_changed) enable client-side routing - Monotonic event IDs enable ring buffer replay without gaps
- Keep-alive heartbeats (every 15s) prevent connection timeout
sync_requiredevent handles ring buffer overflow gracefully- Trade-off: SSE is unidirectional. If clients ever need to send commands via the event stream, WebSocket would be needed. Current design doesn't require this — commands go through REST endpoints.
- Trade-off: no binary encoding (events are JSON text). Acceptable for state change notifications (small payloads, infrequent).