@suaveplan/api-plugin-sse - Server-Sent Events plugin for @suaveplan/api. Registers a typed sseService in the host ServiceRegistry, mounts a Hono streamSSE handler with per-connection heartbeat, AbortSignal threading, backpressure, and Last-Event-ID resume from a bounded per-channel ring buffer. Server-tier.

Server-Sent Events plugin for @suaveplan/api. Registers a typed sseService in the host ServiceRegistry, mounts a Hono streaming handler at GET /sse/:channel, and ships with per-connection heartbeat, AbortSignal threading on client disconnect, Last-Event-ID resume from a bounded per-channel ring buffer, and backpressure handling with drop-oldest / drop-newest overflow policies.

Documentation tree

buffer — Bounded per-channel ring buffer that powers Last-Event-ID resume. The SSE service appends every broadcast to the buff…
- ring-buffer — Bounded per-channel ring buffer that powers Last-Event-ID resume. The SSE service appends every broadcast to the buff…
error-codes — Stable error-code registry and SseError class for @suaveplan/api-plugin-sse. Every failure path in the plugin raise…
- error-codes — Stable error-code registry and SseError class for @suaveplan/api-plugin-sse. Every failure path in the plugin raise…
fanout — Single-process publish/subscribe bus consumed by the SSE service to deliver every broadcast to every active subscriber…
- in-process — Single-process publish/subscribe bus consumed by the SSE service to deliver every broadcast to every active subscriber…
format — Serialises SseEvent objects into the text/event-stream wire format defined by the WHATWG HTML Standard so the SSE h…
parse — Async streaming parser for text/event-stream. Decodes a ReadableStreamDefaultReader<Uint8Array> into a sequence of…
middleware — Hono handler factory that turns a subscription on SseService into a streaming HTTP response framed in the `text/event…
- sse-handler — Hono handler factory that turns a subscription on SseService into a streaming HTTP response framed in the `text/event…
otel — Provides the canonical OpenTelemetry instrument bundle emitted by the SSE plugin. Counters and a histogram cover the fo…
- instruments — Provides the canonical OpenTelemetry instrument bundle emitted by the SSE plugin. Counters and a histogram cover the fo…
plugin — Factory producing a typed PluginDescriptor for the SSE plugin. Wraps the @suaveplan/api-plugin definePlugin found…
- plugin — Factory producing a typed PluginDescriptor for the SSE plugin. Wraps the @suaveplan/api-plugin definePlugin found…
registry — TypeScript module augmentation declaring the sseService slot on the @suaveplan/api-plugin/service-registry `Service…
- service-registry — TypeScript module augmentation declaring the sseService slot on the @suaveplan/api-plugin/service-registry `Service…
event — Zod schema validating the SseEvent shape accepted by SseService.broadcast. Ensures application payloads cannot bypa…
options — Zod schema validating SsePluginOptions at the factory boundary. createSsePlugin calls `SsePluginOptionsSchema.safeP…
services — Core SSE service registered under the sseService slot in the host ServiceRegistry. Owns subscription lifecycle (id…
- service — Core SSE service registered under the sseService slot in the host ServiceRegistry. Owns subscription lifecycle (id…

Install

bun add @suaveplan/api-plugin-sse

Quick start

import { Hono } from "hono";
import { createPluginRegistry } from "@suaveplan/api-plugin";
import { createSsePlugin } from "@suaveplan/api-plugin-sse";

const app = new Hono();
const registry = createPluginRegistry({ seedServices: { app } });

await registry.register(createSsePlugin({ heartbeatIntervalMs: 15_000 }));
await registry.init();

const sse = registry.getService("sseService");
setInterval(() => {
    sse?.broadcast("notifications", { data: { ts: Date.now() } });
}, 1_000);

export default app;

A browser client connects with the native EventSource:

const source = new EventSource("/sse/notifications");
source.addEventListener("message", (evt) => console.log(evt.data));

The 3-way plug-and-play contract

This package follows the canonical API-plugin pattern pioneered by @suaveplan/api-plugin-auth: a plugin is a definePlugin consumer that owns its (1) Zod schemas at the boundary, (2) optional default route registration, and (3) typed ServiceRegistry slot. Mount or compose with any other @suaveplan/api-plugin-* package by passing them to the same plugin registry.

Modules

src/error-codes/error-codes.md — stable SSE_* codes + SseError
src/buffer/ring-buffer.md — bounded per-channel ring buffer for Last-Event-ID resume
src/fanout/in-process.md — single-process pub/sub bus
src/formatter/format.md — SSE wire-format serializer
src/formatter/parse.md — streaming parser for SSE clients
src/schemas/options.md — Zod schema for plugin options
src/schemas/event.md — Zod schema for events
src/otel/instruments.md — OpenTelemetry instruments
src/services/service.md — SseService registered under sseService
src/middleware/sse-handler.md — Hono streaming handler factory
src/plugin/plugin.md — createSsePlugin factory
src/registry/service-registry.md — ServiceRegistry augmentation

Configuration

Option	Default	Description
`heartbeatIntervalMs`	`30_000`	Heartbeat comment-frame cadence per connection
`routePrefix`	`"/sse"`	Mount path for the default route (`:channel` appended)
`attachDefaultRoute`	`true`	Skip route registration to mount manually
`retentionPerChannel`	`100`	Ring-buffer size per channel for resume
`maxConnectionsPerPrincipal`	`16`	Per-principal connection cap
`maxTotalConnections`	`10_000`	Global connection cap
`queueHighWaterMark`	`256`	Per-connection backlog threshold
`overflowPolicy`	`"drop-oldest"`	`drop-oldest` or `drop-newest`
`idGenerator`	`crypto.randomUUID()`	Event id source

Observability

sse.active_connections — current open connections (UpDownCounter, channel attribute)
sse.broadcasts_total{channel} — broadcasts per channel
sse.heartbeats_total — heartbeat frames written
sse.message_bytes_total — bytes written to clients
sse.queue_overflow_total{policy,code} — events dropped under backpressure
sse.connection_duration_ms — per-connection lifetime histogram

License

MIT