SSE: emit periodic keepalive heartbeats so idle streams survive proxy timeouts

[EricAndrechek]

Area: streaming (api) · ops — reliability gap · found via WaveHouse-Stats dogfooding (reproduced live)

Expected: a long-lived SSE stream survives through a CDN/proxy even with no events flowing.

Actual: the handler writes : connected once (internal/api/stream.go:67) then sends nothing until an event arrives — the select loop (:116-145) has only context-done and incoming-event cases, no heartbeat ticker. On a quiet stream an intermediary (Cloudflare's edge idle-timeout, ~2 min) resets the idle HTTP/2 stream with INTERNAL_ERROR. Browser EventSource auto-reconnects so it's masked there, but curl/server-side consumers drop repeatedly and each reconnect re-runs gap-fill.

Impact (Stats): curl against /v1/stream?table=gh_events dies ~every 2 min while the table is quiet; we wrap it in a reconnect loop.

Scope: periodic SSE comment heartbeat on a ticker, added to the select loop.

Related: SSE per-subscriber channel buffer sizing #152 (same handler).

---

From WAVEHOUSE-FEEDBACK.md (WaveHouse-Stats dogfooding); validated by code-read against 0f8826c on 2026-06-04.

[coderabbitai]

🔗 Related PRs

#124 - chore(api)!: drop hub wildcard fan-out; SSE/WS use ?table= (closes #100) [merged]
#174 - refactor(table names): handle unsafe table names [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[EricAndrechek]

Reproduced live (Eric, 2026-06-04) on the public demo, server-side:

curl -N "https://stats.wavehouse.dev/v1/stream?table=gh_events"
: connected
curl: (92) HTTP/2 stream 1 was not closed cleanly: INTERNAL_ERROR (err 2)
(after 2m 5s, EC2 → Cloudflare Tunnel)

Confirms the ~2-minute idle reset — and note it's via a Cloudflare Tunnel here, not just the CDN edge, so the keepalive is needed for tunneled/proxied server-side consumers generally (not one specific CDN). Browser EventSource masks it via auto-reconnect; curl/server-side consumers don't. Trivial fix (a :\n\n heartbeat ticker in the select loop) and it's visible to anyone curling the demo, so it's a cheap launch-polish win.