suaveplan/openspec/archive/2026-05-26-api-sse-bun/proposal.md

# `@suaveplan/api-sse-bun` — `Bun.serve` Server-Sent Events engine

**Package**: `@suaveplan/api-sse-bun`
**Status**: PROPOSED
**Type**: new-package
**Stage**: 7 (GraphQL + WebSocket / SSE engines) — see umbrella `openspec/changes/api-plugin-foundation/`

## Why

Per design doc §11.6 SSE is the simpler cousin of WebSocket — useful for activity feeds, dashboards, and notifications where no client-to-server channel and no ack semantics are needed. SSE falls back gracefully on networks that block WebSocket (corporate proxies, restrictive firewalls), making it a deliberately important second transport. This package implements the abstract `api-sse` contract on top of `Bun.serve` and the same broker abstraction as `api-ws-bun`, so multi-host fan-out is handled by the same Redis broker (`api-ws-broker-redis`) without duplication.

Without this adapter the foundation has no production SSE story and falls back to single-transport-only deployments.

## What changes

Net-new package depending on `@suaveplan/api-types`, `@suaveplan/api-sse` (abstract contract), `@suaveplan/api-router` (HTTP endpoint mount), `@suaveplan/error`, `@suaveplan/logger`, `@suaveplan/opentelemetry`, and `zod`.

- ADDED: `createBunSseEngine(opts)` — factory returning the engine value implementing `@suaveplan/api-sse`'s contract.
- ADDED: `BunSseEngineOptions` — Zod-validated config: `eventBufferSize` (default 256 events per `(tenant, topic)`), `eventBufferMs` (default 300000 = 5 min, pairs with WS reconnect TTL), `keepAliveCommentMs` (default 15000 — emits SSE comments to prevent intermediary timeouts), `maxConnectionsPerTenant` (default 1000), `compressionEnabled` (default `true` — uses `Content-Encoding: gzip` when the client accepts it), `retryMs` (default 3000 — written into `retry:` field of the SSE stream so clients back off appropriately).
- ADDED: Endpoint mount — plugin's manifested SSE endpoints (`sse: [{ path, auth, subscriptions }]`) are mounted via `api-router` as `GET <path>` returning `Content-Type: text/event-stream`.
- ADDED: `Last-Event-Id` resume — when the client supplies `Last-Event-Id` header (HTTP standard), the engine consults the event buffer (broker-backed when Redis broker wired, in-memory otherwise) and replays events with id > supplied value before resuming live delivery.
- ADDED: Per-`(tenant, topic)` event buffer — for single-host deployments, in-memory ring buffer of `eventBufferSize` events with `eventBufferMs` TTL. For multi-host deployments, delegates to the wired broker (`api-ws-broker-redis` exposes the same buffer surface; SSE consumes it identically to WS).
- ADDED: Keep-alive comments — `:keepalive\n\n` emitted every `keepAliveCommentMs` to prevent intermediary proxy timeouts. This is invisible to clients.
- ADDED: Subscription model — `conn.subscribe(topic, { tenant?, filter? })` registers against the host's subscription bus (same bus used by WS). `bus.broadcast` triggers fan-out to SSE connections matching `(topic, tenant)`.
- ADDED: Per-tenant cap — `maxConnectionsPerTenant` enforced at request time; exceeding returns 429 with `SSE_BUN_TENANT_CAP_EXCEEDED`.
- ADDED: `SSE_BUN_*` error codes: `SSE_BUN_HANDSHAKE_REJECTED`, `SSE_BUN_TENANT_CAP_EXCEEDED`, `SSE_BUN_BUFFER_MISS`, `SSE_BUN_EVENT_TOO_LARGE`, `SSE_BUN_LAST_EVENT_ID_INVALID`, `SSE_BUN_COMPRESSION_FAILED`, `SSE_BUN_STREAM_INTERRUPTED`, `SSE_BUN_PRINCIPAL_EXPIRED`, `SSE_BUN_BROKER_UNAVAILABLE`, `SSE_BUN_INVALID_TOPIC`.
- ADDED: OTel surface from design §11.7 — `sse.connections { plugin, path, tenant }` observable gauge, `sse.events_sent_total { plugin, topic }` counter, plus this package adds `sse.handshake.duration_ms`, `sse.buffer_replays_total { hit }`, `sse.compression_ratio` histogram.
- ADDED: `./testing` subpath — re-export of `runSseEngineConformance` from `api-sse/testing` bound to `createBunSseEngine`.

## Out of scope

- A non-Bun SSE engine — the contract lives in `api-sse`; other engines can implement it.
- Cross-host fan-out logic — delegated to `api-ws-broker-redis` (which is also the SSE broker, per §11.6).
- Bi-directional channels — SSE is server→client only by design.
- Browser polyfills — modern browsers + recent Node clients support SSE natively.

## Source mapping

Genesis-original. Source of design intent: `docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md`.

| Requirement | Design doc section |
|---|---|
| SSE endpoint declared in manifest | §3 (`sse` block) + §11.6 |
| `Last-Event-Id` resume | §11.5 (paragraph 3) + §11.6 |
| Event buffer per `(tenant, topic)` with size + ttl | §11.5 (paragraph 3) |
| Shared broker with WS for multi-host fan-out | §11.6 |
| Same subscription bus as WS | §11.6 |
| OTel `sse.connections` gauge + `sse.events_sent_total` counter | §11.7 |
| Graceful fall-back when WS blocked | §11.6 |

## Verification approach

- `src/engine/bun-sse-engine.test.ts` — handshake, event emission framing, keep-alive comment cadence, principal frozen at handshake.
- `src/engine/bun-sse-engine.spec-conformance.test.ts` — runs `runSseEngineConformance("bun", createBunSseEngine)`.
- `src/last-event-id/last-event-id.test.ts` — supply `Last-Event-Id: 7`, assert events 8..N replay before live delivery.
- `src/event-buffer/event-buffer.test.ts` — in-memory mode: ring-buffer cap, TTL eviction. Broker mode (integration, 30000ms): delegation to broker-backed buffer.
- `src/limits/tenant-cap.test.ts` — 1001st connection rejected with 429.
- `src/keep-alive/keep-alive.test.ts` (FakeClock) — `:keepalive` comments emitted every `keepAliveCommentMs`.
- `tests/integration/end-to-end.test.ts` (30000ms) — real `Bun.serve`, real SSE client, full subscribe → broadcast → keep-alive → disconnect → reconnect-with-Last-Event-Id.
- `tests/integration/multi-host-fan-out.test.ts` (60000ms) — two SSE engines behind `api-ws-broker-redis`; broadcast from one delivers on the other.

## Migration impact

None — additive only.