Skip to content

ADR-0003: SSE for Live Execution

Status

Accepted

Date

2026-05-13

Context

Clients of the server need to follow a test run as it executes, step by step. The backend ExecutionMonitor already emits granular events (step start, step complete, assertion result, error). Three transport options were evaluated:

  1. WebSocket: bidirectional, complex setup, requires connection management.
  2. SSE (Server-Sent Events): unidirectional server→client, simple, auto-reconnect.
  3. REST polling: simple but introduces latency and unnecessary load.

A client watching a run only needs to receive events — it never sends data back during execution.

Decision

Use Server-Sent Events via FastAPI StreamingResponse on the server. Clients consume the stream with any SSE-capable HTTP client (for example browser EventSource, or fetch with ReadableStream). Event types map directly to ExecutionMonitor event kinds.

Consequences

Positive

  • Simpler than WebSocket — no bidirectional connection management needed.
  • Standard SSE clients such as browser EventSource provide auto-reconnect.
  • No additional dependencies on the server or its clients.
  • Works through HTTP proxies and CDNs without special configuration.

Negative

  • No bidirectional messaging — if future features need client→server during execution, a separate mechanism is required.
  • Limited to ~6 concurrent connections per domain in some browsers (mitigated by HTTP/2).

Neutral

  • Event format uses standard SSE data: lines with JSON payloads.
  • Connection lifecycle tied to test execution duration.