skills/plugins/document-navigator/docs/api-stack/api/api-sse-bun/README.md

@suaveplan/api-sse-bun - Bun.serve concrete engine for @suaveplan/api-sse: text/event-stream framing, Last-Event-Id replay, per-(tenant,topic) ring buffer with broker delegation, gzip streaming, keep-alive comments, per-tenant connection cap, shared subscription bus with WS engine, and the runSseEngineConformance harness bound to createBunSseEngine.

Bun.serve-backed Server-Sent Events engine for the @suaveplan/api plugin system. Implements the abstract @suaveplan/api-sse contract and passes runSseEngineConformance end-to-end. Lands at api-plugin-foundation umbrella.

SSE complements api-ws-bun: where WebSocket carries bi-directional duplex traffic, SSE is the simpler server→client stream useful for activity feeds, dashboards, notifications, and any payload pattern that does not need client→server acks. SSE also falls back gracefully on networks that block WebSocket (corporate proxies, restrictive firewalls) so a single broadcast can reach clients via either transport.

Documentation tree

• compression — The compression module owns the engine's optional gzip path. SSE streams compress well — UTF-8 text framed with repea…
  • compression — The compression module owns the engine's optional gzip path. SSE streams compress well — UTF-8 text framed with repea…
• engine — The bun-sse-engine module exports createBunSseEngine, the factory the host calls to mount Server-Sent Events on top…
  • bun-sse-engine — The bun-sse-engine module exports createBunSseEngine, the factory the host calls to mount Server-Sent Events on top…
• error-codes — The error-codes module defines the stable SSE_BUN_* error registry used across the Bun SSE engine. Every failure mo…
  • error-codes — The error-codes module defines the stable SSE_BUN_* error registry used across the Bun SSE engine. Every failure mo…
• event-buffer — The event-buffer module owns the per-(tenant, topic) replay storage the engine consults on Last-Event-Id reconnec…
  • event-buffer — The event-buffer module owns the per-(tenant, topic) replay storage the engine consults on Last-Event-Id reconnec…
• handshake — The handshake module implements the 7-step SSE handshake pipeline: topic validation, Last-Event-Id parsing, authent…
  • handshake — The handshake module implements the 7-step SSE handshake pipeline: topic validation, Last-Event-Id parsing, authent…
• instruments — The instruments module wires the engine's OpenTelemetry surface. Every metric mandated by design doc §11.7 — connecti…
  • instruments — The instruments module wires the engine's OpenTelemetry surface. Every metric mandated by design doc §11.7 — connecti…
• keep-alive — The keep-alive module emits invisible SSE comment lines on a fixed cadence so intermediary proxies (corporate gateway…
  • keep-alive — The keep-alive module emits invisible SSE comment lines on a fixed cadence so intermediary proxies (corporate gateway…
• last-event-id — The last-event-id module parses and validates the Last-Event-Id header browsers send automatically on EventSource…
  • last-event-id — The last-event-id module parses and validates the Last-Event-Id header browsers send automatically on EventSource…
• limits — The tenant-cap module owns the per-tenant SSE connection counter the engine consults during handshake. A tenant that…
  • tenant-cap — The tenant-cap module owns the per-tenant SSE connection counter the engine consults during handshake. A tenant that…
• options — The options module declares the public configuration surface accepted by createBunSseEngine and exposes `resolveOpt…
  • options — The options module declares the public configuration surface accepted by createBunSseEngine and exposes `resolveOpt…
• stream — The sse-stream module owns the byte-level framing for the SSE wire protocol. Every event the engine pushes to a clien…
  • sse-stream — The sse-stream module owns the byte-level framing for the SSE wire protocol. Every event the engine pushes to a clien…
• subscription — The subscription-bus module owns the shared fan-out surface both the WS and SSE engines plug into. The host construct…
  • subscription-bus — The subscription-bus module owns the shared fan-out surface both the WS and SSE engines plug into. The host construct…
• testing — The testing module exposes runBunSseEngineConformance — a thin binding that hands createBunSseEngine to the abstr…
  • conformance — The testing module exposes runBunSseEngineConformance — a thin binding that hands createBunSseEngine to the abstr…

Modules

• engine/bun-sse-engine — createBunSseEngine(options) factory returning the public engine value; wires options + buffer + bus + cap + instruments + handshake into one cohesive instance.
• handshake/handshake — 7-step pipeline (topic validation, Last-Event-Id parse, auth, cap acquire, compression negotiate, prologue + replay, subscribe + keep-alive).
• stream/sse-stream — WHATWG-compliant byte-level framing for id/event/data/retry/:comment lines.
• event-buffer/event-buffer — in-memory ring buffer + broker delegate behind one EventBuffer surface.
• subscription/subscription-bus — shared topic + tenant bus the WS engine reuses.
• limits/tenant-cap — per-tenant connection counter enforced at handshake time.
• compression/compression — Accept-Encoding negotiation + node:zlib streaming with sync-flush after every chunk.
• keep-alive/keep-alive — periodic :keepalive comment scheduler with injectable timer for FakeClock tests.
• last-event-id/last-event-id — header parser enforcing decimal format.
• instruments/instruments — OTel meter bundle: connections gauge, events-sent counter, handshake-duration histogram, replay-hit/miss counter, compression-ratio histogram.
• error-codes/error-codes — 10 stable SSE_BUN_* codes + SseBunError subclass.
• testing/conformance — runBunSseEngineConformance() binding to the abstract runSseEngineConformance harness.

Defaults

Knob	Default	Notes
eventBufferSize	256	Per-(tenant, topic) ring capacity.
eventBufferMs	300_000	5 min — pinned to WS reconnect window.
keepAliveCommentMs	15_000	15 s — inside the 30 s proxy idle window.
maxConnectionsPerTenant	1_000	Per-tenant cap.
maxEventBytes	65_536	64 KiB per encoded frame.
compressionEnabled	true	Honours Accept-Encoding: gzip.
retryMs	3_000	Initial retry: directive.

Boundary vs api-ws-bun

SSE is server→client only. It does not carry client→server messages, acks, or close codes — the client opens a long-lived GET, the server streams text/event-stream until the client disconnects or the server tears down. Use SSE when you need a uni-directional broadcast stream that defaults to working through restrictive intermediaries; use WS when you need duplex semantics, binary frames, or per-message acks. The two engines share the same subscription bus and event-buffer surface so the choice is per-route, not per-deploy.

Install + use

bun add @suaveplan/api-sse-bun

import { createBunSseEngine } from "@suaveplan/api-sse-bun";

const engine = createBunSseEngine({
    authenticate: async (req) => ({
        tenantId: (req.headers.get("x-tenant") ?? "anon") as never,
        principal: null,
    }),
});

Bun.serve({
    port: 0,
    async fetch(request) {
        const url = new URL(request.url);
        if (url.pathname === "/sse/audit") {
            return engine.acceptRequest({
                request: {
                    headers: request.headers,
                    url: request.url,
                    method: request.method,
                },
                path: url.pathname,
                topic: "audit",
            });
        }
        return new Response("not found", { status: 404 });
    },
});

Status

Stage-7 keystone. Conformance is pinned by the abstract runSseEngineConformance harness from @suaveplan/api-sse; this package's runBunSseEngineConformance() re-runs it bound to createBunSseEngine.