Skip to content

F6.2 — Server-sent events

State Closed
Parent E6
Iteration Release 8
Start Date 2026-10-31
Closed Date 2026-11-01
Predecessors F9.8's FastAPI scaffold, for S6.2.4

Stories: 4 Closed

Story State Depends on
S6.2.1 — Approve the sse-starlette dependency Closed (2026-09-26) —
S6.2.2 — Build rn_forge.fastapi.sse Closed (2026-11-01) —
S6.2.3 — Document it Closed (2026-11-01) —
S6.2.4 — Stream from a scaffolded application Closed (2026-11-01) —

Three applications hand-rolled server-sent-event framing, each slightly differently: IntelliBuild's run stream, Apollo's job stream and PhotoTidy's event broker. sse-starlette already does the framing, heartbeat and disconnect handling correctly. This feature added a thin rn-forge-fastapi wrapper for the things it does not do.

Outcome: rn_forge.fastapi.sse.sse_response shipped on 2026-11-01 behind the sse extra. Usage is in the rn-forge-fastapi wiring guide (docs/guides/wiring.md) and the API page docs/reference/sse.md. F17.6's job-event stream is built on it.

Context

Apollo's rebuild is the concrete consumer: sse_response replaces its hand-written frame function, comment heartbeat and StreamingResponse loop. It keeps its own code until this ships and its pins move.

Design

The module is gated behind an extra because importing sse-starlette patches uvicorn.Server.handle_exit, a process-wide side effect (ADR-0003). It has no conformance case, because both framework drivers run every case with no skips and rn-forge-django has no SSE adapter. Trace Context (F4.2) removed the correlation-header parameter of the 2026-09-19 design.

S6.2.1 — Approve the sse-starlette dependency

State: Closed (2026-09-26)

Acceptance: The owner approves sse-starlette>=3.4.11 as the only dependency of a new rn-forge-fastapi[sse] extra. Approved 2026-09-26.

S6.2.2 — Build rn_forge.fastapi.sse

State: Closed (2026-11-01)

Acceptance:

  • rn-forge-fastapi declares the sse extra, and its dev and docs groups include rn-forge-fastapi[sse].
  • tests/test_sse.py covers every case listed under Design, and passes with the extra installed.
  • rn_forge.fastapi.sse is not re-exported from rn_forge.fastapi.
  • rn_forge.web.conformance.CASES gains no SSE case.
  • uv run pyright and uv run lint-imports pass.

S6.2.3 — Document it

State: Closed (2026-11-01)

Acceptance: docs/reference/sse.md exists in rn-forge-fastapi, the wiring guide has an SSE section, and the package site builds with --strict. rn-forge-web's docs are unchanged.

S6.2.4 — Stream from a scaffolded application

State: Closed (2026-11-01)

Acceptance: the FastAPI application that F9.8 scaffolds, installed with rn-forge-fastapi[sse] from built wheels, serves an sse_response endpoint; a client reads its data frames, a heartbeat, and a terminal problem frame when the generator raises.

Acceptance

set -euo pipefail
absent() { local rc=0; rg -q --hidden --glob '!.git' "$@" </dev/null || rc=$?; [ "$rc" -eq 1 ]; }
cd packages/rn-forge-fastapi
grep -q '^sse = \["sse-starlette' pyproject.toml                   # S6.2.2
uv run pytest -q tests/test_sse.py                                 # S6.2.2
absent '\bsse\b' src/rn_forge/fastapi/__init__.py                  # S6.2.2
absent 'text/event-stream|ServerSentEvent' ../rn-forge-web/src/rn_forge/web/conformance  # S6.2.2
uv run pyright && uv run lint-imports                              # S6.2.2
test -f docs/reference/sse.md                                      # S6.2.3
uv run --group docs mkdocs build --strict                          # S6.2.3

S6.2.4 runs as part of F9.8's scaffold tests.

Considered and rejected

  • A hand-written frame encoder and a framework-neutral rn_forge.web.sse module, retired by the sse-starlette evaluation on 2026-09-19.